---
title: Configuring the Node.js Tracing Library
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: >-
  Docs > APM > Application Instrumentation > Configure the Datadog Tracing
  Library > Configuring the Node.js 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](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md).
To verify your runtime configuration and confirm settings, view the current configuration of your service in Datadog. Navigate to the **APM Service Page**, click **Service Config**, and select the **SDK Configuration** tab.
Tracer settings can be configured with the following environment variables:

### Unified Service Tagging{% #unified-service-tagging %}

{% dl %}

{% dt %}
`DD_ENV`
{% /dt %}

{% dd %}
**Configuration**: `env`**Default**: The environment configured in the Datadog AgentSet an application's environment (for example, `prod`, `pre-prod`, and `stage`).
{% /dd %}

{% dt %}
`DD_SERVICE`
{% /dt %}

{% dd %}
**Configuration**: `service`**Default**: The `name` field in `package.json`The service name used for this application.
{% /dd %}

{% dt %}
`DD_VERSION`
{% /dt %}

{% dd %}
**Configuration**: `version`**Default**: The `version` field in `package.json`The version number of the application.
{% /dd %}

{% /dl %}

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](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md) documentation for recommendations on configuring these environment variables.

### Traces{% #traces %}

{% dl %}

{% dt %}
`DD_TRACE_ENABLED`
{% /dt %}

{% dd %}
**Configuration**: N/A**Default**: `true`Whether to enable dd-trace. Setting this to `false` disables all features of the library.See also [DD_APM_TRACING_ENABLED](https://docs.datadoghq.com/tracing/trace_collection/library_config.md#traces).
{% /dd %}

{% dt %}
`DD_TRACE_DEBUG`
{% /dt %}

{% dd %}
**Configuration**: N/A**Default**: `false`Enable debug logging in the tracer.
{% /dd %}

{% dt %}
`DD_TRACING_ENABLED`
{% /dt %}

{% dd %}
**Configuration**: N/A**Default**: `true`Whether to enable tracing.
{% /dd %}

{% dt %}
`DD_TRACE_RATE_LIMIT`
{% /dt %}

{% dd %}
**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 %}

{% dt %}
`DD_TRACE_HEADER_TAGS`
{% /dt %}

{% dd %}
**Configuration**: `headerTags`**Default**: N/AAccepts 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 %}

{% dt %}
`DD_SERVICE_MAPPING`
{% /dt %}

{% dd %}
**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 %}

{% dt %}
Flush Interval
{% /dt %}

{% dd %}
**Configuration**: `flushInterval`**Default**: `2000`Interval in milliseconds at which the tracer submits traces to the Agent.
{% /dd %}

{% dt %}
`DD_TRACE_PARTIAL_FLUSH_MIN_SPANS`
{% /dt %}

{% dd %}
**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 %}

{% dt %}
`DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP`
{% /dt %}

{% dd %}
**Configuration**: N/A**Default**: N/AA 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 %}

{% dt %}
`DD_TRACE_CLIENT_IP_HEADER`
{% /dt %}

{% dd %}
**Configuration**: N/A**Default**: N/ACustom header name to source the `http.client_ip` tag from.
{% /dd %}

{% dt %}
DNS Lookup Function
{% /dt %}

{% dd %}
**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 %}

{% dt %}
`DD_TRACE_AGENT_PROTOCOL_VERSION`
{% /dt %}

{% dd %}
**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 %}

{% dt %}
`DD_TRACE_REPORT_HOSTNAME`
{% /dt %}

{% dd %}
**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 %}

{% dt %}
`DD_TRACE_STARTUP_LOGS`
{% /dt %}

{% dd %}
**Configuration**: `startupLogs`**Default**: `false`Enable tracer startup configuration and diagnostic log.
{% /dd %}

{% dt %}
`DD_SPAN_SAMPLING_RULES_FILE`
{% /dt %}

{% dd %}
**Configuration**: N/A**Default**: N/APoints 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 %}

