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_logging settings.
  • 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-config checks 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

  1. Bootstrap. When newrelic is first loaded, index.js checks the Node.js version against the package's engines field (>=22.16.0), builds the configuration (defaults, then the config file, then NEW_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 to newrelic.* never crash the application.
  2. Hooking. The agent registers module-loading hooks (require-in-the-middle for CommonJS, import-in-the-middle plus @apm-js-collab/tracing-hooks for ES modules) and the diagnostics_channel based "subscribers". When your code loads express, pg, openai, and so on, the matching instrumentation wraps it.
  3. 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.
  4. 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