Compatibility requirements
The latest version of the NodeJS Tracer officially supports versions >=12
. Versions 8
and 10
are supported in maintenance mode on the 0.x
release line. For more information about our Node version support and the supported versions, see the Compatibility Requirements page.
Installation and getting started
To add the Datadog tracing library to your Node.js applications, follow these steps:
Install the Datadog Tracing library using npm for Node.js 12+:
npm install dd-trace --save
If you need to trace end-of-life Node.js versions 10 or 8, install version 0.x of dd-trace
by running:
npm install dd-trace@latest-node10
or
npm install dd-trace@latest-node8
For more information on our distribution tags and Node.js runtime version support, see the Compatibility Requirements page.
Import and initialize the tracer either in code or via command line arguments. The Node.js tracing library needs to be imported and initialized before any other module.
Once you have completed setup, if you are not receiving complete traces, including missing URL routes for web requests, or disconnected or missing spans, confirm step 2 has been correctly done. The tracing library being initialized first is necessary for the tracer to properly patch all of the required libraries for automatic instrumentation.
When using a transpiler such as TypeScript, Webpack, Babel, or others, import and initialize the tracer library in an external file and then import that file as a whole when building your application.
Configure the Datadog Agent for APM
Add any desired configuration to the tracer, such as service
, env
, and version
for Unified Service Tagging.
Adding the tracer in code
JavaScript
// This line must come before importing any instrumented module.
const tracer = require('dd-trace').init();
TypeScript and bundlers
For TypeScript and bundlers that support EcmaScript Module syntax, initialize the tracer in a separate file in order to maintain correct load
order.
// 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;
If the default config is sufficient, or all configuration is done
via environment variables, you can also use dd-trace/init
, which loads and
initializes in one step.
Adding the tracer via command line arguments
Use the --require
option to Node.js to load and initialize the tracer in one
step.
node --require dd-trace/init app.js
Note: This approach requires using environment variables for all
configuration of the 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_config
with 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.
Set apm_non_local_traffic: true
in the apm_config
section of 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:
After having instrumented your application, the tracing client sends traces to localhost:8126
by default. If this is not the correct host and port change it by setting the below env variables:
DD_AGENT_HOST
and DD_TRACE_AGENT_PORT
.
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
.
DD_TRACE_AGENT_URL=unix:<SOCKET_PATH> node server
- Set
DD_SITE
in the Datadog Agent to
to ensure the Agent sends data to the right Datadog location.
See the tracer settings for the list of initialization options.
Configuration
Tracer settings can be configured with the following environment variables:
Tagging
DD_ENV
- Set an application’s environment (for example,
prod
, pre-prod
, and stage
). Defaults to the environment configured in the Datadog Agent. DD_SERVICE
- The service name used for this program. Defaults to the name field value in
package.json
. DD_VERSION
- The version number of the application. Defaults to the version field value in
package.json
. DD_TAGS
- 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 how to configure these environment variables.
Instrumentation
DD_TRACE_ENABLED
- Default:
true
Whether to enable the tracer. DD_TRACE_DEBUG
- Default:
false
Enable debug logging in the tracer. DD_TRACE_AGENT_URL
- Default:
http://localhost:8126
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 apm_config.receiver_socket
in your datadog.yaml
file, or the DD_APM_RECEIVER_SOCKET
environment variable. DD_TRACE_AGENT_HOSTNAME
- Default:
localhost
The address of the Agent that the tracer submits to. DD_TRACE_AGENT_PORT
- Default:
8126
The port of the Trace Agent that the tracer submits to. DD_DOGSTATSD_PORT
- Default:
8125
The port of the DogStatsD Agent that metrics are submitted to. DD_LOGS_INJECTION
- Default:
false
Enable automatic injection of trace IDs in logs for supported logging libraries. DD_TRACE_SAMPLE_RATE
- Percentage of spans to sample as a float between
0
and 1
. Defaults to the rates returned by the Datadog Agent. DD_TRACE_RATE_LIMIT
- Percentage of spans to sample as a float between
0
and 1
. Defaults to 100
when DD_TRACE_SAMPLE_RATE
is set. Otherwise, delegates rate limiting to the Datadog Agent. DD_RUNTIME_METRICS_ENABLED
- 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
- 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
- A comma-separated string of integration names automatically disabled when tracer is initialized. Environment variable only, for example,
DD_TRACE_DISABLED_PLUGINS=express,dns
. DD_TRACE_LOG_LEVEL
- Default:
debug
A string for the minimum log level for the tracer to use when debug logging is enabled, for example, error
, debug
.
For more options including the programmatic configuration API, see the API documentation.
Further Reading
Additional helpful documentation, links, and articles: