Installations
npm install dd-traceDeveloper Guide
Typescript
No
Module System
CommonJS
Min. Node Version
>=18
Node Version
20.18.3
NPM Version
10.8.2
Score
72.9
Supply Chain
97.5
Quality
94.2
Maintenance
100
Vulnerability
87.3
License
Releases
Contributors
Languages
JavaScript (99.7%)
Shell (0.12%)
HTML (0.09%)
Gherkin (0.04%)
Dockerfile (0.03%)
TypeScript (0.03%)
validate.email 🚀
Verify real, reachable, and deliverable emails with instant MX records, SMTP checks, and disposable email detection.
Developer
Download Statistics
Total Downloads
417,942,839
Last Day
757,680
Last Week
3,770,517
Last Month
16,034,531
Last Year
140,865,725
GitHub Statistics
NOASSERTION License
683 Stars
3,248 Commits
321 Forks
602 Watchers
287 Branches
456 Contributors
Updated on Mar 14, 2025
Bundle Size
1.31 MB
Minified
363.39 kB
Minified + Gzipped
Maintainers
Package Meta Information
Latest Version
5.41.1
Package Id
dd-trace@5.41.1
Unpacked Size
2.37 MB
Size
561.29 kB
File Count
704
NPM Version
10.8.2
Node Version
20.18.3
Published on
Mar 07, 2025
Total Downloads
Cumulative downloads
Total Downloads
417,942,839
Last Day
7.5%
757,680
Compared to previous day
Last Week
-1.8%
3,770,517
Compared to previous week
Last Month
17.3%
16,034,531
Compared to previous month
Last Year
25.7%
140,865,725
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
32
Dev Dependencies
45
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:
- Tracing Node.js Applications - most project documentation, including setup instructions
- Configuring the NodeJS Tracing Library - environment variables and config options
- API Documentation - method signatures, plugin list, and some usage examples
- APM Terms and Concepts - a glossary of concepts applicable across all languages
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 | Current | 2024-01-11 | Unknown |
- EOL = End-of-life
- SSI = Single-Step Install
We currently maintain one release line, namely v5.
For any new projects it is recommended to use the v5 release line:
1$ npm install dd-trace 2$ yarn add dd-trace
Existing projects that need to use EOL versions of Node.js may continue to use these older release lines. This is done by specifying the version when installing the package.
1$ npm install dd-trace@4 # or whatever version you need 2$ yarn add dd-trace@4 # or whatever version you need
Note, however, that the end-of-life release lines are no longer maintained and will not receive updates.
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.
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. Use the following to enable experimental ESM support with your application:
Node.js < v20.6
1node --loader dd-trace/loader-hook.mjs entrypoint.js
Node.js >= v20.6
1node --import dd-trace/register.js entrypoint.js
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.
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.
Note that our internal implementation of the OpenTelemetry API is currently set within the version range >=1.0.0 <1.9.0. This range will be updated at a regular cadence therefore, we recommend updating your tracer to the latest release to ensure up to date support.
No vulnerabilities found.
Reason
security policy file detected
Details
- Info: security policy file detected: SECURITY.md:1
- Info: Found linked content: SECURITY.md:1
- Info: Found disclosure, vulnerability, and/or timelines in security policy: SECURITY.md:1
- Info: Found text in security policy: SECURITY.md:1
Reason
all changesets reviewed
Reason
30 commit(s) and 12 issue activity found in the last 90 days -- score normalized to 10
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
packaging workflow detected
Details
- Info: Project packages its releases by way of GitHub Actions.: .github/workflows/release-3.yml:13
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Warn: project license file does not contain an FSF or OSI license.
Reason
dependency not pinned by hash detected -- score normalized to 9
Details
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/datadog-static-analysis.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/DataDog/dd-trace-js/datadog-static-analysis.yml/master?enable=pin
- Warn: containerImage not pinned by hash: benchmark/sirun/Dockerfile:2: pin your Docker image by updating ubuntu:22.04 to ubuntu:22.04@sha256:ed1544e454989078f5dec1bfdabd8c5cc9c48e0705d07b678ab6ae3fb61952d2
- Warn: pipCommand not pinned by hash: benchmark/sirun/Dockerfile:14
- Warn: downloadThenRun not pinned by hash: benchmark/sirun/Dockerfile:15
- Warn: downloadThenRun not pinned by hash: benchmark/sirun/Dockerfile:30-37
- Warn: npmCommand not pinned by hash: .gitlab/prepare-oci-package.sh:11
- Warn: npmCommand not pinned by hash: benchmark/sirun/runall.sh:30
- Warn: npmCommand not pinned by hash: .github/workflows/release-proposal.yml:16
- Info: 156 out of 156 GitHub-owned GitHubAction dependencies pinned
- Info: 53 out of 54 third-party GitHubAction dependencies pinned
- Info: 0 out of 2 downloadThenRun dependencies pinned
- Info: 1 out of 4 npmCommand dependencies pinned
- Info: 0 out of 1 containerImage dependencies pinned
- Info: 0 out of 1 pipCommand dependencies pinned
Reason
1 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-jr5f-v2jv-69x6
Reason
SAST tool detected but not run on all commits
Details
- Info: SAST configuration detected: CodeQL
- Warn: 9 commits out of 30 are checked with a SAST tool
Reason
branch protection is not maximal on development and all release branches
Details
- Info: 'allow deletion' disabled on branch 'master'
- Info: 'allow deletion' disabled on branch 'v5.x'
- Info: 'allow deletion' disabled on branch 'v4.x'
- Info: 'force pushes' disabled on branch 'master'
- Info: 'force pushes' disabled on branch 'v5.x'
- Info: 'force pushes' disabled on branch 'v4.x'
- Info: 'branch protection settings apply to administrators' is required to merge on branch 'master'
- Info: 'branch protection settings apply to administrators' is required to merge on branch 'v5.x'
- Info: 'branch protection settings apply to administrators' is required to merge on branch 'v4.x'
- Info: 'stale review dismissal' is required to merge on branch 'master'
- Info: 'stale review dismissal' is required to merge on branch 'v5.x'
- Info: 'stale review dismissal' is required to merge on branch 'v4.x'
- Warn: required approving review count is 1 on branch 'master'
- Warn: required approving review count is 1 on branch 'v5.x'
- Warn: required approving review count is 1 on branch 'v4.x'
- Warn: codeowners review is not required on branch 'master'
- Warn: codeowners review is not required on branch 'v5.x'
- Warn: codeowners review is not required on branch 'v4.x'
- Warn: 'last push approval' is disabled on branch 'master'
- Warn: 'last push approval' is disabled on branch 'v5.x'
- Warn: 'last push approval' is disabled on branch 'v4.x'
- Warn: 'up-to-date branches' is disabled on branch 'master'
- Warn: 'up-to-date branches' is disabled on branch 'v5.x'
- Warn: 'up-to-date branches' is disabled on branch 'v4.x'
- Info: status check found to merge onto on branch 'master'
- Info: status check found to merge onto on branch 'v5.x'
- Info: status check found to merge onto on branch 'v4.x'
- Info: PRs are required in order to make changes on branch 'master'
- Info: PRs are required in order to make changes on branch 'v5.x'
- Info: PRs are required in order to make changes on branch 'v4.x'
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Info: jobLevel 'checks' permission set to 'read': .github/workflows/all-green.yml:21
- Info: jobLevel 'contents' permission set to 'read': .github/workflows/all-green.yml:22
- Info: jobLevel 'actions' permission set to 'read': .github/workflows/codeql-analysis.yml:26
- Info: jobLevel 'contents' permission set to 'read': .github/workflows/codeql-analysis.yml:27
- Warn: jobLevel 'contents' permission set to 'write': .github/workflows/release-3.yml:18
- Warn: jobLevel 'contents' permission set to 'write': .github/workflows/release-4.yml:18
- Info: jobLevel 'pull-requests' permission set to 'read': .github/workflows/release-4.yml:19
- Warn: jobLevel 'contents' permission set to 'write': .github/workflows/release-dev.yml:11
- Warn: jobLevel 'contents' permission set to 'write': .github/workflows/release-latest.yml:18
- Info: jobLevel 'pull-requests' permission set to 'read': .github/workflows/release-latest.yml:19
- Warn: jobLevel 'contents' permission set to 'write': .github/workflows/release-latest.yml:44
- Info: jobLevel 'contents' permission set to 'read': .github/workflows/serverless-integration-test.yml:16
- Warn: no topLevel permission defined: .github/workflows/actionlint.yml:1
- Warn: no topLevel permission defined: .github/workflows/all-green.yml:1
- Warn: no topLevel permission defined: .github/workflows/appsec.yml:1
- Warn: no topLevel permission defined: .github/workflows/ci-visibility-performance.yml:1
- Warn: no topLevel permission defined: .github/workflows/codeql-analysis.yml:1
- Warn: no topLevel permission defined: .github/workflows/core.yml:1
- Warn: no topLevel permission defined: .github/workflows/datadog-static-analysis.yml:1
- Warn: no topLevel permission defined: .github/workflows/debugger.yml:1
- Warn: no topLevel permission defined: .github/workflows/instrumentations.yml:1
- Warn: no topLevel permission defined: .github/workflows/lambda.yml:1
- Warn: no topLevel permission defined: .github/workflows/llmobs.yml:1
- Warn: no topLevel permission defined: .github/workflows/package-size.yml:1
- Warn: no topLevel permission defined: .github/workflows/plugins.yml:1
- Warn: no topLevel permission defined: .github/workflows/pr-labels.yml:1
- Warn: no topLevel permission defined: .github/workflows/profiling.yml:1
- Warn: no topLevel permission defined: .github/workflows/project.yml:1
- Warn: no topLevel permission defined: .github/workflows/release-3.yml:1
- Warn: no topLevel permission defined: .github/workflows/release-4.yml:1
- Warn: no topLevel permission defined: .github/workflows/release-dev.yml:1
- Warn: no topLevel permission defined: .github/workflows/release-latest.yml:1
- Warn: no topLevel permission defined: .github/workflows/release-proposal.yml:1
- Warn: no topLevel permission defined: .github/workflows/serverless-integration-test.yml:1
- Warn: no topLevel permission defined: .github/workflows/system-tests.yml:1
- Warn: no topLevel permission defined: .github/workflows/tracing.yml:1
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Score
7.4
/10
Last Scanned on 2025-03-10
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More