JavaScript APM Tracer
Other
446
468
241

dd-trace: Node.js APM Tracer Library

npm v3 npm v2 npm dev codecov

Bits the dog  JavaScript

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.

Tracer, Agent, Datadog relationship diagram

Documentation

Most of the documentation for dd-trace is available on these webpages:

Version Release Lines and Maintenance

Release Line Latest Version Node.js Status Initial Release End of Life
v1 npm v1 >= v12 End of Life 2021-07-13 2022-02-25
v2 npm v2 >= v12 Maintenance 2022-01-28 2023-08-15
v3 npm v3 >= v14 Current 2022-08-15 Unknown

We currently maintain two release lines, namely v2 and v3. Features and bug fixes that are merged are released to the v3 line and, if appropriate, also the v2 line.

For any new projects it is recommended to use the v3 release line:

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

However, existing projects that already use the v2 release line, or projects that need to support Node.js v12, may use the v2 release line. This is done by specifying the version when installing the package. Note that we also publish to npm using a latest-node12 tag that can also be used for install:

$ npm install dd-trace@2
$ yarn add dd-trace@2
$ npm install dd-trace@latest-node12
$ yarn add dd-trace@latest-node12

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

Before contributing to this open source project, read our CONTRIBUTING.md.

Requirements

Since this project supports multiple Node versions, using a version manager such as nvm is recommended.

We use yarn for its workspace functionality, so make sure to install that as well.

To install dependencies once you have Node and yarn installed, run:

$ yarn

Testing

Before running plugin tests, the data stores need to be running. The easiest way to start all of them is to use the provided docker-compose configuration:

$ docker-compose up -d -V --remove-orphans --force-recreate
$ yarn services

Note The couchbase, grpc and oracledb instrumentations rely on native modules that do not compile on ARM64 devices (for example M1/M2 Mac) - their tests cannot be run locally on these devices.

Unit Tests

There are several types of unit tests, for various types of components. The following commands may be useful:

# Tracer core tests (i.e. testing `packages/dd-trace`)
$ yarn test:trace:core
# "Core" library tests (i.e. testing `packages/datadog-core`
$ yarn test:core
# Instrumentations tests (i.e. testing `packages/datadog-instrumentations`
$ yarn test:instrumentations

Several other components have test commands as well. See package.json for details.

To test plugins (i.e. components in packages/datadog-plugin-XXXX directories, set the PLUGINS environment variable to the plugin you're interested in, and use yarn test:plugins. If you need to test multiple plugins you may separate then with a pipe (|) delimiter. Here's an example testing the express and bluebird plugins:

PLUGINS="express|bluebird" yarn test:plugins

Memory Leaks

To run the memory leak tests, use:

$ yarn leak:core

# or

$ yarn leak:plugins

Linting

We use ESLint to make sure that new code is conform to our coding standards.

To run the linter, use:

$ yarn lint

Benchmarks

Our microbenchmarks live in benchmark/sirun. Each directory in there corresponds to a specific benchmark test and its variants, which are used to track regressions and improvements over time.

In addition to those, when two or more approaches must be compared, please write a benchmark in the benchmark/index.js module so that we can keep track of the most efficient algorithm. To run your benchmark, use:

$ yarn bench

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.

Security Vulnerabilities

If you have found a security issue, please contact the security team directly at security@datadoghq.com.

Contributors

rochdev
juan-fernandez
bengl
simon-id
Qard
uurien
tlhunter
khanayan123
CarlesDD
iunanua
rishabh
ericmustin
astuyve
nsavoire
sabrenner
DarcyRaynerDD
hoolioh
alloy
Kyle-Verhoog
maxday
wconti27
ganeshkumarsv
duncanista
schmod
szegedi
bmeck
cbeauchesne
ddyurchenko
DDuongNguyen
devsnek
jbertran
JustinTRoss
kjvalencik
lennyburdette
nilushancosta
piochelepiotr
robertomonteromiguel
flintinatux
vecerek
brettlangdon
crysmags
fragglebob
albertvaka
trevorah
blimmer
benjamine
bvanreeven
bizob2828
BrunoBerisso
CSLTech
icirellik
chaserelock
CNManning
agocs
csabapalfi
clayne11
Shikkic
djchinia
dandean
dlsteuer
deongroenewald
dwinrick-lever
eaviles
esilkensen
erwinw
thehideki81
hong823
ida613
sabrehagen
jamiehodge
jeremy-lq
jirikuncar
joeyfromspace
joeyzhao2018
jhatch
theJC
josephfrazier
jcarvalho
vanstinator
jeromemacias
NaitoKenzo
randomanderson
laurentjacob
ffluk3
marcghorayeb
mhassan1
onhate
Oblosys
martinslota
mlarraz
mattgperry
maxenglander
mkaufmaner
kurayama
koreissm
nathanmarks
goncalvesnelson
erictheswift
nunofgs
puzzledbytheweb