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-rinstead.ai_monitoring.enabled— useai_monitoring.basic_telemetry.enabled.plugins.native_metrics.enabled— usevirtual_machine.collect_metrics.enabled.utilization.gcp_use_instance_as_host— useutilization.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.