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.

DD_TRACE_CLOUD_REQUEST_PAYLOAD_TAGGING

Configuration: cloudPayloadTagging.request
Default: N/A (disabled)
Example: DD_TRACE_CLOUD_REQUEST_PAYLOAD_TAGGING=$.Metadata.UserId
A comma-separated string of JSONPath entries to redact from AWS SDK requests. Setting this enables AWS payload tagging for requests.

DD_TRACE_CLOUD_RESPONSE_PAYLOAD_TAGGING

Configuration: cloudPayloadTagging.response
Default: N/A (disabled)
Example: DD_TRACE_CLOUD_RESPONSE_PAYLOAD_TAGGING=$.Metadata.UserId
A comma-separated string of JSONPath entries to redact from AWS SDK responses. Setting this enables AWS payload tagging for responses.

DD_TRACE_CLOUD_PAYLOAD_TAGGING_MAX_DEPTH

Configuration: cloudPayloadTagging.maxDepth
Default: 10
Example: DD_TRACE_CLOUD_PAYLOAD_TAGGING_MAX_DEPTH=10
An integer representing the maximum depth of an AWS SDK request/reponse payload to use for AWS payload tagging.

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.

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

Further Reading

Documentation, liens et articles supplémentaires utiles:

Source codeSOURCE CODE API documentationDOCUMENTATION Propagating trace contextDOCUMENTATION Explore your services, resources and tracesDOCUMENTATION Advanced UsageDOCUMENTATION OpenTelemetry Environment Variable ConfigurationsDOCUMENTATION