Configuring the Node.js Tracing Library

Docs > APM > Application Instrumentation > Configure the Datadog Tracing Library > Configuring the Node.js Tracing Library

After you set up the tracing library with your code and configure the Agent to collect APM data, optionally configure the tracing library as desired, including setting up Unified Service Tagging.

Tracer settings can be configured with the following environment variables:

Unified Service Tagging

DD_ENV: Configuration: env
Default: The environment configured in the Datadog Agent
Set an application’s environment (for example, prod, pre-prod, and stage).
DD_SERVICE: Configuration: service
Default: The name field in package.json
The service name used for this application.
DD_VERSION: Configuration: version
Default: The version field in package.json
The version number of the application.

It is recommended that you use DD_ENV, DD_SERVICE, and DD_VERSION to set env, service, and version for your services. Review the Unified Service Tagging documentation for recommendations on configuring these environment variables.

Traces

DD_TRACE_ENABLED

Configuration: N/A
Default: true
Whether to enable dd-trace. Setting this to false disables all features of the library.

DD_TRACE_DEBUG

Configuration: N/A
Default: false
Enable debug logging in the tracer.

DD_TRACING_ENABLED

Configuration: N/A
Default: true
Whether to enable tracing.

DD_TRACE_RATE_LIMIT

Configuration: rateLimit
Default: 100 when DD_TRACE_SAMPLE_RATE is set. Otherwise, delegates rate limiting to the Datadog Agent. The maximum number of traces per second per service instance.

DD_TRACE_HEADER_TAGS

Configuration: headerTags
Default: N/A
Accepts a comma-delimited list of case-insensitive HTTP headers optionally mapped to tag names. Automatically applies matching header values as tags on traces. When a tag name is not specified, it defaults to tags of the form http.request.headers.<header-name> for requests and http.response.headers.<header-name> for responses. Note: This option is only supported for HTTP/1.

Example: User-ID:userId,Request-ID

If the Request/Response has a header User-ID, its value is applied as tag userId to the spans produced by the service.
If the Request/Response has a header Request-ID, its value is applied as tag http.request.headers.Request-ID for requests and http.response.headers.Request-ID for responses.

DD_TRACE_SAMPLE_RATE

Configuration: sampleRate
Default: Defers the decision to the Agent.
Controls the ingestion sample rate (between 0.0 and 1.0) between the Agent and the backend.
Note: DD_TRACE_SAMPLE_RATE is deprecated in favor of DD_TRACE_SAMPLING_RULES.

DD_TRACE_SAMPLING_RULES

Configuration: samplingRules
Default: []
Sampling rules to apply to priority sampling. A JSON array of objects. Each object must have a sample_rate value between 0.0 and 1.0 (inclusive). Each rule has optional name and service fields, which are regex strings to match against a trace’s service and name. Rules are applied in configured order to determine the trace’s sample rate. If omitted, the tracer defers to the Agent to dynamically adjust sample rate across all traces.

DD_SERVICE_MAPPING

Configuration: serviceMapping
Default: N/A
Example: mysql:my-mysql-service-name-db,pg:my-pg-service-name-db
Provide service names for each plugin. Accepts comma separated plugin:service-name pairs, with or without spaces.

Flush Interval

Configuration: flushInterval
Default: 2000
Interval in milliseconds at which the tracer submits traces to the Agent.

DD_TRACE_PARTIAL_FLUSH_MIN_SPANS

Configuration: flushMinSpans
Default: 1000
Number of spans before partially exporting a trace. This prevents keeping all the spans in memory for very large traces.

DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP

Configuration: N/A
Default: N/A
A regex to redact sensitive data from incoming requests’ query string reported in the http.url tag (matches are replaced with <redacted>). Can be an empty string to disable redaction or .* to redact all query string. WARNING: This regex executes for every incoming request on an unsafe input (url) so make sure you use a safe regex.

DD_TRACE_CLIENT_IP_HEADER

Configuration: N/A
Default: N/A
Custom header name to source the http.client_ip tag from.

DNS Lookup Function

Configuration: lookup
Default: require('dns').lookup
Custom function for DNS lookups when sending requests to the Agent. Some setups have hundreds of services running, each doing DNS lookups on every flush interval, causing scaling issues. Override this to provide your own caching or resolving mechanism.

DD_TRACE_AGENT_PROTOCOL_VERSION

Configuration: protocolVersion
Default: 0.4
Protocol version to use for requests to the Agent. The version configured must be supported by the Agent version installed or all traces are dropped.

DD_TRACE_REPORT_HOSTNAME

Configuration: reportHostname
Default: false
Whether to report the system’s hostname for each trace. When disabled, the hostname of the Agent is used instead.

DD_TRACE_STARTUP_LOGS

Configuration: startupLogs
Default: false
Enable tracer startup configuration and diagnostic log.

DD_SPAN_SAMPLING_RULES

Configuration: spanSamplingRules
Default: []
Span sampling rules to keep individual spans when the rest of the trace would otherwise be dropped. A JSON array of objects. Rules are applied in configured order to determine the span’s sample rate. The sample_rate value must be between 0.0 and 1.0 (inclusive). For more information, see Ingestion Mechanisms.
Example:

Set the span sample rate to 50% for the service my-service and operation name http.request, up to 50 traces per second: '[{"service": "my-service", "name": "http.request", "sample_rate":0.5, "max_per_second": 50}]'

DD_SPAN_SAMPLING_RULES_FILE

