dd-trace is the official Datadog APM tracing client library for Node.js applications, designed to automatically and manually capture performance monitoring data. It provides distributed tracing capabilities, allowing developers to instrument their Node.js services to gain insights into request lifecycles, identify bottlenecks, and monitor service health within the Datadog platform. The current stable release line is `v5`, with the latest version being `5.97.0`. Datadog maintains a regular release cadence for patch and minor versions, often weekly or bi-weekly, to introduce new features, improvements, and bug fixes, while major versions are released less frequently, with `v5` being released in January 2024. A key differentiator is its deep integration with the Datadog ecosystem, offering automatic instrumentation for popular Node.js frameworks and libraries, support for Single-Step Install (SSI), and Kubernetes Injection. It requires a Datadog Agent to be running to collect and forward the captured trace data.
npm install dd-traceVerified import paths — ran on the pinned version, not inferred.
This quickstart initializes the Datadog tracer, sets up a basic Express.js server, and demonstrates both automatic (Express request) and manual (`custom.db.query`) span creation with custom tags and error handling. It highlights the importance of `tracer.init()` and provides guidance on checking the Datadog Agent connectivity.
Upgrade to the latest `v5` release line to ensure continued support and access to the latest features. Review the migration guide for any breaking changes between major versions.
Ensure your application environment uses Node.js version 18 or newer. If you must use an older Node.js version, you will need to install a compatible EOL version of `dd-trace` (e.g., v4 for Node.js >=16, v3 for Node.js >=14).
Verify that the Datadog Agent is running and network accessible from your application. Configure `DD_AGENT_HOST` and `DD_AGENT_PORT` environment variables if the agent is not on `localhost:8126`.
Profile your application to identify performance bottlenecks before and after adding manual instrumentation. Enable debug logging only during development or for targeted troubleshooting, and avoid overly granular manual spans in high-throughput loops.
If conflicts arise, try disabling specific plugins in `dd-trace.init({ plugins: false })` or using `DD_TRACE_DISABLED_PLUGINS` environment variables. Consult the Datadog documentation for advanced plugin configuration and troubleshooting.Upgrade Node.js to version 18 or higher. Alternatively, if upgrading Node.js is not possible, install an older, compatible major version of `dd-trace` (e.g., `npm install dd-trace@4` for Node.js >=16).
Start the Datadog Agent. Ensure `DD_AGENT_HOST` and `DD_AGENT_PORT` environment variables are correctly set, pointing to the agent's location. Verify network connectivity and firewall rules between your application and the agent.
Ensure `tracer.init()` is called once at the very beginning of your application's entry point, preferably before any other modules are loaded, and that the `tracer` object is properly imported and available where `startSpan` is invoked.