Tracing Node.js Applications
New announcements from Dash: Incident Management, Continuous Profiler, and more! New announcements from Dash!

Tracing Node.js Applications

Compatibilty Requirements

The NodeJS Tracer officially supports versions >=8. Only even versions like 8.x and 10.x are officially supported. Odd versions like 9.x and 11.x should work but are not officially supported. For a full list of supported libraries, visit the Compatibility Requirements page.

Installation and getting started

Follow the Quickstart instructions within the Datadog app for the best experience, including:

  • Step-by-step instructions scoped to your deployment configuration (hosts, Docker, Kubernetes, or Amazon ECS).
  • Dynamically set service, env, and version tags.
  • Enable App Analytics and Trace ID injection into logs during setup.

For descriptions of terminology used in APM, take a look at the official documentation.

For details about configuration and using the API, see Datadog’s API documentation.

For details about contributing, check out the development guide.


This library MUST be imported and initialized before any instrumented module. When using a transpiler, you MUST import and initialize the tracer library in an external file and then import that file as a whole when building your application. This prevents hoisting and ensures that the tracer library gets imported and initialized before importing any other instrumented module.

To begin tracing Node.js applications, first install and configure the Datadog Agent, see the additional documentation for tracing Docker applications or Kubernetes applications.

Next, install the Datadog Tracing library using npm:

npm install --save dd-trace

Finally, import and initialize the tracer:

// This line must come before importing any instrumented module.
const tracer = require('dd-trace').init();
// server.ts
import './tracer'; // must come before importing any instrumented module.

// tracer.ts
import tracer from 'dd-trace';
tracer.init(); // initialized in a different file to avoid hoisting.
export default tracer;

See the tracer settings for the list of initialization options.


Tracer settings can be configured as a parameter to the init() method or as environment variables.


ConfigEnvironment VariableDefaultDescription
envDD_ENVnullSet an application’s environment e.g. prod, pre-prod, stage, etc. Available for versions 0.20+
serviceDD_SERVICEnullThe service name to be used for this program. Available for versions 0.20+
versionDD_VERSIONnullThe version number of the application. Defaults to value of the version field in package.json. Available for versions 0.20+
tagsDD_TAGS{}Set global tags that should be applied to all spans and metrics. When passed as an environment variable, the format is key:value,key:value. When setting this programmatically: tracer.init({ tags: { foo: 'bar' } }) Available for versions 0.20+

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 how to configure these environment variables.


ConfigEnvironment VariableDefaultDescription
enabledDD_TRACE_ENABLEDtrueWhether to enable the tracer.
debugDD_TRACE_DEBUGfalseEnable debug logging in the tracer.
urlDD_TRACE_AGENT_URLnullThe URL of the Trace Agent that the tracer submits to. Takes priority over hostname and port, if set. 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.
hostnameDD_TRACE_AGENT_HOSTNAMElocalhostThe address of the Agent that the tracer submits to.
portDD_TRACE_AGENT_PORT8126The port of the Trace Agent that the tracer submits to.
dogstatsd.portDD_DOGSTATSD_PORT8125The port of the DogStatsD Agent that metrics are submitted to.
logInjectionDD_LOGS_INJECTIONfalseEnable automatic injection of trace IDs in logs for supported logging libraries.
sampleRate-1Percentage of spans to sample as a float between 0 and 1.
flushInterval-2000Interval (in milliseconds) at which the tracer submits traces to the Agent.
runtimeMetricsDD_RUNTIME_METRICS_ENABLEDfalseWhether to enable capturing runtime metrics. Port 8125 (or configured with dogstatsd.port) must be opened on the Agent for UDP.
experimental-{}Experimental features can be enabled all at once using Boolean true or individually using key/value pairs. Contact support to learn more about the available experimental features.
plugins-trueWhether or not to enable automatic instrumentation of external libraries using the built-in plugins.
-DD_TRACE_DISABLED_PLUGINS-A comma-separated string of integration names automatically disabled when tracer is initialized. Environment variable only e.g. DD_TRACE_DISABLED_PLUGINS=express,dns.
clientTokenDD_CLIENT_TOKENnullClient token for browser tracing. Can be generated in Datadog in Integrations -> APIs.
logLevelDD_TRACE_LOG_LEVELdebugA string for the minimum log level for the tracer to use when debug logging is enabled, e.g. error, debug.

Change Agent Hostname

Configure your application level tracers to submit traces to a custom Agent hostname:

The NodeJS Tracing Module automatically looks for and initializes with the ENV variables DD_AGENT_HOST and DD_TRACE_AGENT_PORT


To use a different protocol such as UDS, specify the entire URL as a single ENV variable DD_TRACE_AGENT_URL.


Further Reading