dd-trace: the Node.js APM client, and the two release lines that still get fixes

Three hops: tracer, agent, then the Datadog back end

dd-trace is an npm package you install into a Node.js application to capture APM data, which is Application Performance Monitoring data. In Datadog's own vocabulary this library is a Tracer. The trace data is sent to a process that collects and aggregates it, called an Agent, and the Agent sends it on to the Datadog servers, where it is stored and made available for querying, in a dashboard or to trigger an alert.

That three hop design is the first thing to understand, because it decides what you run and where. The tracer lives inside your process, the agent is a separate process that sits alongside your service, and everything beyond that is the vendor's side. The README includes a diagram of the relationship between the tracer, the agent and Datadog.

The topics list includes opentracing, which tells you the library speaks an open tracing vocabulary rather than only the vendor's own. The repository layout backs that up: there is an openfeature/ directory and openfeature.js, an ext/ directory for the instrumentation extensions, and a packages/ directory holding the individual integration packages, one per framework or service.

For the reader deciding whether to adopt this, the immediate question is whether you already have a Datadog Agent in your deployment. If you do, the tracer slots into a pipeline that exists. If you do not, adopting the tracer means adopting the agent as well.

Six release lines, and only two of them still receive updates

The release line table in the README is the most consequential part of the documentation, and it is worth reading in full before you install anything.

The v1 line supports Node 12 and above, started on 2021-07-13 and reached end of life on 2022-02-25. The v2 line, also Node 12 and above, ran from 2022-01-28 to 2023-08-15. The v3 line raised the floor to Node 14, ran from 2022-08-15 to 2024-05-15, and was the first to support Kubernetes injection. The v4 line, Node 16 and above, ran from 2023-05-12 to 2025-01-11 and added Single-Step Install. The v5 line requires Node 18 and above, began on 2024-01-11 and is in maintenance with end of life on 2027-07-02. The v6 line requires Node 22 and above, started on 2026-07-02, is marked current, and has no end of life date set.

So the practical rule is: new projects go on v6, existing v5 projects stay on v5 during the maintenance window, and the older lines are still installable by pinning but receive nothing.

The policy behind that is described in the same section. Any backwards-breaking functionality raises the major version and creates a new release line, and such releases are kept to a minimum to reduce upgrade pain. When a new line appears, the previous one enters maintenance for a year, and after that it is end of life. The library also follows the Node.js LTS lifecycle, so a new line drops compatibility with Node versions that have themselves reached end of life, while the maintenance line keeps receiving updates for another year.

Installing is one command, and the major version is the contract

For a new project the README recommends the v6 release line, and the install is the usual two lines:

$ npm install dd-trace
$ yarn add dd-trace

Projects already on v5 pin the major version for the duration of the maintenance window:

$ npm install dd-trace@5
$ yarn add dd-trace@5

And the older end of life lines can still be pinned if something needs them:

$ npm install dd-trace@4 # or whatever version you need
$ yarn add dd-trace@4 # or whatever version you need

Pinning the major is the important habit here, and the README's own policy explains why it matters. Because a breaking change produces a new major line, an unpinned dependency can move your application onto a different line during an ordinary install, and with it a different Node.js floor and a different set of supported integrations.

The documentation set is spread across four places, which is worth knowing before you start: the tracing guide for Node.js applications with setup instructions, the library configuration page for environment variables and config options, the API documentation with method signatures and the plugin list, and a general APM terms and concepts glossary that applies across languages.

For per release detail, the README points to the GitHub Releases screen, and MIGRATING.md is in the repository root for upgrade notes.

ESM needs a loader argument, and Lambda lives in another repository

Two integration realities are called out early because both change how you start the process.

The first is ECMAScript modules. The README states plainly that ESM support requires an additional command line argument when starting the Node.js process, and links to the ESM section of the Node.js tracer documentation. The repository carries the machinery for this: loader-hook.mjs, initialize.mjs and init.js are the entry points involved in that startup path. If your application is ESM only, that argument is not optional.

The second is serverless. The README notes that a separate Lambda project, datadog-lambda-js, is responsible for enabling metrics and distributed tracing when the application runs on Lambda. That project depends on the dd-trace package and adds a lot of Lambda specific extras. The routing advice is practical rather than defensive: if the issue is specific to the Lambda integration, the issue is likely to be resolved faster in that repository, while core instrumentation problems are better filed here.

