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.

Getting started

Before you begin, make sure you’ve already installed and configured the Agent.

Instrument your application

After you install and configure your Datadog Agent, the next step is to add the tracing library directly in the application to instrument it. Read more about compatibility information.

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

  1. 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.

  2. 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.

Bundling

dd-trace works by intercepting require() calls that a Node.js application makes when loading modules. This includes modules that are built-in to Node.js, like the fs module for accessing the filesystem, as well as modules installed from the NPM registry, like the pg database module.

Bundlers crawl all of the require() calls that an application makes to files on disk. It replaces the require() calls with custom code and combines all of the resulting JavaScript into one “bundled” file. When a built-in module is loaded, such as require('fs'), that call can then remain the same in the resulting bundle.

APM tools like dd-trace stop working at this point. They can continue to intercept the calls for built-in modules but don’t intercept calls to third party libraries. This means that when you bundle a dd-trace app with a bundler it is likely to capture information about disk access (through fs) and outbound HTTP requests (through http), but omit calls to third party libraries. For example:

  • Extracting incoming request route information for the express framework.
  • Showing which query is run for the mysql database client.

A common workaround is to treat all third party modules that the APM needs to instrument as being “external” to the bundler. With this setting the instrumented modules remain on disk and continue to be loaded with require() while the non-instrumented modules are bundled. However, this results in a build with many extraneous files and starts to defeat the purpose of bundling.

Datadog recommends you have custom-built bundler plugins. These plugins are able to instruct the bundler on how to behave, inject intermediary code and intercept the “translated” require() calls. As a result, more packages are included in the bundled JavaScript file.

Note: Some applications can have 100% of modules bundled, however native modules still need to remain external to the bundle.

Esbuild support

This library provides experimental esbuild support in the form of an esbuild plugin, and requires at least Node.js v16.17 or v18.7. To use the plugin, make sure you have dd-trace@3+ installed, and then require the dd-trace/esbuild module when building your bundle.

Here’s an example of how one might use dd-trace with esbuild:

const ddPlugin = require('dd-trace/esbuild')
const esbuild = require('esbuild')

esbuild.build({
  entryPoints: ['app.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [ddPlugin],
  platform: 'node', // allows built-in modules to be required
  target: ['node16'],
  external: [
    // esbuild cannot bundle native modules
    '@datadog/native-metrics',

    // required if you use profiling
    '@datadog/pprof',

    // required if you use Datadog security features
    '@datadog/native-appsec',
    '@datadog/native-iast-taint-tracking',
    '@datadog/native-iast-rewriter',

    // required if you encounter graphql errors during the build step
    'graphql/language/visitor',
    'graphql/language/printer',
    'graphql/utilities'
  ]
}).catch((err) => {
  console.error(err)
  process.exit(1)
})

Note: Due to the usage of native modules in the tracer, which are compiled C++ code, (usually ending with a .node file extension), you need to add entries to your external list. Currently native modules used in the Node.js tracer live inside of @datadog prefixed packages. This will also require that you ship a node_modules/ directory alongside your bundled application. You don’t need to ship your entire node_modules/ directory as it would contain many superfluous packages that should be contained in your bundle.

To generate a smaller node_modules/ directory with only the required native modules, (and their dependencies) you can first determine the versions of packages that you need, then create a temporary directory to install them into, and copy the resulting node_modules/ directory from it. For example:

cd path/to/project
npm ls @datadog/native-metrics
# dd-trace@5.4.3-pre ./dd-trace-js
# └── @datadog/native-metrics@2.0.0
$ npm ls @datadog/pprof
# dd-trace@5.4.3-pre ./dd-trace-js
# └── @datadog/pprof@5.0.0
mkdir temp && cd temp
npm init -y
npm install @datadog/native-metrics@2.0.0 @datadog/pprof@5.0.0
cp -R ./node_modules path/to/bundle

At this stage you should be able to deploy your bundle, (which is your application code and most of your dependencies), with the node_modules/ directory, which contains the native modules and their dependencies.

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.

Read tracer settings for a list of initialization options.

Further Reading

Additional helpful documentation, links, and articles:

Source codeGITHUB more more API documentationDOCUMENTATION more more Explore your services, resources and tracesUSE THE APM UI more more Advanced UsageADVANCED USAGE more more