dd-trace: Node.js APM Tracer Library
dd-trace is an npm package that you can install in your Node.js application to capture APM (Application Performance Monitoring) data. In Datadog terminology this library is called a Tracer. This data is then sent off to a process which collects and aggregates the data, called an Agent. Finally the data is sent off to the Datadog servers where it's stored and made available for querying in a myriad of ways, such as displaying in a dashboard or triggering alerts.
Documentation
Most of the documentation for dd-trace is available on these webpages:
Version Release Lines and Maintenance
| Release Line | Latest Version | Node.js | SSI | K8s Injection | Status | Initial Release | End of Life |
|---|
v1 | | >= v12 | NO | NO | EOL | 2021-07-13 | 2022-02-25 |
v2 | | >= v12 | NO | NO | EOL | 2022-01-28 | 2023-08-15 |
v3 | | >= v14 | NO | YES | EOL | 2022-08-15 | 2024-05-15 |
v4 | | >= v16 | YES | YES | EOL | 2023-05-12 | 2025-01-11 |
v5 | | >= v18 | YES | YES | Maintenance | 2024-01-11 | 2027-07-02 |
v6 |
- EOL = End-of-life
- SSI = Single-Step Install
We currently maintain two release lines: v6 (current) and v5 (maintenance).
For any new projects it is recommended to use the v6 release line:
$ npm install dd-trace
$ yarn add dd-trace
Existing projects on v5 may continue to use it during its maintenance window by pinning the major version:
$ npm install dd-trace@5
$ yarn add dd-trace@5
Older EOL release lines are no longer maintained, but can still be pinned if needed:
$ npm install dd-trace@4 # or whatever version you need
$ yarn add dd-trace@4 # or whatever version you need
Any backwards-breaking functionality that is introduced into the library will result in an increase of the major version of the library and therefore a new release line.
Such releases are kept to a minimum to reduce the pain of upgrading the library.
When a new release line is introduced the previous release line then enters maintenance mode where it will receive updates for the next year.
Once that year is up the release line enters End of Life and will not receive new updates.
The library also follows the Node.js LTS lifecycle wherein new release lines drop compatibility with Node.js versions that reach end-of-life (with the maintenance release line still receiving updates for a year).
For more information about library versioning and compatibility, see the Node.js Compatibility Requirements page.
Changes associated with each individual release are documented on the GitHub Releases screen.
Development and Contribution
Please read the CONTRIBUTING.md document before contributing to this open source project.
ECMAScript Modules (ESM) Support
ESM support requires an additional command line argument when starting the Node.js process.
For more information, see the section on ESM support in the Node.js tracer documentation.
Serverless / Lambda
Note that there is a separate Lambda project, datadog-lambda-js, that is responsible for enabling metrics and distributed tracing when your application runs on Lambda.
That project does depend on the dd-trace package but also adds a lot of Lambda-related niceties.
If you find any issues specific to Lambda integrations then the issues may get solved quicker if they're added to that repository.
That said, even if your application runs on Lambda, any core instrumentation issues not related to Lambda itself may be better served by opening an issue in this repository.
Regardless of where you open the issue, someone at Datadog will try to help.
Bundling
If you would like to trace your bundled application then please read this page on bundling and dd-trace. It includes information on how to use our ESBuild plugin and includes caveats for other bundlers.
Next.js 15.5 or newer applications that use Turbopack can wrap their existing configuration:
const { withDatadogTurbopack } = require('dd-trace/next')
const nextConfig = { reactStrictMode: true }
module.exports = withDatadogTurbopack(nextConfig)
Preload dd-trace/init before the application loads. The wrapper instruments CommonJS dependencies and supported
source-rewrite targets in Node.js bundles.
The wrapper does not instrument client or edge bundles. It also excludes generic ESM export replacement, linked
workspaces, Prisma clients outside node_modules, and Yarn Plug'n'Play packages.
Security Vulnerabilities
Please refer to the SECURITY.md document if you have found a security issue.
Datadog With OpenTelemetery
Please refer to the Node.js Custom Instrumentation using OpenTelemetry API document. It includes information on how to use the OpenTelemetry API with dd-trace-js.
