Our Node.js agent is publicly available on the Node Package Manager (npm) repository as well as on GitHub. Before you install the Node.js agent, make sure your application meets the following system requirements.
If you haven't already, create a New Relic account. It's free, forever.
Node.js version support
Tip
For best performance, use the latest active long term support (LTS) version of Node.js.
Support for new Node.js releases
We 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 our general 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 |
|---|---|---|
18 | October 2022 | April-October 2022 |
16 | October 2021 | July 26, 2021 with Node.js agent v8.0.0 |
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 |
|---|---|---|
12 | April 2022 | April-October 2022 |
10 | April 2021 | As of July 26, 2021, we have discontinued support for Node.js 10 with v8 of the Node.js agent. For more details, including how you can easily prepare for this transition, see our Explorers Hub post. |
Node.js 12 errors
For Node.js 12, the following change affects the 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
- Express 4.6.0 or higher
- Restify
- Connect
- Hapi
- Koa 2.0.0 or higher (external module loaded with the agent)
- Fastify
- Next.js 12.0.9 or higher
If you are using a supported framework with default routers, the 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.
EOL NOTICE
We're discontinuing support for several capabilities in November 2021. This includes the Oracle Driver Package and Hapi versions prior to Hapi 19.2 for our Node.js agent. For more details, including how you can easily prepare for this transition, see our Explorers Hub post.
Processors
- The New Relic Node Agent is built to run on most processors including being tested and validated to work on AWS Graviton2
Operating systems
- Linux
- SmartOS
- macOS 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:
- Cassandra
- Memcached
- MongoDB
- MySQL (via mysql and mysql2 packages)
- Redis
- Postgres (including the native and pure JavaScript packages)
Instance details
We collect instance details for a variety of databases and database drivers. The ability to view specific instances and the types of database information in APM depends on your agent version.
New Relic's Node.js agent version 1.31.0 or higher supports the following:
Database |
| Minimum module version | Minimum agent version |
|---|---|---|---|
4.0.0 | 1.31.0 | ||
2.0.0 | 1.31.0 | ||
2.1.0 | 1.32.0 | ||
2.4.1 | 1.32.0 | ||
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 features
The Node.js agent integrates with other features to give you observability across your entire stack:
Product | Integration |
|---|---|
The Node.js agent can add the benefits of browser monitoring when you enable auto-instrumentation. After enabling browser monitoring injection, simply follow our guide to installing browser monitoring with the Node.js agent. Once you've completed these steps, you can view your browser data in the APM Summary page and quickly switch between the APM and browser data for a particular app. For configuration options and manual instrumentation, see browser monitoring and the Node.js agent. | |
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 APM data in infrastructure monitoring. | |
The Node.js agent sends default events and attributes for NRQL queries. You can also record custom events for advanced analysis. | |
Synthetic transaction traces connect requests from synthetic monitors to the underlying APM transaction. |