API Overview
require('newrelic') (or import newrelic from 'newrelic') returns the agent's API object, an instance of the API class defined in api.js. This page explains the rules shared by every method and lists them all, grouped by topic, with links to the detailed pages.
const newrelic = require('newrelic')
newrelic.addCustomAttribute('plan', 'enterprise')
Rules That Apply to Every Method
- It is always safe to call. If the agent did not start (disabled, misconfigured, unsupported Node.js), the export is a stub whose methods do nothing. See The Stub API.
- Most methods need an active transaction. Methods such as
setTransactionName, addCustomAttribute, setUserID, and ignoreApdex act on the transaction in the current async context. Called outside one, they log a warning (for example No transaction found for custom attributes.) and do nothing. Inbound requests to instrumented servers create transactions automatically; for other work use startWebTransaction or startBackgroundTransaction.
- Errors are logged, not thrown. Bad arguments produce a log line in the agent log and an early return, never an exception. Check
newrelic_agent.log when a call seems to have no effect.
- Every call is counted. Each method increments a supportability metric named
Supportability/API/<method>.
- Return values. Most methods return
undefined. Several return false when they refuse to record (high security mode, an api.* kill switch, no transaction); those are noted per method.
- Kill switches.
api.custom_attributes_enabled, api.custom_events_enabled, and api.notice_error_enabled turn off the related methods. High security mode disables custom attributes and custom events entirely.
Methods by Topic
Transactions and segments
| Method |
Summary |
setTransactionName(name) |
Name the current transaction Custom/<name>. |
setControllerName(name, action) |
Name it Controller/<name>/<action>. |
getTransaction() |
Get a handle to end, ignore, or propagate the current transaction. |
startWebTransaction(url, handle) |
Run code in a new web transaction. |
startBackgroundTransaction(name, group, handle) |
Run code in a new background transaction. |
endTransaction() |
End the current transaction. |
startSegment(name, record, handler, callback) |
Time a block of code as a segment. |
ignoreApdex() |
Exclude the current transaction from Apdex. |
addNamingRule(pattern, name) |
Add a URL naming rule at runtime. |
addIgnoringRule(pattern) |
Ignore transactions whose URL matches. |
Attributes, events, and metrics
Errors and logs
Distributed tracing, linking, and browser
AI monitoring
Integrations and lifecycle
Custom instrumentation
TypeScript and ES Modules
The package itself is JavaScript; use import newrelic from 'newrelic' in ES modules. The developer API documentation generated from JSDoc is published at newrelic.github.io/node-newrelic.
See Also