How to Monitor a Node.js Application with New Relic APM

Last verified: September 10, 2026
By: PerfMonitoring

New Relic's Node.js APM agent instruments supported frameworks and libraries from inside your application process. The critical setup detail is load order: New Relic must load before the modules you want it to instrument. The current official installation guide recommends installing the newrelic npm package and starting the application with -r newrelic, for example node -r newrelic ./dist/server.js. [1]

This tutorial uses Node.js 24 LTS and an Express-style application as the reference environment. As of September 10, 2026, New Relic's official Node.js agent release notes list v14.3.10, released September 1, 2026. New Relic's compatibility documentation also notes that agent v14 dropped Node.js 20 after that runtime reached end of life, so do not assume an old Node runtime will work with the current major agent. [2][3]

The goal is not merely to install an npm package. You will prove that the agent is loaded at process startup, send normal traffic, report a controlled test error, and verify that the expected application entity receives transactions and error data.

What You'll Accomplish

By the end, you should have:

1. the current New Relic Node.js agent installed in your application;
2. a meaningful application name and license key configured without hard-coding the key in source;
3. the agent preloaded before Express and other instrumented modules;
4. normal HTTP transactions visible in New Relic APM;
5. one controlled verification error visible in the correct application; and
6. a practical troubleshooting path for “application exists but no data” failures.

Prerequisites

You need:

• a New Relic account and ingest/license key;
• a Node.js release supported by the current New Relic agent;
• an existing Node application or a small Express application for verification;
• permission to modify dependencies and the application startup command; and
• outbound network connectivity from the runtime to New Relic.

For this article, use Node.js 24 LTS unless your own support policy requires another currently supported runtime. New Relic recommends using the latest active LTS version of Node.js. [3]

Do not put a real New Relic license key into a public repository, tutorial screenshot, or command example.

Quick Answer

Install the agent with npm install newrelic, configure NEW_RELIC_LICENSE_KEY and NEW_RELIC_APP_NAME, and start Node with -r newrelic so the agent loads before your application modules. Generate several requests, then verify the application and transactions in New Relic APM. For a deterministic error check, call the current newrelic.noticeError() API from a temporary verification route and confirm that the event reaches the intended application. [1][4]

Step 1: Check Node.js and Agent Compatibility

Before adding instrumentation, check your runtime:

node --version
npm --version

Do not choose an agent version from an old blog post. New Relic follows semantic versioning for its Node.js agent and major releases can remove support for end-of-life Node runtimes or instrumentation. [2]

On the verification date for this article, New Relic's release-notes index lists Node.js agent 14.3.10 as the latest release, dated September 1, 2026. [2] The compatibility page says Node.js 22 and 24 are supported by recent agent releases and records that agent v14 discontinued support for Node.js 20. [3]

That does not mean you must pin 14.3.10 forever. It means your deployment should use a current supported agent and runtime combination, and you should review release notes before a major upgrade.

Step 2: Install the New Relic Node.js Agent

From your application directory, install the official package:

npm install newrelic

This is the current command in New Relic's manual Node.js agent installation documentation. [1]

If the dependency is installed into an existing application, commit the resulting package.json and lockfile changes according to your normal dependency-management policy. Do not add your license key to either file.

The official manual flow also provides a newrelic.js configuration file from the installed package. If you use file-based configuration, copy the provided file to the application root and keep secrets out of the file. [1]

For a small first deployment, environment variables are usually easier to keep environment-specific. New Relic documents both NEW_RELIC_LICENSE_KEY and NEW_RELIC_APP_NAME as configuration equivalents for the required license key and recommended application name. [5]

Step 3: Configure the Application Identity and License Key

Set the values in the process environment rather than editing secrets into source code:

export NEW_RELIC_LICENSE_KEY="<NEW_RELIC_LICENSE_KEY>"
export NEW_RELIC_APP_NAME="checkout-api"

Use an application name that clearly identifies the service. Avoid leaving the default “My Application” name because multiple unrelated applications can become difficult to distinguish. New Relic's configuration documentation strongly recommends a meaningful app_name. [5]

In production, use your platform's secret and environment management rather than interactive export commands. For example, a systemd unit, container orchestrator, or deployment platform can inject these values at runtime. The exact mechanism is environment-specific.

