Installation

This page covers the requirements of the New Relic Node.js agent, how to install it, how to create a configuration, and how to verify that it starts. For release notes, see NEWS.md on GitHub.

Requirements

Requirement Value Source
Node.js >=22.16.0 engines.node in package.json
npm >=6.0.0 engines.npm in package.json
New Relic account A license key (license_key) Required unless serverless mode is enabled
Network Outbound HTTPS (port 443 by default) to the New Relic collector host, port, proxy settings

The Node.js version check is enforced at runtime, not only by npm. On an older Node.js, loading the agent logs and prints:

New Relic for Node.js requires a version of Node >=22.16.0.
Please upgrade from your current Node version: v20.11.0. Not starting!

The application keeps running, but require('newrelic') returns the no-op stub API. On Node.js 27 or newer, the agent starts but logs a warning that it "has not been tested" on that version.

Optional dependencies

These packages are listed as optionalDependencies and are installed automatically when they can be built for your platform. The agent works without them:

Package Used for
@datadog/pprof CPU and heap profiling (the profiling settings)
@newrelic/fn-inspect Function inspection used by code-level metrics
@prisma/prisma-fmt-wasm Parsing Prisma schemas for the @prisma/client instrumentation

The README also mentions an add-on package, @newrelic/native-metrics, which provides V8-level metrics.

Install the Package

Install newrelic as a regular (production) dependency with your npm-based package manager:

npm install newrelic

It must be a runtime dependency: the agent is loaded in production, not only at build time.

Create a Configuration

You can configure the agent with a file, with environment variables, or with both (environment variables win). See Configuration for the full precedence rules.

Option A: a configuration file

Copy the template shipped in the package to the directory you start your application from:

cp ./node_modules/newrelic/newrelic.js ./newrelic.js

Edit at least app_name and license_key:

'use strict'
exports.config = {
  app_name: ['Your application or service name'],
  license_key: 'your-license-key',
  logging: {
    level: 'info'
  }
}

The template also sets allow_all_headers: true and a default attributes.exclude list that removes cookies, authorization headers, set-cookie, and all x* request and response headers. Keep or adjust that list deliberately — see Attributes, Privacy, and Security.

The agent looks for newrelic.js, newrelic.cjs, or newrelic.mjs in several directories. If your application is an ES module project ("type": "module" in package.json), the README recommends renaming the file to newrelic.cjs so it is loaded as CommonJS:

mv newrelic.js newrelic.cjs

Option B: environment variables only

Every setting has a NEW_RELIC_* environment variable. The minimum is:

export NEW_RELIC_APP_NAME="Your application"
export NEW_RELIC_LICENSE_KEY="your-license-key"

When no file is found, the agent logs Unable to find configuration file. ... Attempting to start agent using environment variables. and continues. To skip the file search entirely (useful in containers), also set:

export NEW_RELIC_NO_CONFIG_FILE=true

Load the Agent

The recommended way is Node's -r (--require) flag, so the agent loads before any other module:

node -r newrelic your-program.js

For ES module applications, add the agent's loader as well:

node --import newrelic/esm-loader.mjs -r newrelic your-program.js

If you cannot change the command line, NODE_OPTIONS='-r newrelic' works too, or require('newrelic') as the very first line of your entry point. See Loading the Agent for the trade-offs.

Verify the Installation

1. Validate the configuration

The package installs a newrelic command. Run the validator against your file:

npx newrelic validate-config --config-file ./newrelic.js

A configuration that will let the agent start prints:

No configuration errors detected.

and exits with status 0. Environment variables are taken into account, so an empty license_key in the file is fine if NEW_RELIC_LICENSE_KEY is set. See Command-Line Tools for all options.

2. Check the agent log

By default the agent writes newrelic_agent.log in the process's current working directory. After starting your application, you should see lines similar to:

Using New Relic for Node.js. Agent version: 14.13.0; Node version: v22.16.0.

and, once it has reached New Relic, a debug-level line New Relic for Node.js is connected to New Relic.. Lines are written as JSON records; set logging.level to debug or trace for more detail, or logging.filepath to stdout to log to the console.

3. Generate traffic

Send a few requests to your application. Data normally appears in New Relic APM within a few minutes, under the name you set in app_name.

Upgrading

Upgrade with your package manager (npm install newrelic@latest). Breaking changes are listed per release in NEWS.md. Some settings and APIs currently emit deprecation warnings and are scheduled for removal in v15:

  • newrelic.instrumentLoadedModule() — load the agent with -r instead.
  • ai_monitoring.enabled — use ai_monitoring.basic_telemetry.enabled.
  • plugins.native_metrics.enabled — use virtual_machine.collect_metrics.enabled.
  • utilization.gcp_use_instance_as_host — use utilization.gcp_cloud_run.use_instance_as_host.

Troubleshooting Installation

Symptom Cause Fix
requires a version of Node >=22.16.0 ... Not starting! Node.js is too old. Upgrade Node.js, or pin an older agent major version that supports your runtime.
New Relic requires that you name this application! No app_name in the file and no NEW_RELIC_APP_NAME. Set one of them.
Not starting without license key! in the log No license_key and serverless mode is off. Set license_key or NEW_RELIC_LICENSE_KEY.
New Relic for Node.js is disabled due to an error: on stderr The configuration failed schema validation (for example a wrong type). Run npx newrelic validate-config -c ./newrelic.js to see the offending setting.
No newrelic_agent.log appears The working directory is not writable, logging.enabled is false, or serverless mode turned logging off. Set logging.filepath to a writable path or to stdout.
Optional dependency build warnings during install A native optional dependency could not be built. Safe to ignore unless you need profiling or code-level metrics function inspection.

More cases are covered in Troubleshooting.

See Also