Install the Node.js agent

To complete a basic Node.js agent installation, you can use our guided installation for an automated install, (choose EU if you're in the EU) or follow the instructions in this document. Either way, you need a New Relic account if you don't already have one. (It's free, forever!)

Our Node.js agent is publicly available on the Node Package Manager (npm) repository as well as on GitHub.

Install the Node.js agent

To install the Node.js agent:

1. Create a New Relic account. Don't have one? Sign up for free! No credit card required.

2. Ensure you meet the system requirements. In particular, make sure you use a supported Node.js version.

3. Use the command npm install newrelic for each application you want to monitor. If your app is using one of these Apollo Server modules install our Apollo plugin with npm install @newrelic/apollo-server-plugin. More details about using @newrelic/apollo-server-plugin can be found here.

   Important

   If you're using Next.js, see this example of a Next.js app

4. From node_modules/newrelic, copy newrelic.js into the root directory of your app.

5. Configure agent via the newrelic.js file or via environment variable:

   • Customize the license_key setting with license key.
   • Customize the app_name setting with one or more meaningful app names.

6. Add -r newrelic to your app's startup script. For example, if your application's entry point is ./dist/server.js then you would use the require flag like so:

   bash

   Copy

   $
   node -r newrelic ./dist/server.js

   An example Docker command:

   CMD ["node", "-r", "newrelic", "server.js"]

   Copy

   Important

   For a Next.js app load our agent via NODE_OPTIONS:

   CMD ["NODE_OPTIONS='-r newrelic'", "next", "start"]

   Copy

   If you're using Nest.JS and the nest start command to start the application, modify its startup binary to load the New Relic agent: nest start --exec 'node -r newrelic'. Here is an example Nest.js application

   More info about the Node.js command line option -r here.

   Important

   If you are unable to use the -r require flag you can also use require('newrelic') as the first line of your app's main module. Note If you are using Babel or a similar transpiler require('newrelic') will cause instrumentation issues.

   If neither of these options work for you, (for example, asynchronously loading API keys from a remote location during application bootstrapping), you may also add stock instrumentation to an already loaded supported module by using newrelic.instrumentLoadedModule:

   // module loaded before newrelic
   const expressModule = require('express');
   
   // load the agent
   const newrelic = require('newrelic');
   
   // instrument express after the agent has been loaded
   newrelic.instrumentLoadedModule(
     'express',    // the module's name, as a string
     expressModule // the module instance
   );

   Copy

7. Optional: For additional Node.js runtime-level statistics, ensure the @newrelic/native-metrics package is installed.

8. Generate some traffic, then wait a few minutes for data to appear in the APM UI.

You can further customize your agent behavior via newrelic.js or an environment variable. To keep the agent configuration separate from your app, edit the NEW_RELIC_HOME environmental variable.

For more information, see our API doc.

View logs for your APM and infrastructure data

You can also bring your logs and application's data together to make troubleshooting easier and faster. With logs in context, you can see log messages related to your errors and traces directly in your app's UI. You can also see logs in context of your infrastructure data, such as Kubernetes clusters. No need to switch to another UI page.

Keep your Node.js agent up-to-date

To ensure that you have the most up-to-date version of New Relic, refer to the Node.js release notes. When applicable, the release notes include a download link with instructions on how to update the Node.js agent.

Troubleshooting

After you update the agent, generate some traffic and wait a few minutes. If no data appears in the New Relic UI, see the troubleshooting procedures.