{% dt %}
`DD_TRACE_DISABLED_PLUGINS`
{% /dt %}

{% dd %}
**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 %}

{% dt %}
Experimental Features
{% /dt %}

{% dd %}
**Configuration**: `experimental`**Default**: `{}`Experimental features can be enabled by adding predefined keys with a value of `true`. [Contact Support](https://docs.datadoghq.com/help/) to learn more about the available experimental features.
{% /dd %}

{% dt %}
Automatically Instrument External Libraries
{% /dt %}

{% dd %}
**Configuration**: `plugins`**Default**: `true`Whether to enable automatic instrumentation of external libraries using the built-in plugins.
{% /dd %}

{% dt %}
`DD_TRACE_CLOUD_REQUEST_PAYLOAD_TAGGING`
{% /dt %}

{% dd %}
**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](https://docs.datadoghq.com/tracing/guide/aws_payload_tagging.md?code-lang=nodejs) for requests.
{% /dd %}

{% dt %}
`DD_TRACE_CLOUD_RESPONSE_PAYLOAD_TAGGING`
{% /dt %}

{% dd %}
**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](https://docs.datadoghq.com/tracing/guide/aws_payload_tagging.md?code-lang=nodejs) for responses.
{% /dd %}

{% dt %}
`DD_TRACE_CLOUD_PAYLOAD_TAGGING_MAX_DEPTH`
{% /dt %}

{% dd %}
**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](https://docs.datadoghq.com/tracing/guide/aws_payload_tagging.md?code-lang=nodejs).
{% /dd %}

{% /dl %}

### Agent{% #agent %}

{% dl %}

{% dt %}
`DD_TAGS`
{% /dt %}

{% dd %}
**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 %}

{% dt %}
`DD_TRACE_AGENT_URL`
{% /dt %}

