New announcements for Serverless, Network, RUM, and more from Dash! New announcements from Dash!

Tracing Node.js Applications

Installation And Getting Started

If you already have a Datadog account you can find step-by-step instructions in our in-app guides for host-based and container-based set ups.

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

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

Compatibility

Node >=8 is supported by this library. 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.

Node 4 or Node 6 versions are supported by version 0.13 of the dd-trace-js tracer. This version will be supported until April 30th, 2020, but no new feature will be added.

Note: The global policy is that the Datadog JS tracer supports (only for bug fixes) a Node version until 1 year after its release reached its end-of-life.

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

ModuleVersionsSupport TypeNotes
connect>=2Fully Supported
express>=4Fully SupportedSupports Sails, Loopback, and more
fastify>=1Fully Supported
graphql>=0.10Fully SupportedSupports Apollo Server and express-graphql
hapi>=2Fully Supported
koa>=2Fully Supported
paperplane>=2.3Fully SupportedNot supported in serverless-mode
restify>=3Fully Supported

Native Module Compatibility

ModuleSupport Type
dnsFully Supported
httpFully Supported
httpsFully Supported
netFully Supported

Data Store Compatibility

ModuleVersionsSupport TypeNotes
cassandra-driver>=3Fully Supported
elasticsearch>=10Fully SupportedSupports @elastic/elasticsearch versions >=5
ioredis>=2Fully Supported
knex>=0.8Fully SupportedThis integration is only for context propagation
memcached>=2.2Fully Supported
mongodb-core>=2Fully SupportedSupports Mongoose
mysql>=2Fully Supported
mysql2>=1Fully Supported
pg>=4Fully SupportedSupports pg-native when used with pg
redis>=0.12Fully Supported
tedious>=1Fully SupportedSQL Server driver for mssql and sequelize

Worker Compatibility

ModuleVersionsSupport TypeNotes
amqp10>=3Fully SupportedSupports AMQP 1.0 brokers (i.e. ActiveMQ, Apache Qpid)
amqplib>=0.5Fully SupportedSupports AMQP 0.9 brokers (i.e. RabbitMQ, Apache Qpid)
generic-pool>=2Fully Supported
kafka-nodeComing Soon
rheaComing Soon

Promise Library Compatibility

ModuleVersionsSupport Type
bluebird>=2Fully Supported
promise>=7Fully Supported
promise-js>=0.0.3Fully Supported
q>=1Fully Supported
when>=3Fully Supported

Logger Compatibility

ModuleVersionsSupport Type
bunyan>=1Fully Supported
paperplane>=2.3.2Fully Supported
pino>=2Fully Supported
winston>=1Fully Supported

Further Reading