If you run separate staging and production deployments, use a naming/tagging strategy that prevents their telemetry from being merged unintentionally.

Step 4: Load New Relic Before Express and Other Instrumented Modules

The safest generic startup pattern in the current documentation is preload mode:

node -r newrelic app.js

If your compiled entry point is elsewhere, change only the application path:

node -r newrelic ./dist/server.js

The -r newrelic flag tells Node to require the agent before loading the application entry point. New Relic calls this out because the agent needs to load before many libraries in order to instrument them correctly. [1][6]

If you use a process manager, serverless runtime, Next.js, Kubernetes auto-attach, or a framework with a dedicated New Relic installation path, use the vendor's current framework-specific instructions. Do not force the generic startup command onto a deployment model that has its own integration.

Add the preload to package.json

For a simple Node application, you can make the preload part of the start script:

{
  "scripts": {
    "start": "node -r newrelic app.js"
  }
}

Then run:

npm start

The important property is not the name of the npm script. It is that New Relic loads before the modules it needs to instrument.

Step 5: Generate Normal Test Traffic

Once the app is running, send several normal requests to a known route:

for i in {1..10}; do
  curl -s http://localhost:3000/health > /dev/null
done

Use a route that exists in your own application. Do not create a production endpoint solely for New Relic if you already have a harmless read-only route you can exercise.

This traffic gives the agent transactions to report. Wait for the normal telemetry pipeline, then open the New Relic APM application matching NEW_RELIC_APP_NAME.

You should be able to identify fresh transaction activity for the service. Exact navigation labels can change, so the durable success criteria are:

• the intended APM application/entity exists;
• its last-seen data is current;
• transaction throughput increases after your test requests; and
• response-time/error views contain data from the same service rather than another application with a similar name.

Step 6: Generate One Controlled Error for Verification

A successful HTTP transaction proves that tracing is arriving, but it does not prove the error pipeline is useful. New Relic's Node agent exposes the noticeError() API for reporting an error programmatically, and the current agent configuration has a notice_error_enabled setting for this API. [4][5]

For an Express verification app, add a temporary route similar to this:

const newrelic = require('newrelic');
const express = require('express');
const app = express();

app.get('/nr-verification-error', (req, res) => {
  newrelic.noticeError(new Error('PerfMonitoring verification error'));
  res.status(500).json({ ok: false, verification: true });
});

This code does not mean you should add synthetic failures to a production public route. Use it in a local, staging, or otherwise controlled verification environment, then remove or protect the route when the check is complete.

Call the route once:

curl -i http://localhost:3000/nr-verification-error

Then confirm that the error appears in the same New Relic application used for the normal transaction test.

Verify the Setup

Consider the setup complete only when you can answer yes to all of these questions:

• Is the application running with newrelic preloaded?
• Does the New Relic entity have the expected application name?
• Did the normal test requests produce fresh transaction data?
• Did the controlled error appear as an error event/trace in the intended application?
• Are the timestamps and environment context consistent with the instance you just tested?

If the entity exists but no current transactions arrive, do not proceed to alerts yet. Fix instrumentation first.

Common Problems and Fixes

Problem: The application runs, but New Relic shows no transactions

Likely cause: the agent loaded after Express/framework modules, the license key is invalid/missing, the app name is unexpected, or network egress is blocked.

Fix: use the documented node -r newrelic ... preload form, verify NEW_RELIC_LICENSE_KEY and NEW_RELIC_APP_NAME are present in the actual runtime environment, and review the Node agent log. Avoid assuming that npm install newrelic alone starts instrumentation. [1]

Problem: Node.js 20 works with an older agent but not after upgrading

Likely cause: support changed across a major New Relic agent release.

Fix: do not downgrade blindly. New Relic's current compatibility material records that v14 dropped Node.js 20 support after Node 20 reached end of life. Upgrade the application runtime to a currently supported Node.js release, then retest the agent. [3]

Problem: Data appears under the wrong application name

Likely cause: the default or shared app_name is being used in more than one environment.

Fix: set a deliberate NEW_RELIC_APP_NAME for each service/environment naming model. New Relic warns that applications sharing the same name can have their data merged in the UI. [5]

Problem: Errors do not appear, but transactions do

Likely cause: no reportable error has occurred, the error API is disabled by configuration/high-security settings, or your application handles errors in a way that does not reach the agent automatically.

