Tracing Node.js Applications

Compatibility requirements

The latest Node.js Tracer supports versions >=14. For a full list of Datadog’s Node.js version and framework support (including legacy and maintenance versions), see the Compatibility Requirements page.

Installation and getting started

Follow the in-app documentation (recommended)

Follow the Quick start instructions in Datadog 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 the Continuous Profiler, ingesting 100% of traces, and Trace ID injection into logs during setup.

Configure the Datadog Agent for APM

Install and configure the Datadog Agent to receive traces from your instrumented application. By default the Datadog Agent is enabled in your datadog.yaml file under apm_config with enabled: true and listens for trace data at http://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:

The tracing client sends traces to localhost:8126 by default. If this is not the correct host and port for your Agent, set the DD_TRACE_AGENT_HOSTNAME and DD_TRACE_AGENT_PORT environment variables by running:
```
DD_TRACE_AGENT_HOSTNAME=<HOSTNAME> DD_TRACE_AGENT_PORT=<PORT> node server
```
To use Unix domain sockets, specify the entire URL as a single environment variable, DD_TRACE_AGENT_URL.
If you require a different socket, host, or port, use the DD_TRACE_AGENT_URL environment variable or the DD_TRACE_AGENT_HOST and DD_TRACE_AGENT_PORT environment variables. Some examples:
```
DD_AGENT_HOST=<HOSTNAME> DD_TRACE_AGENT_PORT=<PORT> node server
DD_TRACE_AGENT_URL=http://<HOSTNAME>:<PORT> node server
DD_TRACE_AGENT_URL=unix:<SOCKET_PATH> node server
```

To set up Datadog APM in AWS Lambda, see the Tracing Serverless Functions documentation.

Tracing is available for other environments, including Heroku, Cloud Foundry, and AWS Elastic Beanstalk.

For other environments, see the Integrations documentation for that environment and contact support if you encounter setup issues.

Read tracer settings for a list of initialization options.

Instrument your application

If you are collecting traces from a Kubernetes application, or from an application on a Linux host or container, as an alternative to the following instructions, you can inject the tracing library into your application. Read Injecting Libraries for instructions.

After the Agent is installed, follow these steps to add the Datadog tracing library to your Node.js applications:

Install the Datadog Tracing library using npm for Node.js 14+:
```
npm install dd-trace --save
```
If you need to trace end-of-life Node.js version 12, install version 2.x of dd-trace by running:
```
npm install dd-trace@latest-node12
```
For more information on our distribution tags and Node.js runtime version support, see the Compatibility Requirements page. If you are upgrading from a previous major version of the library (0.x, 1.x, or 2.x) to another major version (2.x or 3.x), read the Migration Guide to assess any breaking changes.
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.

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.

import 'dd-trace/init';

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.

Configuration

If needed, configure the tracing library to send application performance telemetry data as you require, including setting up Unified Service Tagging. Read Library Configuration for details.