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

Method Summary
addCustomAttribute(key, value) Attribute on the transaction and current span.
addCustomAttributes(atts) Several at once.
addCustomSpanAttribute(key, value) Attribute on the current span only.
addCustomSpanAttributes(atts) Several span attributes.
setUserID(id) Set enduser.id.
recordCustomEvent(eventType, attributes) Record a custom event.
recordMetric(name, value) Record a custom metric value.
incrementMetric(name, value) Increment a custom counter metric.

Errors and logs

Method Summary
noticeError(error, customAttributes, expected) Report a handled error.
setErrorGroupCallback(callback) Compute error.group.name for Errors Inbox.
recordLogEvent(logEvent) Forward a log record.

Distributed tracing, linking, and browser

Method Summary
getTraceMetadata() Current traceId and spanId.
getLinkingMetadata(omitSupportability) Metadata for logs-in-context.
Transaction handle DT methods acceptDistributedTraceHeaders, insertDistributedTraceHeaders.
getBrowserTimingHeader(options) Browser monitoring script for HTML pages.

AI monitoring

Method Summary
recordLlmFeedbackEvent(params) Attach user feedback to an LLM response.
setLlmTokenCountCallback(callback) Supply token counts.
withLlmCustomAttributes(context, callback) Add llm.* attributes to LLM events in a scope.

Integrations and lifecycle

Method Summary
setLambdaHandler(handler) Wrap an AWS Lambda handler.
setDispatcher(name, version) Report the dispatcher environment value.
obfuscateSql(sql, dialect) Replace literal values in SQL.
Apollo Server callbacks Custom attributes and filtering for GraphQL.
shutdown(options, callback) Flush data and stop the agent.

Custom instrumentation

Method Summary
instrument(...) Generic instrumentation.
instrumentConglomerate(...) Modules mixing several categories.
instrumentDatastore(...) Database clients.
instrumentMessages(...) Message brokers.
instrumentWebframework(...) Web frameworks.
instrumentLoadedModule(name, module) Deprecated.

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