NodeJS Compatibility Requirements

NodeJS Compatibility Requirements

Releases

Versioning

Versioning of the Datadog Node.js tracing library follows semver. When a new major version is released it becomes the primary release line, where all new features, bug fixes and security patches land. Here’s an outline of what constitutes each type of semver change:

Major Minor Patch
Changes that are incompatible with previous versions. Adding anything that is compatible with previous versions (does not break them). Security fixes
API changes incompatible with previous versions. API additions Bug fixes
Functionality changes incompatible with previous versions. Functionality additions
Dropping support for anything such as Node.js versions, supported libraries, or other features. Adding tested support for anything, such as Node.js versions, supported libraries, or other features.

When a release has changes that could go in multiple semver categories, the highest one is chosen. Release notes are posted with each GitHub release.

Maintenance

Maintenance mode is a period during which a release gets only security and bug fixes whenever possible, but not new features except on a case-by-case basis. Major versions of dd-trace enter maintenance mode upon the release of the subsequent major version of dd-trace. The maintenance mode period lasts for one year after the release date of that subsequent version.

For example, if version 5.0.0 of dd-trace is released on May 4, 2023, the 4.x.x release line is supported on a maintenance mode basis until May 4, 2024. During this maintenance mode period, security and bug patches will be applied whenever possible.

If you have any questions or concerns about our support for a particular version of dd-trace-js, contact Support to discuss.

Node.js Version Support

When the Node.js project drops support for an LTS major release line (when it goes EOL), support for it is dropped in the next major version of dd-trace. The last major supporting release line of dd-trace library supports that EOL version of Node.js for at least another year on a maintenance mode basis.

Some issues cannot be solved in dd-trace and instead must be solved in Node.js. When this happens and the Node.js release in question is EOL, it’s not possible to solve the issue without moving to another non-EOL release. We do not make new releases of dd-trace to provide specific support for non-LTS Node.js major release lines (odd numbered versions).

For the best level of support, always run the latest LTS release of Node.js, and the latest major version of dd-trace. Whatever release line of Node.js you use, also use the latest version of Node.js on that release line, to ensure you have the latest security fixes.

For more information about Node.js release, see the official Node.js documentation.

Supported integrations

APM provides out-of-the-box instrumentation for many popular frameworks and libraries by using a plugin system. To request support for a module that is not listed, contact our awesome support team.

For details about how to how to toggle and configure plugins, check out the API documentation.

Web framework compatibility

Module Versions Support Type Notes
connect >=2 Fully supported
express >=4 Fully supported Supports Sails, Loopback, and more
fastify >=1 Fully supported
graphql >=0.10 Fully supported Supports Apollo Server and express-graphql
gRPC >=1.13 Fully supported
hapi >=2 Fully supported Supports [@hapi/hapi] versions >=17.9
koa >=2 Fully supported
microgateway-core >=2.1 Fully supported Core library for Apigee Edge. Support for the edgemicro CLI requires static patching using @datadog/cli.
next >=9.5 Fully supported CLI usage requires NODE_OPTIONS='-r dd-trace/init'.
paperplane >=2.3 Fully supported Not supported in serverless-mode
restify >=3 Fully supported

Native module compatibility

Module Support Type Notes
dns Fully supported
fs Fully supported
http Fully supported
https Fully supported
http2 Partially supported Only HTTP2 clients are currently supported and not servers.
net Fully supported

Data store compatibility

Module Versions Support Type Notes
cassandra-driver >=3 Fully supported
couchbase ^2.4.2 Fully supported
elasticsearch >=10 Fully supported Supports @elastic/elasticsearch versions >=5
ioredis >=2 Fully supported
knex >=0.8 Fully supported This integration is only for context propagation
memcached >=2.2 Fully supported
mongodb-core >=2 Fully supported Supports Mongoose
mysql >=2 Fully supported
mysql2 >=1 Fully supported
oracledb >=5 Fully supported
pg >=4 Fully supported Supports pg-native when used with pg
redis >=0.12 Fully supported
sharedb >=1 Fully supported
tedious >=1 Fully supported SQL Server driver for mssql and sequelize

Worker compatibility

Module Versions Support Type Notes
@google-cloud/pubsub >=1.2 Fully supported
amqp10 >=3 Fully supported Supports AMQP 1.0 brokers (i.e. ActiveMQ, Apache Qpid)
amqplib >=0.5 Fully supported Supports AMQP 0.9 brokers (i.e. RabbitMQ, Apache Qpid)
generic-pool >=2 Fully supported
kafkajs >=1.4 Fully supported
kafka-node Coming Soon
rhea >=1 Fully supported

SDK compatibility

Module Versions Support Type Notes
aws-sdk >=2.1.35 Fully supported CloudWatch, DynamoDB, Kinesis, Redshift, S3, SNS, SQS, and generic requests.

Promise library compatibility

Module Versions Support Type
bluebird >=2 Fully supported
promise >=7 Fully supported
promise-js >=0.0.3 Fully supported
q >=1 Fully supported
when >=3 Fully supported

Logger compatibility

Module Versions Support Type
bunyan >=1 Fully supported
paperplane >=2.3.2 Fully supported
pino >=2 Fully supported
winston >=1 Fully supported

Unsupported libraries

Fibers

fibers is incompatible with async_hooks, a Node.js module that is used by dd-trace-js to track asynchronous contexts thereby ensuring accurate tracing. Interactions between fibers and async_hooks may lead to unpreventable crashes and undefined behavior. So, the use of dd-trace-js with applications that invoke fibers directly or indirectly through frameworks such as Meteor may result in instability (crashes) or incorrect tracing.

For additional information or to discuss leave a comment on this github issue or reach out to support to discuss further.

Further Reading

Additional helpful documentation, links, and articles: