Compatibility and requirements for the Node.js agent

New Relic's Node.js agent is publicly available on the Node Package Manager (npm) repository as well as on New Relic's GitHub repo for Node.js. Before you install the Node.js agent, make sure your application meets the following system requirements.

Node.js version support

Recommendation: For best performance, use the latest active long term support (LTS) version of Node.js.

Support for new Node.js releases

New Relic will support the latest even versions of Node.js releases by the beginning of the following active long term support schedule. The version support policy does not replace the general New Relic agent and plugin end-of-life (EOL) policy.

The following are proposed time ranges. The actual release date may vary.

Node.js version Active long term support (LTS) start date Initial release date of Node.js agent
with support
14 October 2020 April-October 2020
12 October 22, 2019 November 2019

End of support for Node.js releases reaching EOL

When support for a new long term support agent version is made available, support for the Node.js agent version that reaches end-of-life during the same time period will simultaneously drop.

The following are proposed time ranges. The actual release date may vary.

Node.js version End of life (EOL) date Initial release date of Node.js agent dropping support
10 April 2021 April-October 2021
8 December 2019 TBD
6 April 2019 November 2019

Node 12 errors

For Node 12, the following change affects New Relic's Node.js agent:

Errors resulting in unhandled rejections are not scoped to the transaction that was active when the rejected promise was created. This is because the promise responsible for triggering the init async hook is no longer passed through on the promise wrap instance. This breaks the linkage that associates a given promise rejection with the transaction it was scheduled in.

Supported Node.js frameworks

If you are using a supported framework with default routers, New Relic's Node.js agent can read these frameworks' route names as-is. However, if you want more specific names than are provided by your framework, you may want to use one or more of the tools New Relic provides with the Node.js transaction naming API.

Operating systems

  • Linux
  • SmartOS
  • Mac OSX 10.7 and higher
  • Windows Server 2008 and higher

Datastores

The Node.js agent monitors the performance of Node.js application calls to these datastores:

Instance details

New Relic collects instance details for a variety of databases and database drivers. The ability to view specific instances and the types of database information in New Relic APM depends on your New Relic agent version.

New Relic's Node.js agent version 1.31.0 or higher supports the following:

Database npm module name Minimum module version Minimum agent version
PostgreSQL pg 4.0.0 1.31.0
Redis redis 2.0.0 1.31.0
MongoDB mongodb 2.1.0 1.32.0
MySQL mysql 2.4.1 1.32.0
Memcached memcached 1.0.0 1.33.0

To request instance-level information from datastores currently not listed for your New Relic agent, get support at support.newrelic.com.

Messages queues

Message queue instrumentation is only available with the New Relic Node.js agent v2 or higher. Currently supported message queue instrumentation:

  • amqplib

For other message queue libraries, use custom instrumentation.

Hosting services

Process managers

In general, process managers that handle starting, stopping, and restarting of Node.js (like Forever) should be compatible with the Node.js agent. If you are using PM2, the minimum supported version of PM2 is 2.0.

Security requirements

As a standard security measure for data collection, your app server must support SHA-2 (256-bit). SHA-1 is not supported.

Connect the agent to other New Relic products

The Node.js agent integrates with other New Relic products to give you end-to-end visibility:

Product Integration
New Relic Browser The Node.js agent automatically injects the Browser JavaScript agent when you enable auto-instrumentation. After enabling Browser injection, you can view Browser data in the APM Overview page and quickly switch between the APM and Browser data for a particular app. For configuration options and manual instrumentation, see New Relic Browser and the Node.js agent.
New Relic Infrastructure When you install the Infrastructure and APM agents on the same host, they automatically detect one another. You can then view a list of hosts in the APM UI, and filter your Infrastructure hosts by APM app in the Infrastructure UI. For more information, see New Relic APM data in Infrastructure.
New Relic Insights The Node.js agent sends default events and attributes to Insights for NRQL queries. You can also record custom events for advanced analysis.
New Relic Synthetics Synthetic transaction traces connect requests from Synthetics monitors to the underlying APM transaction.

For more help

Recommendations for learning more: