dd-trace
Advanced tools
Package description
The dd-trace npm package is a Node.js APM (Application Performance Monitoring) client for Datadog. It allows you to monitor the performance of your Node.js applications, providing insights into the runtime and helping you to diagnose and optimize your code.
Tracing
This feature allows you to trace the execution of your application, marking and timing various operations within your code. You can tag spans with metadata and monitor the performance of individual requests or tasks.
const tracer = require('dd-trace').init();
// Instrument a function
tracer.trace('web.request', (span) => {
// Do some work
span.setTag('http.status_code', 200);
});Automatic Instrumentation
dd-trace can automatically instrument popular libraries and frameworks such as Express, Koa, GraphQL, and many others. This means that you can get insights into how these libraries are performing without having to manually instrument code.
const tracer = require('dd-trace').init();
// Automatically instruments supported libraries
const express = require('express');
const app = express();
app.get('/', (req, res) => res.send('Hello World!'));
app.listen(3000);Custom Tags and Metrics
You can add custom tags and metrics to your traces to provide additional context and granularity. This can be useful for filtering and searching through your traces in the Datadog APM interface.
const tracer = require('dd-trace').init();
// Add custom tags to a span
tracer.trace('web.request', (span) => {
span.setTag('my_tag', 'my_value');
span.setMetric('my_metric', 100);
});Distributed Tracing
Distributed tracing allows you to trace requests as they move across different services and components in your system. This is essential for understanding the performance of microservices architectures.
const tracer = require('dd-trace').init();
// Continue a trace across asynchronous boundaries
async function part1() {
return tracer.trace('part1', async () => {
// Do something
});
}
async function part2() {
return tracer.trace('part2', async (span) => {
// Do something else
span.context().toTraceId();
});
}New Relic's APM tool is similar to dd-trace in that it provides performance monitoring and tracing for Node.js applications. It offers a wide range of features for monitoring application health and is known for its user-friendly interface. However, it is a different product with its own set of integrations and pricing model.
Elastic APM Node.js Agent is part of the Elastic APM suite, which integrates with the Elastic Stack (Elasticsearch, Kibana, etc.). It provides similar functionalities for monitoring Node.js applications, including distributed tracing and performance metrics. It is more focused on integration with the Elastic ecosystem.
Zipkin is an open-source distributed tracing system. It provides features to gather timing data needed to troubleshoot latency problems in service architectures. While it supports various programming languages, it requires more manual setup and configuration compared to dd-trace.
Readme
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.
Most of the documentation for dd-trace is available on these webpages:
| Release Line | Latest Version | Node.js | Status | Initial Release | End of Life |
|---|---|---|---|---|---|
v1 |  | >= v12 | End of Life | 2021-07-13 | 2022-02-25 |
v2 |  | >= v12 | End of Life | 2022-01-28 | 2023-08-15 |
v3 |  | >= v14 | Maintenance | 2022-08-15 | 2024-05-15 |
v4 |  | >= v16 | Maintenance | 2023-05-12 | 2025-01-11 |
v5 |  | >= v18 | Current | 2024-01-11 | Unknown |
We currently maintain three release lines, namely v5, v4 and v3.
Features and bug fixes that are merged are released to the v5 line and, if appropriate, also the v4 & v3 line.
For any new projects it is recommended to use the v5 release line:
$ npm install dd-trace
$ yarn add dd-trace
However, existing projects that already use the v4 & v3 release line, or projects that need to support EOL versions of Node.js, may continue to use these release lines.
This is done by specifying the version when installing the package.
$ npm install dd-trace@4
$ yarn add dd-trace@4
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 NodeJS Compatibility Requirements page.
Changes associated with each individual release are documented on the GitHub Releases screen.
Please read the CONTRIBUTING.md document before contributing to this open source project.
Warning
ESM support has been temporarily disabled starting from Node 20 as significant changes are in progress.
ESM support is currently in the experimental stages, while CJS has been supported
since inception. This means that code loaded using require() should work fine
but code loaded using import might not always work.
Use the following command to enable experimental ESM support with your application:
Node.js < v20.6
node --loader dd-trace/loader-hook.mjs entrypoint.js
Node.js >= v20.6
node --import dd-trace/register.js entrypoint.js
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.
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.
Please refer to the SECURITY.md document if you have found a security issue.
FAQs
Datadog APM tracing client for JavaScript
The npm package dd-trace receives a total of 1,871,036 weekly downloads. As such, dd-trace popularity was classified as popular.
We found that dd-trace demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.
Security News
GitHub is susceptible to a CDN flaw that allows attackers to host malware on any public repository.