Fix: in a controlled environment, use the current newrelic.noticeError() API once, then check the error view. Review notice_error_enabled and your security configuration if the explicit test is still missing. [4][5]

Problem: A framework-specific deployment behaves differently

Likely cause: the generic Node instructions are not the recommended path for that framework/deployment model.

Fix: use New Relic's current dedicated installation guidance for Next.js, Lambda, Kubernetes auto-attach, PM2, or other supported special cases. The official “Monitor your Node.js application” page routes users to different setup paths based on deployment type. [6]

Best Practices

Keep the license key out of source. Treat it as a deployment secret and rotate it if it is exposed.

Use a supported Node release. Runtime EOL and agent major releases are linked. Read the compatibility page before upgrading either side.

Keep the agent current, but test upgrades. New Relic recommends staying current and its release notes call out breaking changes. Treat a major agent upgrade like an application dependency upgrade, not a transparent operating-system patch. [2]

Use meaningful service identity. A clear NEW_RELIC_APP_NAME, environment metadata, and release/version metadata make later alerting and incident triage more reliable.

Verify with known traffic. A clean install log is not enough. Generate a small, deterministic request set so you can correlate what you did with the telemetry you see.

Avoid collecting unnecessary sensitive data. Review application attributes, request data, and error payloads before enabling broader capture in production.

When This Setup Makes Sense

This setup fits a conventional Node.js service where you control package dependencies and the Node startup command. It is especially straightforward for Express-style services running on a server or container where node -r newrelic ... can be made part of the process definition.

Use New Relic's dedicated paths when the application runs in Lambda, Next.js, Kubernetes auto-attach, or another environment with special instrumentation requirements. [6]

For context rather than setup instructions, see the New Relic software profile, the application performance monitoring guide, the APM tools category, and the Datadog vs New Relic comparison.

Once your APM data is healthy, the natural next step is the companion tutorial on creating NRQL alert conditions from a signal you have already validated.

FAQ

Why must New Relic load before other Node.js modules?

The agent instruments supported libraries as they load. Preloading it with -r newrelic ensures the instrumentation is present before frameworks such as Express are required by the application. [1]

Can I configure the Node.js agent with environment variables?

Yes. New Relic documents environment-variable forms for most agent settings, including NEW_RELIC_LICENSE_KEY and NEW_RELIC_APP_NAME. [5]

Why do I see the application but no transactions?

Check whether the entity contains fresh data, not merely historical data. Then verify startup order, runtime environment variables, outbound connectivity, and whether the requests you generated actually reached the instrumented process.

Conclusion

A dependable New Relic Node.js setup has three proofs: the agent loads before the application, normal requests create fresh transactions, and a controlled error reaches the expected service. That is more meaningful than simply confirming that the newrelic package exists in node_modules.

Keep the Node runtime and agent within their supported compatibility window, preserve the preload order, and verify actual telemetry before creating operational alerts.

References

1. New Relic Documentation — Install the Node.js agent — https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/install-nodejs-agent/ — accessed September 10, 2026.
2. New Relic Documentation — Node.js agent release notes — https://docs.newrelic.com/docs/release-notes/agent-release-notes/nodejs-release-notes/ — accessed September 10, 2026. Latest release listed on the verification date: v14.3.10, September 1, 2026.
3. New Relic Documentation — Compatibility and requirements for the Node.js agent — https://docs.newrelic.com/docs/apm/agents/nodejs-agent/getting-started/compatibility-requirements-nodejs-agent/ — accessed September 10, 2026.
4. New Relic Documentation — Manage errors in APM: Collect, ignore, or mark as expected — https://docs.newrelic.com/docs/apm/agents/manage-apm-agents/agent-data/manage-errors-apm-collect-ignore-or-mark-expected/ — accessed September 10, 2026.
5. New Relic Documentation — Node.js agent configuration — https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration/ — accessed September 10, 2026.
6. New Relic Documentation — Monitor your Node.js application — https://docs.newrelic.com/docs/apm/agents/nodejs-agent/getting-started/monitor-your-nodejs-app/ — accessed September 10, 2026.

Editorial note: The commands and compatibility statements above were fact-checked against current official New Relic documentation. No live New Relic account or production Node.js service was used to claim hands-on test results.