Configuration: N/A
Default: N/A
Points to a JSON file that contains the span sampling rules. DD_SPAN_SAMPLING_RULES takes precedence over this variable. See DD_SPAN_SAMPLING_RULES for the rule format.

DD_TRACE_DISABLED_PLUGINS

Configuration: N/A
Default: N/A
Example: DD_TRACE_DISABLED_PLUGINS=express,dns
A comma-separated string of integration names automatically disabled when the tracer is initialized.

Experimental Features

Configuration: experimental
Default: {}
Experimental features can be enabled by adding predefined keys with a value of true. Contact Support to learn more about the available experimental features.

Automatically Instrument External Libraries

Configuration: plugins
Default: true
Whether to enable automatic instrumentation of external libraries using the built-in plugins.

Agent

DD_TAGS: Configuration: tags
Default: {}
Set global tags that are applied to all spans and runtime metrics. When passed as an environment variable, the format is key:value,key:value. When setting this programmatically, the format is tracer.init({ tags: { foo: 'bar' } }).
DD_TRACE_AGENT_URL: Configuration: url
Default: http://localhost:8126
The URL of the Trace Agent that the tracer submits to. Takes priority over hostname and port, if set. If the Agent configuration sets receiver_port or DD_APM_RECEIVER_PORT to something other than the default 8126, then DD_TRACE_AGENT_PORT or DD_TRACE_AGENT_URL must match it. Supports Unix Domain Sockets in combination with the apm_config.receiver_socket in your datadog.yaml file, or the DD_APM_RECEIVER_SOCKET environment variable.
DD_TRACE_AGENT_HOSTNAME: Configuration: hostname
Default: localhost
The address of the Agent that the tracer submits to.
DD_TRACE_AGENT_PORT: Configuration: port
Default: 8126
The port of the Trace Agent that the tracer submits to. If the Agent configuration sets receiver_port or DD_APM_RECEIVER_PORT to something other than the default 8126, then DD_TRACE_AGENT_PORT or DD_TRACE_AGENT_URL must match it.
DD_DOGSTATSD_PORT: Configuration: dogstatsd.port
Default: 8125
The port of the DogStatsD Agent that metrics are submitted to. If the Agent configuration sets dogstatsd_port or DD_DOGSTATSD_PORT to something other than the default 8125, then this tracing library DD_DOGSTATSD_PORT must match it.
DD_REMOTE_CONFIG_POLL_INTERVAL_SECONDS: Configuration: remoteConfig.pollInterval
Default: 5
Remote configuration polling interval in seconds.

ASM

DD_APPSEC_ENABLED: Configuration: appsec.enabled
Default: false
Enable Application Security Management features.
DD_APPSEC_RULES: Configuration: appsec.rules
Default: N/A
A path to a custom AppSec rules file.
DD_APPSEC_WAF_TIMEOUT: Configuration: appsec.wafTimeout
Default: 5000
Limits the WAF synchronous execution time (in microseconds).
DD_APPSEC_OBFUSCATION_PARAMETER_KEY_REGEXP: Configuration: appsec.obfuscatorKeyRegex
Default: N/A
A regex string to redact sensitive data by its key in attack reports.
DD_APPSEC_OBFUSCATION_PARAMETER_VALUE_REGEXP: Configuration: appsec.obfuscatorValueRegex
Default: N/A
A regex string to redact sensitive data by its value in attack reports.

Database monitoring

DD_DBM_PROPAGATION_MODE: Configuration: dbmPropagationMode
Default: 'disabled'
To enable DBM to APM link using tag injection, can be set to 'service' or 'full'. The 'service' option enables the connection between DBM and APM services. The 'full' option enables connection between database spans with database query events. Available for Postgres.

Logs

DD_LOGS_INJECTION: Configuration: logInjection
Default: false
Enable automatic injection of trace IDs in logs for supported logging libraries.
DD_TRACE_LOG_LEVEL: Configuration: logLevel
Default: debug
A string for the minimum log level for the tracer to use when debug logging is enabled, for example, error, debug.

OpenTelemetry

DD_TRACE_OTEL_ENABLED: Configuration: N/A
Default: undefined
When true, OpenTelemetry-based tracing for custom instrumentation is enabled.

Profiling

DD_PROFILING_ENABLED: Configuration: profiling
Default: false
Whether to enable profiling.

Runtime metrics

DD_RUNTIME_METRICS_ENABLED: Configuration: runtimeMetrics
Default: false
Whether to enable capturing runtime metrics. Port 8125 (or configured with DD_DOGSTATSD_PORT) must be opened on the Agent for UDP.

Trace context propagation

For information about valid values and using the following configuration options, see Propagating Node.js Trace Context.

DD_TRACE_PROPAGATION_STYLE_INJECT: Configuration: tracePropagationStyle.inject
Default: Datadog,tracecontext
A comma-separated list of header formats to include to propagate distributed traces between services.
DD_TRACE_PROPAGATION_STYLE_EXTRACT: Configuration: tracePropagationStyle.extract
Default: Datadog,tracecontext
A comma-separated list of header formats from which to attempt to extract distributed tracing propagation data. The first format found with complete and valid headers is used to define the trace to continue.
DD_TRACE_PROPAGATION_STYLE: Configuration: tracePropagationStyle
Default: Datadog,tracecontext
A comma-separated list of header formats from which to attempt to inject and extract distributed tracing propagation data. The first format found with complete and valid headers is used to define the trace to continue. The more specific DD_TRACE_PROPAGATION_STYLE_INJECT and DD_TRACE_PROPAGATION_STYLE_EXTRACT configurations take priority when present.