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.
Follow the Quickstart instructions within the Datadog app for the best experience, including:
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.
To begin tracing Node.js applications, install the Datadog Tracing library using npm:
npm install --save dd-trace
Next, 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;
Install and configure the Datadog Agent to receive traces from your now instrumented application. By default the Datadog Agent is enabled in your
datadog.yaml file under
apm_enabled: true and listens for trace traffic at
localhost:8126. For containerized environments, follow the links below to enable trace collection within the Datadog Agent.
apm_non_local_traffic: true in your main
datadog.yaml configuration file
See the specific setup instructions to ensure that the Agent is configured to receive traces in a containerized environment:
localhost:8126by default. If this is not the correct host and port change it by setting the below env variables:
DD_AGENT_HOST=<HOSTNAME> DD_TRACE_AGENT_PORT=<PORT> node server
To use a different protocol such as UDS, specify the entire URL as a single ENV variable
DD_TRACE_AGENT_URL=unix:<SOCKET_PATH> node server
To set up Datadog APM in AWS Lambda, see the Tracing Serverless Functions documentation.
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.
|env||Set an application’s environment e.g. |
|service||The service name to be used for this program. Available for versions 0.20+|
|version||The version number of the application. Defaults to value of the version field in package.json. Available for versions 0.20+|
|tags||Set global tags that should be applied to all spans and runtime metrics. When passed as an environment variable, the format is |
It is recommended that you use
DD_VERSION to set
version for your services. Review the Unified Service Tagging documentation for recommendations on how to configure these environment variables.
|enabled||Whether to enable the tracer.|
|debug||Enable debug logging in the tracer.|
|url||The 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 |
|hostname||The address of the Agent that the tracer submits to.|
|port||The port of the Trace Agent that the tracer submits to.|
|dogstatsd.port||The port of the DogStatsD Agent that metrics are submitted to.|
|logInjection||Enable automatic injection of trace IDs in logs for supported logging libraries.|
|sampleRate||-||Percentage of spans to sample as a float between |
|flushInterval||-||Interval (in milliseconds) at which the tracer submits traces to the Agent.|
|runtimeMetrics||Whether to enable capturing runtime metrics. Port |
|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||-||Whether or not to enable automatic instrumentation of external libraries using the built-in plugins.|
|-||-||A comma-separated string of integration names automatically disabled when tracer is initialized. Environment variable only e.g. |
|clientToken||Client token for browser tracing. Can be generated in Datadog in Integrations -> APIs.|
|logLevel||A string for the minimum log level for the tracer to use when debug logging is enabled, e.g. |
Additional helpful documentation, links, and articles: