Supported technologiesedit

The Elastic APM Node.js Agent automatically instruments various APIs in Node.js core and third-party frameworks and packages. This page lists all supported technologies and version ranges.

Node.js versionsedit

Support for the Elastic APM Node.js agent follows the support schedule of Node.js itself to the end-of-life period of each version after its maintenance term. Versions of Node.js past their end-of-life date are not supported.

Node.js release schedule

The current APM agent version (3.x) works with Node.js versions back to v8.6. We will only break support for older Node.js versions with a major version release of the APM agent.

ES Modulesedit

The Elastic APM Node.js agent does not yet support automatically instrumenting ECMAScript module imports (ESM), i.e. modules that are loaded via import ... statements. It currently only instruments CommonJS module imports, i.e. modules loaded via require(...).

For example, in the following code the http module is instrumented:

require('elastic-apm-node').start(/* ... */);

const http = require('http'); // CommonJS require
const server = http.createServer((req, res) => {
    res.statusCode = 200;
    res.end('pong');
});
server.listen(3000);

But in the following code the http module is not instrumented:

import apm from 'elastic-apm-node/start';

import http from 'http'; // ESM import
const server = http.createServer((req, res) => {
    res.statusCode = 200;
    res.end('pong');
});
server.listen(3000);

However, if you are using TypeScript or JavaScript that is compiled/translated/transpiled to CommonJS-using JavaScript via tools like Babel, Webpack, esbuild, etc., then using import ... in your source code is fine. To ensure your compiler is generating JS that uses CommonJS imports, use the following settings:

The ESM limitation only affects the agent’s automatic instrumentation. Other functionality — such as metrics collection, manual instrumentation and error capture — still works when using ES modules. Support for ES modules is planned for a future version of the APM agent.

Elastic Stack Compatibilityedit

This agent is compatible with APM Server v6.6 and above.

Frameworksedit

Though you can use Elastic APM with any Node.js framework, we automate a few things for the most popular Node.js modules.

These are the frameworks that we officially support:

Framework Version

Express

^4.0.0

hapi

>=9.0.0 <19.0.0; Deprecated. No longer tested.

@hapi/hapi

>=17.9.0 <21.0.0

Koa via koa-router or @koa/router

>=5.2.0 <10.0.0

Koa doesn’t have a built in router, so we can’t support Koa directly since we rely on router information for full support. We currently support the most popular Koa router called koa-router.

Restify

>=5.2.0

Fastify

>=1.0.0; see also Fastify’s own LTS documentation

AWS Lambda

N/A

Custom Transactionsedit

By default transactions are named based on their matched HTTP route if the framework used is listed above. These modules override that behavior to give better insights into specialized HTTP servers:

Module Version Note

express-graphql

>=0.6.1 <0.13.0

Will name all transactions by the GraphQL query name. (There is known issue with node <10.4.)

apollo-server-express

^2.0.4 <4

Will name all transactions by the GraphQL query name

Tracing and Instrumentationedit

The Node.js agent will automatically instrument the following modules to give you detailed performance metrics:

Module Version Note

aws-sdk

>1 <3

Will instrument SQS send/receive/delete messages, all S3 methods, all DynamoDB methods, and the SNS publish method

cassandra-driver

>=3.0.0 <5

Will instrument all queries

elasticsearch

>=8.0.0

Will instrument all queries

@elastic/elasticsearch

>=7.0.0 <9.0.0

Will instrument all queries

graphql

>=0.7.0 <17

Will instrument all queries

handlebars

*

Will instrument compile and render calls

jade

>=0.5.6

Will instrument compile and render calls; Deprecated. No longer tested. Use pug.

pug

>=0.1.0

Will instrument compile and render calls

ioredis

>=2.0.0 <6.0.0

Will instrument all queries

memcached

>=2.2.0 

Will instrument all commands.

mongodb-core

>=1.2.19 <4

Will instrument all queries. A lot of higher level MongoDB modules use mongodb-core, so those should be supported as well.

mongodb

>=2.0.0 <3.3.0

Supported via mongodb-core

mongodb

^3.3.0 <5

Will instrument all queries

mongojs

>=1.0.0 <2.7.0

Supported via mongodb-core

mongoose

>=4.0.0 <5.7.0

Supported via mongodb-core

mysql

^2.0.0

Will instrument all queries

mysql2

>=1.0.0 <3.0.0

Will instrument all queries

pg

>=4.0.0 <9.0.0

Will instrument all queries

redis

>=2.0.0 <4.0.0

Will instrument all queries

tedious

>=1.9 <15.0.0

(Excluding v4.0.0.) Will instrument all queries

undici

>=4.7.1 <6

Will instrument undici HTTP requests, except HTTP CONNECT. Requires node v14.17.0 or later, or the user to have installed the diagnostics_channel polyfill.

ws

>=1.0.0 <8.0.0

Will instrument outgoing WebSocket messages

Better Stack Tracesedit

When viewing a span in Elastic APM, you’ll see where in your code you initiated the span (e.g. a database query).

Given the async nature of Node.js, it’s not possible for us to see further back than the last async boundary. We therefore make sure to monitor as close to your code as possible. But some modules will interfere with this monitoring by injecting an async call between your code and the actual monitored function.

We monitor these "offending" modules directly to give you a better experience.

The modules and versions listed below are the ones we support. If you use an unsupported version you might not be able to see your own code in the spans. This does not impact the stability of your application in any way - only the collected metrics.

If you don’t see your own code in spans, please create a new topic in the Elastic APM discuss forum and include information about your dependencies.

Module Version

knex

>=0.9.0 <1.0.0

Continuityedit

The Elastic APM agent monitors async operations in your Node.js application to maintain awareness of which request is the active request at any given time. Certain modules can interfere with this monitoring if not handled properly.

Below is a list of modules known to cause issues with this monitoring. The versions listed are the versions we support. If you use an unsupported version you might experience missing spans. This does not impact the stability of your application in any way - only the collected metrics.

If you do experience missing spans in your performance metrics, please create a new topic in the Elastic APM discuss forum and include information about your dependencies and what data is missing.

Module Version Note

bluebird

>=2.0.0 <4.0.0

generic-pool

^2.0.0 || ^3.1.0

Used by a lot of database modules like for instance "pg"

express-queue

>=0.0.11 <1.0.0