Datadog Synthetics is now available!

Tracing Node.js Applications

Installation And Getting Started

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.

Quickstart

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:

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

// tracer.js
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.

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

const tracer = require('dd-trace').init({
  hostname: process.env.DD_AGENT_HOST,
  port: process.env.DD_TRACE_AGENT_PORT
})

Compatibility

Node ^4.7, ^6.9 and >=8 are supported by this library. However, it benefits significantly from the performance improvements introduced in Node >=8.3.

Integrations

APM provides out-of-the-box instrumentation for many popular frameworks and libraries by using a plugin system. If you would like support for a module that is not listed, contact support to share a request.

For details about how to how to toggle and configure plugins, check out the API documentation.

Web Framework Compatibility

Module Versions Support Type Notes
express >=4 Fully Supported Supports Sails, Loopback, and more
graphql >=0.10 Fully Supported Supports Apollo Server and express-graphql
hapi >=2 Fully Supported
koa >=2 Fully Supported
restify >=3 Fully Supported

Native Module Compatibility

Module Support Type
dns Fully Supported
http Fully Supported
https Fully Supported
net Fully Supported

Data Store Compatibility

Module Versions Support Type Notes
cassandra-driver >=3 Fully Supported
elasticsearch >=10 Fully Supported
ioredis >=2 Fully Supported
memcached >=2.2 Fully Supported
mongodb-core >=2 Fully Supported Supports Mongoose
mysql >=2 Fully Supported
mysql2 >=1 Fully Supported
pg >=4 Fully Supported Supports pg-native when used with pg
redis >=0.12 Fully Supported

Worker Compatibility

Module Versions Support Type Notes
amqp10 >=3 Fully Supported Supports AMQP 1.0 brokers (i.e. ActiveMQ, Apache Qpid)
amqplib >=0.5 Fully Supported Supports AMQP 0.9 brokers (i.e. RabbitMQ, Apache Qpid)
generic-pool >=2 Fully Supported
kafka-node Coming Soon
rhea Coming Soon

Promise Library Compatibility

Module Versions Support Type
bluebird >=2 Fully Supported
q >=1 Fully Supported
when >=3 Fully Supported

Logger Compatibility

Module Versions Support Type
bunyan >=1 Fully Supported
pino >=2 Fully Supported
winston >=1 Fully Supported

Further Reading