There is also a bundling note. The README points to a page on bundling and dd-trace for anyone who wants to trace a bundled application, which matters because a bundler that rewrites module resolution can interfere with an instrumentation library that has to patch modules before your code runs.

Generated files with verification scripts beside them

The package.json shows a repository that generates several things and then checks that the generated output matches. The generate and verify pairs are named after what they produce:

    "generate:config:types": "node scripts/generate-config-types.js",
    "verify:config:types": "node scripts/generate-config-types.js --check",
    "generate:electron-package": "node scripts/generate-electron-package.js",
    "verify:electron-package": "node scripts/generate-electron-package.js --check",

There are equivalents for rewriter targets and for the supported integrations list, which means the table of frameworks the library instruments is generated rather than maintained by hand.

One more generated artefact is worth knowing about because it affects consumers. The prepack script runs a script called swap-v5-types.js, and the repository carries a separate index.d.v5.ts alongside index.d.ts. In other words, the TypeScript definitions that ship differ between the v5 and v6 lines, and the packaging step swaps them.

The lint script is equally thorough, and the list tells you what the project treats as a policy violation rather than a style preference. It runs a licence check, a check on the size of AGENTS.md, a check for coverage artefacts, a check against Microsoft container registry images, a check that Docker image digests are pinned, and then eslint with --max-warnings 0.

A compose file that is a list of emulators pinned by digest

The docker-compose.yml at the root of the repository exists to test the integrations against real services rather than mocks, and the file makes that visible. It defines an Aerospike service, an Azurite service, an Azure Cosmos DB emulator, an Azure Event Hubs emulator and an Azure Service Bus emulator, among others.

Every one of those images is pinned by digest rather than by tag, with the version as a trailing comment:

  azurite:
    image: ghcr.io/datadog/dd-trace-js/mcr.microsoft.com/azure-storage/azurite@sha256:647c63a91102a9d8e8000aab803436e1fc85fbb285e7ce830a82ee5d6661cf37 # 3.35.0
    ports:
      - "127.0.0.1:10000:10000"
      - "127.0.0.1:10001:10001"
      - "127.0.0.1:10002:10002"

The Cosmos DB emulator additionally needs the licence flag ACCEPT_EULA set to Y, and the Event Hubs and Service Bus emulators mount their configuration from fixtures in the packages directory. The ports are bound to 127.0.0.1 rather than exposed, which keeps the emulators local to the developer machine.

That approach says something about the project. Testing an instrumentation library properly means running it against the actual service, and pinning by digest is how you keep that reproducible while the upstream images move.

Where dd-trace is the wrong tool

The first wrong fit is a runtime below the floor of the line you need. v6 requires Node 22, and the older lines that accept Node 14 or 16 are already end of life, so on an old runtime you are choosing between a line that receives no updates and a runtime upgrade. That is a decision about your platform, not about the tracer.

The second is a team that wants vendor-neutral tracing. The agent is a required part of the path, the data is stored in Datadog, and the dashboards and alerting live there. If the requirement is to be able to switch backends, a tracer that talks to a specific agent is the wrong shape.

The third is an application that is not a Node.js service. This is a Node.js library, and its integration packages are Node frameworks and services. A polyglot estate needs a tracer per runtime, and this one covers only its own.

The fourth is the licensing question. The repository is classified with a custom licence that GitHub cannot categorise, and the root holds LICENSE, NOTICE, LICENSE-3rdparty.csv and both LICENSE.Apache and LICENSE.BSD3, which tells you the project ships code under more than one licence and tracks the third party licences of what it vendors. Read those files for the terms that apply to your use, and this is not legal advice.

There is also a dependency question worth raising early, since it is the usual complaint about APM clients. The repository carries a vendor/ directory that the prepare script installs with npm ci, and the library patches istanbul and v8 coverage tooling. An instrumentation library that rewrites modules before your code runs carries real risk of conflicting with other tools that do the same, which is why the bundling and ESM notes are as prominent as they are. Read those two pages before you enable it in a service that already has a lot of instrumentation.

Editorial conclusion

dd-trace fits a Node.js service that is already sending telemetry to Datadog, and whose runtime is Node 22 or newer if it wants the current line. It does not fit an application on an end of life Node version, and it does not fit a team that wants vendor-neutral tracing. Before upgrading, read the release line table and the MIGRATING.md file, and pin the major version explicitly so a patch day cannot move you onto a new line.

Frequently asked questions

Official sources

1. DataDog/dd-trace-js on GitHub
2. Issues
3. Project website
4. README
5. Releases