New Relic Node.js Agent
The newrelic package is New Relic's application performance monitoring (APM) agent for Node.js. You load it into your process before your application code, and it automatically instruments Node.js core modules and a large catalog of popular libraries (HTTP servers and clients, web frameworks, databases, message queues, loggers, and AI SDKs). The data it collects — transactions, traces, spans, errors, metrics, logs, and events — is sent to your New Relic account, where it appears in the APM UI.
This documentation goes deeper than the project README. It describes how the agent finds its configuration, every configuration setting and its environment variable, the full public API, the newrelic command-line tool, custom instrumentation, and the behaviors and pitfalls visible in the agent's source code.
Note: You need a New Relic account and license key to send data. The README advises, as with any instrumentation tool, to test the agent before using it in production.
What the Agent Does
- Automatic instrumentation. When a supported module is loaded, the agent wraps its functions to time requests, database queries, external calls, and message operations. See Supported Modules.
- Transactions and naming. Each inbound request (or custom unit of background work) becomes a transaction, named from your framework's routes. See Transaction Naming.
- Distributed tracing. W3C Trace Context (and, optionally, New Relic) headers are propagated across services, with configurable sampling. See Distributed Tracing.
- Errors. Uncaught errors, HTTP error status codes, and errors you report yourself are collected, with ignore and "expected" rules. See Errors and Logs API.
- Application logs. Records from instrumented logging libraries can be forwarded to New Relic, counted as metrics, or decorated locally with linking metadata. See the
application_loggingsettings. - AI monitoring. Calls to supported LLM SDKs (OpenAI, Anthropic, Google Gen AI, Amazon Bedrock, LangChain, and others) produce
Llm*events. See AI Monitoring API. - A public API. Name transactions, add attributes, record custom events and metrics, create background transactions and segments, and more. See API Overview.
- Custom instrumentation. Instrument libraries the agent does not support, using the same "shim" helpers the built-in instrumentation uses. See Custom Instrumentation.
- A configuration validator CLI.
npx newrelic validate-configchecks a configuration file the same way the agent would. See Command-Line Tools.
A Short Example
Install the package and copy the template configuration file:
npm install newrelic
cp ./node_modules/newrelic/newrelic.js ./newrelic.js
Set at least an application name and a license key in newrelic.js (or use the NEW_RELIC_APP_NAME and NEW_RELIC_LICENSE_KEY environment variables):
'use strict'
exports.config = {
app_name: ['My Application'],
license_key: 'your-license-key',
logging: { level: 'info' }
}
Start your program with the agent preloaded:
node -r newrelic server.js
Then use the API wherever you need it:
const newrelic = require('newrelic')
app.get('/checkout', (req, res) => {
newrelic.addCustomAttribute('cartSize', req.query.items)
res.send('ok')
})
The Quick Start walks through this end to end and shows what to expect in the agent log.
How It Works
- Bootstrap. When
newrelicis first loaded,index.jschecks the Node.js version against the package'senginesfield (>=22.16.0), builds the configuration (defaults, then the config file, thenNEW_RELIC_*environment variables), and decides whether to start. If startup is blocked, it still exports a stub API whose methods are no-ops, so your calls tonewrelic.*never crash the application. - Hooking. The agent registers module-loading hooks (
require-in-the-middlefor CommonJS,import-in-the-middleplus@apm-js-collab/tracing-hooksfor ES modules) and thediagnostics_channelbased "subscribers". When your code loadsexpress,pg,openai, and so on, the matching instrumentation wraps it. - Connecting. The agent connects to the New Relic collector with your license key, receives server-side configuration (such as Apdex thresholds and browser monitoring keys), and begins harvest cycles that periodically send collected data.
- Recording. Instrumented code creates transactions and segments in an async context. Metrics, traces, spans, events, errors, and logs are aggregated in memory and sent on each harvest.
Read Loading the Agent for the details of steps 1 and 2, and Configuration for how settings are resolved.
When to Use It
Use this agent when you run a Node.js service (a web server, a worker, a serverless function, a Next.js app) and want New Relic APM data without writing instrumentation yourself. It suits CommonJS and ES module applications, containers, AWS Lambda (serverless mode), and Azure and Google Cloud Run deployments.
It is not the right tool if you do not use New Relic, if you need vendor-neutral telemetry only (consider OpenTelemetry directly, though the agent can bridge OpenTelemetry APIs — see OpenTelemetry Bridge), or if you run an unsupported Node.js version (older than 22.16.0; versions 27 and newer start but log a warning that they are untested).
Project Status
The package is actively developed by New Relic and published to npm as newrelic. This documentation reflects version 14.13.0 of the package. Release notes are kept in NEWS.md; upgrade notes for old major versions are in the Migration Guide. The agent is licensed under Apache-2.0; the optional security agent dependency (@newrelic/security-agent) is under the New Relic Software License.
Where to Go Next
- Installation — requirements, install, verification.
- Quick Start — from zero to data in New Relic.
- Loading the Agent —
-r, ESM loader, bundlers, worker threads. - Configuration — discovery, precedence, environment variables, server-side config.
- Configuration Reference — every setting.
- Command-Line Tools —
newrelic validate-configandnewrelic-naming-rules. - API Overview — the full public API.
- Custom Instrumentation — instrument unsupported libraries.
- Troubleshooting — common problems and their fixes.