Configuration options

All options are passed to tracer.init(). Environment variables take effect when the programmatic option is not set. Programmatic configuration always takes precedence over environment variables.

const tracer = require('dd-trace').init({
  service: 'my-api',
  env: 'production',
  version: '1.0.0',
})

General

service

string

The service name for this application. If not set, dd-trace attempts to infer it from package.json. In serverless environments it is inferred from the function name environment variable.Env: DD_SERVICE, OTEL_SERVICE_NAME

env

string

The environment name (e.g., prod, staging, development). Appears as the env tag on all spans.Env: DD_ENV

version

string

The application version. If not set, dd-trace attempts to infer it from package.json.Env: DD_VERSION

hostname

string

default:"127.0.0.1"

The hostname of the Datadog Agent. Overridden by url if both are set.Env: DD_AGENT_HOST

port

number | string

default:"8126"

The port of the Datadog Agent.Env: DD_TRACE_AGENT_PORT

url

string

The full URL of the Datadog Agent (e.g., http://localhost:8126). Takes priority over hostname and port.Env: DD_TRACE_AGENT_URL

Tracing

flushInterval

number

default:"2000"

Interval in milliseconds at which the tracer submits traces to the Agent. In Lambda environments this is automatically set to 0 (flush synchronously).Env: DD_TRACE_FLUSH_INTERVAL

flushMinSpans

number

default:"1000"

Number of spans before partially exporting a trace. Prevents very large traces from being held entirely in memory.Env: DD_TRACE_PARTIAL_FLUSH_MIN_SPANS

tracePropagationStyle

string[] | PropagationStyle

Context propagation formats for injection and extraction. Accepts an array of format names (datadog, tracecontext, b3, b3 single header, none) or an object with separate inject and extract arrays.

tracePropagationStyle: ['datadog', 'tracecontext']
// or
tracePropagationStyle: {
  inject: ['datadog', 'tracecontext'],
  extract: ['datadog', 'tracecontext', 'b3'],
}

Env: DD_TRACE_PROPAGATION_STYLE, DD_TRACE_PROPAGATION_STYLE_INJECT, DD_TRACE_PROPAGATION_STYLE_EXTRACT

headerTags

string[]

HTTP request headers to capture as span tags. Each entry is a header name; the tag name will be http.request.headers.<name>.Env: DD_TRACE_HEADER_TAGS

dbmPropagationMode

string

default:"disabled"

Database Monitoring to APM link mode. One of disabled, service, or full.Env: DD_DBM_PROPAGATION_MODE

dsmEnabled

boolean

default:"false"

Whether to enable Data Streams Monitoring.Env: DD_DATA_STREAMS_ENABLED

clientIpEnabled

boolean

default:"false"

Collect client IP from incoming request headers and tag spans with http.client_ip.Env: DD_TRACE_CLIENT_IP_ENABLED

clientIpHeader

string

Custom header name from which to read the client IP. Takes precedence over automatic detection.Env: DD_TRACE_CLIENT_IP_HEADER

Sampling

sampleRate

number

Global trace sample rate, between 0 (drop all) and 1 (keep all). When not set, the Agent determines the rate via priority sampling.Env: DD_TRACE_SAMPLE_RATE, OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG

rateLimit

number

Global rate limit (traces per second) applied after sampling rules. Defaults to deferring the decision to the Agent.Env: DD_TRACE_RATE_LIMIT

samplingRules

SamplingRule[]

default:"[]"

Array of sampling rules applied to priority sampling. Each rule specifies sampleRate and optionally service (string or regex) and name (string or regex).

samplingRules: [
  { service: 'my-api', name: 'express.request', sampleRate: 1.0 },
  { service: /^worker-/, sampleRate: 0.1 },
]

Env: DD_TRACE_SAMPLING_RULES (JSON array)

spanSamplingRules

SpanSamplingRule[]

default:"[]"

Span sampling rules that keep individual spans from dropped traces. Each rule specifies optional service, name, sampleRate (default 1.0), and maxPerSecond.

spanSamplingRules: [
  { service: 'my-api', name: 'redis.command', sampleRate: 1.0, maxPerSecond: 50 },
]

Env: DD_SPAN_SAMPLING_RULES, DD_SPAN_SAMPLING_RULES_FILE

Log injection

logInjection

boolean

default:"false"

Inject dd.trace_id, dd.span_id, dd.service, dd.env, and dd.version fields into log records automatically. Works with supported logging libraries (winston, bunyan, pino, etc.).Env: DD_LOGS_INJECTION

Runtime metrics

runtimeMetrics

boolean | object

default:"false"

Enable runtime metrics collection. Can be a boolean or an object to control individual metric types:

runtimeMetrics: true
// or
runtimeMetrics: {
  enabled: true,
  gc: true,         // garbage collection metrics
  eventLoop: true,  // event loop lag metrics
}

Env: DD_RUNTIME_METRICS_ENABLED, DD_RUNTIME_METRICS_GC_ENABLED, DD_RUNTIME_METRICS_EVENT_LOOP_ENABLED

dogstatsd

object

Configuration for the DogStatsD agent that receives runtime metrics.

dogstatsd: {
  hostname: 'localhost', // DD_DOGSTATSD_HOST
  port: 8125,            // DD_DOGSTATSD_PORT
}

Profiling

profiling

boolean

default:"false"

Enable continuous profiling. Sends CPU, heap, and wall-time profiles to Datadog Profiling.Env: DD_PROFILING_ENABLED

AppSec

appsec

boolean | object

default:"false"

Enable Application Security Monitoring. Can be a boolean or a configuration object:

appsec: true
// or
appsec: {
  enabled: true,
  rules: '/path/to/custom-rules.json',
  rateLimit: 100,
  wafTimeout: 5000,
  obfuscatorKeyRegex: 'password|secret',
  obfuscatorValueRegex: undefined,
  rasp: { enabled: false },
  stackTrace: {
    enabled: true,
    maxStackTraces: 2,
    maxDepth: 32,
  },
  eventTracking: {
    mode: 'identification', // 'anonymous' | 'identification' | 'disabled'
  },
  apiSecurity: {
    enabled: true,
    endpointCollectionEnabled: true,
  },
}

Env: DD_APPSEC_ENABLED

IAST

iast

boolean | object

default:"false"

Enable Interactive Application Security Testing. Can be a boolean or a configuration object. IAST detects code-level vulnerabilities at runtime.Env: DD_IAST_ENABLED

Remote configuration

remoteConfig

object

Configuration for Remote Config, which allows updating tracer settings without redeployment.

remoteConfig: {
  pollInterval: 5, // seconds between polls, DD_REMOTE_CONFIG_POLL_INTERVAL_SECONDS
}

Env: DD_REMOTE_CONFIGURATION_ENABLED, DD_REMOTE_CONFIG_POLL_INTERVAL_SECONDS

Code origin for spans

codeOriginForSpans

object

Attach the source code location where a span was created to the span metadata.

codeOriginForSpans: { enabled: true }

Env: DD_CODE_ORIGIN_FOR_SPANS_ENABLED

Cloud payload tagging

cloudPayloadTagging

object

Tag cloud provider request/response payloads using JSONPath queries.

cloudPayloadTagging: {
  request: '$.Body',
  response: '$.StatusCode',
}

Env: DD_TRACE_CLOUD_REQUEST_PAYLOAD_TAGGING, DD_TRACE_CLOUD_RESPONSE_PAYLOAD_TAGGING

Dynamic Instrumentation

dynamicInstrumentation

object

Configuration for Dynamic Instrumentation (Live Debugging). Allows adding log probes and metric probes to running applications without redeployment.

dynamicInstrumentation: {
  enabled: true,
  captureTimeoutMs: 15,       // timeout for variable capture (default: 15ms)
  uploadIntervalSeconds: 1,   // interval between probe data uploads (default: 1s)
  redactedIdentifiers: [],    // additional identifiers to redact
  redactionExcludedIdentifiers: [], // identifiers to exclude from built-in redaction
  probeFile: '/path/to/probes.json', // path to local probes config file
}

Env: DD_DYNAMIC_INSTRUMENTATION_ENABLED, DD_DYNAMIC_INSTRUMENTATION_CAPTURE_TIMEOUT_MS, DD_DYNAMIC_INSTRUMENTATION_UPLOAD_INTERVAL_SECONDS, DD_DYNAMIC_INSTRUMENTATION_REDACTED_IDENTIFIERS, DD_DYNAMIC_INSTRUMENTATION_REDACTION_EXCLUDED_IDENTIFIERS, DD_DYNAMIC_INSTRUMENTATION_PROBE_FILE

Runtime metrics (additional)

runtimeMetricsRuntimeId

boolean

default:"false"

Whether to add an auto-generated runtime-id tag to runtime metrics. Useful for correlating metrics from the same process instance.Env: DD_RUNTIME_METRICS_RUNTIME_ID_ENABLED

Database Monitoring (DBM)

dbm

object

Advanced Database Monitoring configuration.

dbm: {
  injectSqlBaseHash: false, // inject SQL base hash in DBM comments for process tag correlation
}

Env: DD_DBM_INJECT_SQL_BASEHASH

injectSqlBaseHash requires DD_EXPERIMENTAL_PROPAGATE_PROCESS_TAGS_ENABLED=true to take effect.

Experimental options

experimental

object

Experimental features enabled individually. These may change or be removed without a major version bump.

experimental: {
  exporter: 'agent', // 'log' | 'agent' | 'datadog'
  enableGetRumData: false,
  b3: false,
  aiguard: {
    enabled: false,        // DD_AI_GUARD_ENABLED
    endpoint: undefined,   // DD_AI_GUARD_ENDPOINT
    timeout: 5000,         // DD_AI_GUARD_TIMEOUT (ms)
    maxMessagesLength: undefined, // DD_AI_GUARD_MAX_MESSAGES_LENGTH
    maxContentSize: undefined,    // DD_AI_GUARD_MAX_CONTENT_SIZE
  },
  flaggingProvider: {
    enabled: false,               // DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED
    initializationTimeoutMs: 30000, // DD_EXPERIMENTAL_FLAGGING_PROVIDER_INITIALIZATION_TIMEOUT_MS
  },
}

Env: DD_TRACE_EXPERIMENTAL_EXPORTER, DD_TRACE_EXPERIMENTAL_GET_RUM_DATA_ENABLED, DD_TRACE_EXPERIMENTAL_B3_ENABLED

Introduction

Installation

Configuration

General

Tracing

Sampling

Log injection

Runtime metrics

Profiling

AppSec

IAST

Remote configuration

Code origin for spans

Cloud payload tagging

Dynamic Instrumentation

Runtime metrics (additional)

Database Monitoring (DBM)

Experimental options

Build docs developers (and LLMs) love

Introduction

Installation

Configuration

Documentation Index

​General

​Tracing

​Sampling

​Log injection

​Runtime metrics

​Profiling

​AppSec

​IAST

​Remote configuration

​Code origin for spans

​Cloud payload tagging

​Dynamic Instrumentation

​Runtime metrics (additional)

​Database Monitoring (DBM)

​Experimental options

Build docs developers (and LLMs) love

General

Tracing

Sampling

Log injection

Runtime metrics

Profiling

AppSec

IAST

Remote configuration

Code origin for spans

Cloud payload tagging

Dynamic Instrumentation

Runtime metrics (additional)

Database Monitoring (DBM)

Experimental options