{% dd %}
**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](https://docs.datadoghq.com/agent/configuration/network.md#configure-ports) 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 %}

{% dt %}
`DD_TRACE_AGENT_HOSTNAME`
{% /dt %}

{% dd %}
**Configuration**: `hostname`**Default**: `localhost`The address of the Agent that the tracer submits to.
{% /dd %}

{% dt %}
`DD_TRACE_AGENT_PORT`
{% /dt %}

{% dd %}
**Configuration**: `port`**Default**: `8126`The port of the Trace Agent that the tracer submits to. If the [Agent configuration](https://docs.datadoghq.com/agent/configuration/network.md#configure-ports) 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 %}

{% dt %}
`DD_DOGSTATSD_PORT`
{% /dt %}

{% dd %}
**Configuration**: `dogstatsd.port`**Default**: `8125`The port of the DogStatsD Agent that metrics are submitted to. If the [Agent configuration](https://docs.datadoghq.com/agent/configuration/network.md#configure-ports) 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 %}

{% dt %}
`DD_REMOTE_CONFIG_POLL_INTERVAL_SECONDS`
{% /dt %}

{% dd %}
**Configuration**: `remoteConfig.pollInterval`**Default**: 5Remote configuration polling interval in seconds.
{% /dd %}

{% /dl %}

### AAP{% #aap %}

{% dl %}

{% dt %}
`DD_APPSEC_ENABLED`
{% /dt %}

{% dd %}
**Configuration**: `appsec.enabled`**Default**: `false`Enable App and API Protection features.
{% /dd %}

{% dt %}
`DD_APPSEC_RULES`
{% /dt %}

{% dd %}
**Configuration**: `appsec.rules`**Default**: N/AA path to a custom AppSec rules file.
{% /dd %}

{% dt %}
`DD_APPSEC_WAF_TIMEOUT`
{% /dt %}

{% dd %}
**Configuration**: `appsec.wafTimeout`**Default**: `5000`Limits the WAF synchronous execution time (in microseconds).
{% /dd %}

{% dt %}
`DD_APPSEC_OBFUSCATION_PARAMETER_KEY_REGEXP`
{% /dt %}

{% dd %}
**Configuration**: `appsec.obfuscatorKeyRegex`**Default**: N/AA regex string to redact sensitive data by its key in attack reports.
{% /dd %}

{% dt %}
`DD_APPSEC_OBFUSCATION_PARAMETER_VALUE_REGEXP`
{% /dt %}

{% dd %}
**Configuration**: `appsec.obfuscatorValueRegex`**Default**: N/AA regex string to redact sensitive data by its value in attack reports.
{% /dd %}

{% /dl %}

### Database monitoring{% #database-monitoring %}

{% dl %}

{% dt %}
`DD_DBM_PROPAGATION_MODE`
{% /dt %}

{% dd %}
**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 %}

{% /dl %}

### Logs{% #logs %}

{% dl %}

{% dt %}
`DD_LOGS_INJECTION`
{% /dt %}

{% dd %}
**Configuration**: `logInjection`**Default**: `true`Enable automatic injection of trace IDs in logs for supported logging libraries.
{% /dd %}

{% dt %}
`DD_TRACE_LOG_LEVEL`
{% /dt %}

{% dd %}
**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`.
{% /dd %}

{% /dl %}

### OpenTelemetry{% #opentelemetry %}

{% dl %}

{% dt %}
`DD_TRACE_OTEL_ENABLED`
{% /dt %}

{% dd %}
**Configuration**: N/A**Default**: `undefined`When `true`, OpenTelemetry-based tracing for [custom](https://docs.datadoghq.com/tracing/trace_collection/custom_instrumentation/nodejs/otel.md) instrumentation is enabled.
{% /dd %}

{% /dl %}

### Profiling{% #profiling %}

{% dl %}

{% dt %}
`DD_PROFILING_ENABLED`
{% /dt %}

{% dd %}
**Configuration**: `profiling`**Default**: `false`Whether to enable profiling.
{% /dd %}

{% /dl %}

### Runtime metrics{% #runtime-metrics %}

{% dl %}

{% dt %}
`DD_RUNTIME_METRICS_ENABLED`
{% /dt %}

{% dd %}
**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 %}

{% /dl %}

### Trace context propagation{% #trace-context-propagation %}

For information about valid values and using the following configuration options, see [Propagating Node.js Trace Context](https://docs.datadoghq.com/tracing/trace_collection/trace_context_propagation.md).

{% dl %}

{% dt %}
`DD_TRACE_PROPAGATION_STYLE_INJECT`
{% /dt %}

{% dd %}
**Configuration**: `tracePropagationStyle.inject`**Default**: `Datadog,tracecontext,baggage`A comma-separated list of header formats to include to propagate distributed traces between services.
{% /dd %}

{% dt %}
`DD_TRACE_PROPAGATION_STYLE_EXTRACT`
{% /dt %}

{% dd %}
**Configuration**: `tracePropagationStyle.extract`**Default**: `Datadog,tracecontext,baggage`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 %}

{% dt %}
`DD_TRACE_PROPAGATION_STYLE`
{% /dt %}

{% dd %}
**Configuration**: `tracePropagationStyle`**Default**: `Datadog,tracecontext,baggage`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.
{% /dd %}

{% /dl %}

For more examples of how to work with the library see [API documentation](https://datadog.github.io/dd-trace-js/).

## Further Reading{% #further-reading %}

- [Source code](https://github.com/DataDog/dd-trace-js)
- [API documentation](https://datadog.github.io/dd-trace-js)
- [Propagating trace context](https://docs.datadoghq.com/tracing/trace_collection/trace_context_propagation.md)
- [Explore your services, resources and traces](https://docs.datadoghq.com/tracing/glossary.md)
- [Advanced Usage](https://docs.datadoghq.com/tracing.md)
- [OpenTelemetry Environment Variable Configurations](https://docs.datadoghq.com/opentelemetry/interoperability/environment_variable_support.md)