Cette page n'est pas encore disponible en français, sa traduction est en cours.
Si vous avez des questions ou des retours sur notre projet de traduction actuel, n'hésitez pas à nous contacter.

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:

MajorMinorPatch
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 additionsBug 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. Datadog does 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.

Operating system support

The following operating systems are officially supported by dd-trace. Any operating system not listed is still likely to work, but with some features missing, for example ASM, profiling, and runtime metrics. Generally speaking, operating systems that are actively maintained at the time of initial release for a major version are supported.

dd-trace VersionOperating SystemArchitecturesMinimum Versions
3.xLinux (glibc)arm, arm64, x64CentOS 7, Debian 9, RHEL 7, Ubuntu 14.04
Linux (musl)arm, arm64, x64Alpine 3.13
macOSarm64, x64Catalina (10.15)
Windowsia32, x64Windows 8.1, Windows Server 2012
2.xLinux (glibc)arm, arm64, ia32, x64CentOS 7, Debian 9, RHEL 7, Ubuntu 14.04
Linux (musl)arm, arm64, ia32, x64Alpine 3.10
macOSarm64, x64Yosemite (10.10)
Windowsia32, x64Windows 8.1, Windows Server 2012

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

ModuleVersionsSupport TypeNotes
connect>=2Fully supported
express>=4Fully supportedSupports Sails, Loopback, and more
fastify>=1Fully supported
graphql>=0.10Fully supportedSupports Apollo Server and express-graphql
graphql-yoga>=3.6.0Fully supportedSupports graphql-yoga v3 executor
gRPC>=1.13Fully supported
hapi>=2Fully supportedSupports [@hapi/hapi] versions >=17.9
koa>=2Fully supported
microgateway-core>=2.1Fully supportedCore library for Apigee Edge. Support for the edgemicro CLI requires static patching using @datadog/cli.
moleculer>=0.14Fully supported
next>=9.5Fully supportedSee note on Complex framework usage.

The tracer supports the following Next.js features:
  • Standalone (output: 'standalone')
  • App Router
  • Middleware: Not traced, use tracer versions 4.18.0 and 3.39.0 or higher for best experience.


Note: Next.js is under heavy active development, and it is not uncommon for patch releases to break compatibility with dd-trace. Test automations alert Datadog to these issues, but it can often take a few days to fix compatibility with the latest Next.js release.
paperplane>=2.3Fully supportedNot supported in serverless-mode
restify>=3Fully supported

Complex framework usage

Some modern complex Node.js frameworks, such as Next.js and Nest.js, provide their own entry-point into an application. For example, instead of running node app.js, you may need to run next start. In these cases, the entry point is a file that ships in the framework package, not a local application file (app.js).

Loading the Datadog tracer early in your application code isn’t effective because the framework could have already loaded modules that should be instrumented.

To load the tracer before the framework, use one of the following methods:

Prefix all commands you run with an environment variable:

NODE_OPTIONS='--require dd-trace/init' npm start

Or, modify the package.json file if you typically start an application with npm or yarn run scripts:

    // existing command
    "start": "next start",

    // suggested command
    "start": "node --require dd-trace/init ./node_modules/next start",
    "start": "NODE_OPTIONS='--require dd-trace/init' ./node_modules/next start",

Note: The previous examples use Next.js, but the same approach applies to other frameworks with custom entry points, such as Nest.js. Adapt the commands to fit your specific framework and setup. Either command should work, but using NODE_OPTIONS also applies to any child Node.js processes.

Native module compatibility

ModuleSupport TypeNotes
dnsFully supported
httpFully supported
httpsFully supported
http2Partially supportedOnly HTTP2 clients are currently supported and not servers.
netFully supported

Data store compatibility

ModuleVersionsSupport TypeNotes
cassandra-driver>=3Fully supported
couchbase^2.4.2Fully supported
elasticsearch>=10Fully supportedSupports @elastic/elasticsearch versions >=5
ioredis>=2Fully supported
knex>=0.8Fully supportedThis integration is only for context propagation
mariadb>=3Fully supported
memcached>=2.2Fully supported
mongodb-core>=2Fully supportedSupports Mongoose
mysql>=2Fully supported
mysql2>=1Fully supported
oracledb>=5Fully supported
pg>=4Fully supportedSupports pg-native when used with pg
redis>=0.12Fully supported
sharedb>=1Fully supported
tedious>=1Fully supportedSQL Server driver for mssql and sequelize

Worker compatibility

ModuleVersionsSupport TypeNotes
@google-cloud/pubsub>=1.2Fully supported
amqp10>=3Fully supportedSupports AMQP 1.0 brokers (such as ActiveMQ, or Apache Qpid)
amqplib>=0.5Fully supportedSupports AMQP 0.9 brokers (such as RabbitMQ, or Apache Qpid)
generic-pool>=2Fully supported
kafkajs>=1.4Fully supported
rhea>=1Fully supported

SDK compatibility

ModuleVersionsSupport TypeNotes
aws-sdk>=2.1.35Fully supportedCloudWatch, DynamoDB, Kinesis, Redshift, S3, SNS, SQS, and generic requests.
openai3.xFully supported

Promise library compatibility

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

Logger compatibility

ModuleVersionsSupport Type
bunyan>=1Fully supported
paperplane>=2.3.2Fully supported
pino>=2Fully supported
winston>=1Fully 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

Documentation, liens et articles supplémentaires utiles: