--- title: Node.js Compatibility Requirements description: Compatibility Requirements for the Node.js tracer breadcrumbs: >- Docs > APM > Application Instrumentation > Compatibility Requirements > Node.js Compatibility Requirements --- # Node.js Compatibility Requirements ## Releases{% #releases %} ### Versioning{% #versioning %} Versioning of the Datadog Node.js tracing library follows [semver](https://semver.org/). 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](https://github.com/DataDog/dd-trace-js/releases) are posted with each GitHub release. ### Maintenance{% #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](https://docs.datadoghq.com/help/) to discuss. ### Node.js Version Support{% #nodejs-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](https://github.com/nodejs/release#release-schedule). ### Operating system support{% #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 AAP, 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 Version | Operating System | Architectures | Minimum Versions | | ---------------- | --------------------- | -------------------------------- | ---------------------------------------- | | 3.x, 4.x | Linux (glibc) | arm, arm64, x64 | CentOS 7, Debian 9, RHEL 7, Ubuntu 14.04 | | Linux (musl) | arm, arm64, x64 | Alpine 3.13 | | macOS | arm64, x64 | Catalina (10.15) | | Windows | ia32, x64 | Windows 8.1, Windows Server 2012 | | 2.x | Linux (glibc) | arm, arm64, ia32, x64 | CentOS 7, Debian 9, RHEL 7, Ubuntu 14.04 | | Linux (musl) | arm, arm64, ia32, x64 | Alpine 3.10 | | macOS | arm64, x64 | Yosemite (10.10) | | Windows | ia32, x64 | Windows 8.1, Windows Server 2012 | ## Supported integrations{% #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](https://docs.datadoghq.com/help/). For details about how to how to toggle and configure plugins, check out the [API documentation](https://datadog.github.io/dd-trace-js/#integrations). ### Native module compatibility{% #native-module-compatibility %} | Module | Support Type | Notes | | ---------------------------------------------------------- | ------------------- | ---------------------------------------------- | | [child_process](https://nodejs.org/api/child_process.html) | Fully supported | | [dns](https://nodejs.org/api/dns.html) | Fully supported | | [http](https://nodejs.org/api/http.html) | Fully supported | This includes the built-in `fetch` function. | | [https](https://nodejs.org/api/https.html) | Fully supported | | [http2](https://nodejs.org/api/http2.html) | Partially supported | Only HTTP2 clients are supported, not servers. | | [net](https://nodejs.org/api/net.html) | Fully supported | ### Protocol compatibility{% #protocol-compatibility %} | Module | Versions | Support Type | Notes | | ---------------------------------------------------------------------- | --------- | --------------- | ---------------------------------------------------------------------------------------------------------- | | [@apollo/gateway](https://www.npmjs.com/package/@apollo/gateway) | `>=2.3.0` | Fully supported | | [@apollo/server](https://www.npmjs.com/package/@apollo/server) | `>=4` | Fully supported | | [apollo-server-core](https://www.npmjs.com/package/apollo-server-core) | `>=3` | Fully supported | Used for Apollo Server v2 and v3. | | [avsc](https://www.npmjs.com/package/avsc) | `>=5` | Fully supported | | [gRPC](https://grpc.io/) | `>=1.13` | Fully supported | | [graphql-yoga](https://github.com/dotansimha/graphql-yoga) | `>=3.6.0` | Fully supported | Supports graphql-yoga v3 executor. | | [graphql](https://github.com/graphql/graphql-js) | `>=0.10` | Fully supported | Supports Apollo Server and express-graphql. | | [ldapjs](https://www.npmjs.com/package/ldapjs) | `>=2` | Fully supported | | [ws](https://www.npmjs.com/package/ws) | `>=8` | Fully supported | More info at [WebSocket Observability](https://docs.datadoghq.com/tracing/guide/websocket_observability/). | ### Web framework compatibility{% #web-framework-compatibility %} | Module | Versions | Support Type | Notes | | ---------------------------------------------------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [connect](https://github.com/senchalabs/connect) | `>=2` | Fully supported | | [express](https://expressjs.com) | `>=4` | Fully supported | Supports Sails, Loopback, and other frameworks built on top of Express. | | [fastify](https://www.fastify.io) | `>=1` | Fully supported | | [hapi](https://hapijs.com) | `>=2` | Fully supported | Supports [@hapi/hapi] versions `>=17.9`. | | [hono](https://hono.dev/) | `>=4` | Fully supported | | [koa](https://koajs.com) | `>=2` | Fully supported | | [microgateway-core](https://github.com/apigee/microgateway-core) | `>=2.1` | Fully supported | Core library for Apigee Edge. Support for the [edgemicro](https://github.com/apigee-internal/microgateway) CLI requires static patching using [@datadog/cli](https://www.npmjs.com/package/@datadog/cli). | | [moleculer](https://moleculer.services/) | `>=0.14` | Fully supported | | [next](https://nextjs.org/) | `>=10.2` | Fully supported | See 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](https://github.com/articulate/paperplane) | `>=2.3` | Fully supported | Not supported in [serverless-mode](https://github.com/articulate/paperplane/blob/master/docs/API.md#serverless-deployment). | | [restify](http://restify.com) | `>=3` | Fully supported | #### Complex framework usage{% #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: ```shell 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: ```plain // existing command "start": "next start", // suggested command "start": "node --require dd-trace/init ./node_modules/.bin/next start", "start": "NODE_OPTIONS='--require dd-trace/init' ./node_modules/.bin/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. ### Data store compatibility{% #data-store-compatibility %} | Module | Versions | Support Type | Notes | | -------------------------------------------------------------------------- | --------- | ------------------- | ------------------------------------------------- | | [aerospike](https://github.com/aerospike/aerospike-client-nodejs) | `>=4` | Fully supported | | [cassandra-driver](https://github.com/datastax/nodejs-driver) | `>=3` | Fully supported | | [couchbase](https://github.com/couchbase/couchnode) | `^2.6.12` | Fully supported | | [elasticsearch](https://github.com/elastic/elasticsearch-js) | `>=10` | Fully supported | Supports `@elastic/elasticsearch` versions `>=5`. | | [ioredis](https://github.com/luin/ioredis) | `>=2` | Fully supported | | [iovalkey](https://www.npmjs.com/package/iovalkey) | `>=0.0.1` | Fully supported | | [knex](https://knexjs.org) | `>=0.8` | Fully supported | This integration is only for context propagation. | | [mariadb](https://github.com/mariadb-corporation/mariadb-connector-nodejs) | `>=2` | Fully supported | | [memcached](https://github.com/3rd-Eden/memcached) | `>=2.2` | Fully supported | | [mongodb-core](https://www.mongodb.com/docs/drivers/node/current/) | `>=2` | Fully supported | Supports Mongoose. | | [mongoose](https://mongoosejs.com/) | `>=4.6.4` | Fully supported | | [mysql](https://github.com/mysqljs/mysql) | `>=2` | Fully supported | | [mysql2](https://github.com/sidorares/node-mysql2) | `>=1` | Fully supported | | [opensearch](https://github.com/opensearch-project/opensearch-js) | `>=1` | Fully supported | | [oracledb](https://oracle.github.io/node-oracledb/) | `>=5` | Fully supported | | [pg](https://node-postgres.com) | `>=4` | Fully supported | Supports `pg-native` when used with `pg`. | | [prisma](https://www.prisma.io/) | `>=6.1.0` | Partially supported | Doesn't support DBM. | | [redis](https://github.com/NodeRedis/node_redis) | `>=0.12` | Fully supported | | [sequelize](https://sequelize.org/) | `>=4` | Fully supported | | [sharedb](https://share.github.io/sharedb/) | `>=1` | Fully supported | | [tedious](http://tediousjs.github.io/tedious) | `>=1` | Fully supported | SQL Server driver for `mssql` and `sequelize`. | **Note**: Redis 6.0+ supports inline authentication in commands such as `HELLO`, `MIGRATE`, and `ACL SETUSER`. - **Datadog Trace Agent**: The minimum required and recommended version is `7.76.1` to ensure authentication parameters are automatically obfuscated in trace metadata. - **Datadog Lambda Extension** (Serverless environments): The minimum required version is `v28.0.0`. ### Worker compatibility{% #worker-compatibility %} | Module | Versions | Support Type | Notes | | ---------------------------------------------------------------------------------------------- | ---------- | --------------- | ------------------------------------------------------------------------- | | [@azure/event-hubs](https://www.npmjs.com/package/@azure/event-hubs) | `>=6.0.0` | Fully supported | | [@azure/functions](https://www.npmjs.com/package/@azure/functions) | `>=4` | Fully supported | Disabled by default. Enable with `DD_TRACE_AZURE_FUNCTIONS_ENABLED=true`. | | [@azure/service-bus](https://www.npmjs.com/package/@azure/service-bus) | `>=7.9.2` | Fully supported | | [@confluentinc/kafka-javascript](https://www.npmjs.com/package/@confluentinc/kafka-javascript) | `>=1` | Fully supported | | [@google-cloud/pubsub](https://github.com/googleapis/nodejs-pubsub) | `>=1.2` | Fully supported | | [amqp10](https://github.com/noodlefrenzy/node-amqp10) | `>=3` | Fully supported | Supports AMQP 1.0 brokers (such as ActiveMQ, or Apache Qpid) | | [amqplib](https://github.com/squaremo/amqp.node) | `>=0.5` | Fully supported | Supports AMQP 0.9 brokers (such as RabbitMQ, or Apache Qpid) | | [bullmq](https://github.com/taskforcesh/bullmq) | `>=5.66.0` | Fully supported | | [generic-pool](https://github.com/coopernurse/node-pool) | `>=2` | Fully supported | | [kafkajs](https://github.com/tulios/kafkajs) | `>=1.4` | Fully supported | | [rhea](https://github.com/amqp/rhea) | `>=1` | Fully supported | ### SDK compatibility{% #sdk-compatibility %} | Module | Versions | Support Type | Notes | | -------------------------------------------- | ---------- | --------------- | ---------------------------------------------------------------------------- | | [aws-sdk](https://github.com/aws/aws-sdk-js) | `>=2.1.35` | Fully supported | CloudWatch, DynamoDB, Kinesis, Redshift, S3, SNS, SQS, and generic requests. | ### Promise library compatibility{% #promise-library-compatibility %} | Module | Versions | Support Type | | ---------------------------------------------------- | --------- | --------------- | | [bluebird](https://github.com/petkaantonov/bluebird) | `>=2` | Fully supported | | [promise](https://github.com/then/promise) | `>=7` | Fully supported | | [promise-js](https://github.com/kevincennis/promise) | `>=0.0.3` | Fully supported | | [q](https://github.com/kriskowal/q) | `>=1` | Fully supported | | [when](https://github.com/cujojs/when) | `>=3` | Fully supported | ### Logger compatibility{% #logger-compatibility %} | Module | Versions | Support Type | | ------------------------------------------------------------------------------------- | --------- | --------------- | | [bunyan](https://github.com/trentm/node-bunyan) | `>=1` | Fully supported | | [paperplane](https://github.com/articulate/paperplane/blob/master/docs/API.md#logger) | `>=2.3.2` | Fully supported | | [pino](http://getpino.io) | `>=2` | Fully supported | | [winston](https://github.com/winstonjs/winston) | `>=1` | Fully supported | ### AI/LLM compatibility{% #aillm-compatibility %} The [Automatic Instrumentation for LLM Observability](https://docs.datadoghq.com/llm_observability/instrumentation/auto_instrumentation/?tab=nodejs#supported-frameworks-and-libraries) page contains a list of instrumented LLM packages (including Amazon Bedrock, Anthropic, LangChain, OpenAI, Azure OpenAI, Vercel AI SDK, VertexAI, and Google GenAI). ### Testing framework compatibility{% #testing-framework-compatibility %} The [JavaScript and TypeScript Tests](https://docs.datadoghq.com/tests/setup/javascript/?tab=ciproviderwithautoinstrumentationsupport#compatibility) page contains a list of instrumented testing framework packages (including Jest, Mocha, Cucumber, Cypress, Playwright, and Vitest). ### Known transitive package compatibility{% #known-transitive-package-compatibility %} While the Datadog tracer doesn't provide direct support for modules listed here, they are known to work, as they depend on modules that the tracer does instrument. | Module | Notes | | -------------------------------------------- | -------------------------------------------- | | [axios](https://www.npmjs.com/package/axios) | Axios depends on the internal `http` module. | ## Unsupported libraries{% #unsupported-libraries %} ### Fibers{% #fibers %} [`fibers`](https://github.com/laverdet/node-fibers) is incompatible with `async_hooks`, a Node.js [module](https://nodejs.org/api/async_hooks.html) 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](https://www.meteor.com/) may result in instability (crashes) or incorrect tracing. For additional information or to discuss [leave a comment on this GitHub issue](https://github.com/DataDog/dd-trace-js/issues/1229) or [reach out to support](https://docs.datadoghq.com/help/) to discuss further. ## Further Reading{% #further-reading %} - [Instrument Your Application](https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/nodejs)