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:

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.
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' } }).

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.

Instrumentation

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_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_LOGS_INJECTION
Configuration: logInjection
Default: false
Enable automatic injection of trace IDs in logs for supported logging libraries.
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.
DD_TRACE_RATE_LIMIT
Configuration: rateLimit
Default: 1.0 when DD_TRACE_SAMPLE_RATE is set. Otherwise, delegates rate limiting to the Datadog Agent. Ratio of spans to sample as a float between 0.0 and 1.0.
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_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_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.
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.
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.
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.
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_PROFILING_ENABLED
Configuration: profiling
Default: false
Whether to enable profiling.
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.
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.
DD_TRACE_STARTUP_LOGS
Configuration: startupLogs
Default: false
Enable tracer startup configuration and diagnostic log.
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.
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.
DD_REMOTE_CONFIG_POLL_INTERVAL_SECONDS
Configuration: remoteConfig.pollInterval
Default: 5
Remote configuration polling interval in seconds.

For more examples of how to work with the library see API documentation.

Further Reading