IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

›

Supported technologies

edit

Supported technologies

edit

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.

Some versions of Node.js contain bugs or issues that limit our ability to instrument them correctly. The following versions of Node.js are known to not be fully instrumented:

v8.1.x - Recommended solution: Upgrade to v8.2.0 or higher to get full support
v8.0.x - Recommended solution: Upgrade to v8.2.0 or higher to get full support

Node.js 8.2.0 and above makes use of the experimental core API Async Hooks. If you experience any issues related to using Async Hooks, you can always disable the use of this API by setting the asyncHooks config option to false. Note however, that not all core Node.js API’s can be instrumented without the use of Async Hooks if running Node.js 8 or above.

Elastic Stack Compatibility

edit

This agent is compatible with APM Server v6.5 and above. For support for previous releases of the APM Server, use version 1.x of the agent.

Frameworks

edit

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
@hapi/hapi	>=17.9.0 <20.0.0
Koa via koa-router or @koa/router	>=5.2.0 <9.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	>=0.27.0

Custom Transactions

edit

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.10.0	Will name all transactions by the GraphQL query name
apollo-server-express	^2.0.4	Will name all transactions by the GraphQL query name

Tracing and Instrumentation

edit

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

Module	Version	Note
cassandra-driver	>=3.0.0	Will instrument all queries
elasticsearch	>=8.0.0	Will instrument all queries
graphql	>=0.7.0 <15.0.0	Will instrument all queries
handlebars	*	Will instrument compile and render calls
jade	>=0.5.6	Will instrument compile and render calls
pug	>=0.1.0	Will instrument compile and render calls
ioredis	>=2.0.0 <5.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
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 <8.0.0	Will instrument all queries
redis	^2.0.0	Will instrument all queries
tedious	>=1.9	Will instrument all queries
ws	>=1.0.0 <8.0.0	Will instrument outgoing WebSocket messages

Better Stack Traces

edit

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 <0.18.0

Continuity

edit

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

« Starting the agent Configuration »