Attributes, Events, and Metrics

This page covers the API for attaching your own data to New Relic telemetry: custom attributes on transactions and spans, the end-user ID, custom events, and custom metrics. For how attributes are filtered per destination, see Attributes, Privacy, and Security.

Attribute Limits

These limits apply to all custom attributes, as implemented in lib/attributes/:

Limit Value
Value types string, number, boolean. Other types (objects, arrays, undefined, null) are dropped with a debug log.
Attributes per transaction (custom) 64. Further new keys are dropped.
Attributes per span (custom) 64, prioritized (see below).
Key length 255 bytes. Longer keys are rejected with Length limit exceeded for attribute name, not adding: <key>.
String value length attributes.value_size_limit (default 256, capped at 4096). Longer values are truncated.
Reserved keys nr_flatten_leading cannot be set (Not overwriting value of NR-only attribute ...).

Attributes must also pass the include/exclude rules for at least one destination, or they are silently not stored.

addCustomAttribute(key, value)

Adds an attribute to the current transaction and to the currently active span. The most recent value for a key wins.

Parameter Type Description
key string Attribute name.
value string, number, boolean Attribute value.

Returns: false when the attribute was refused, otherwise undefined.

It returns false when:

  • high_security is true (logged once: Custom attributes are disabled by high security mode.);
  • api.custom_attributes_enabled is false;
  • there is no active transaction (No transaction found for custom attributes.);
  • the key is reserved.

On the transaction, the attribute targets transaction events, transaction traces, error events, and browser monitoring (subject to filters — browser attributes are off by default). On the span, it is added with low priority, so attributes added directly with addCustomSpanAttribute win when the span reaches its 64-attribute limit.

app.get('/cart', (req, res) => {
  newrelic.addCustomAttribute('customerTier', req.user.tier)
  newrelic.addCustomAttribute('itemCount', req.session.cart.length)
  res.render('cart')
})

addCustomAttributes(atts)

Calls addCustomAttribute for each own enumerable property of atts.

newrelic.addCustomAttributes({ region: 'eu-west', experiment: 'B', retries: 2 })

It does not return anything, so you cannot tell which individual keys were refused.

addCustomSpanAttribute(key, value)

Adds an attribute to the current span only (it does not appear on the transaction event). Useful to annotate one specific operation, such as a segment created with startSegment.

Returns: false when refused (high security mode, api.custom_attributes_enabled: false, no active span, reserved key), otherwise undefined.

await newrelic.startSegment('resizeImage', false, async () => {
  newrelic.addCustomSpanAttribute('image.width', width)
  return resize(file, width)
})

addCustomSpanAttributes(atts)

Calls addCustomSpanAttribute for each own property of atts.

setUserID(id)

Sets the enduser.id agent attribute on the current transaction. It is sent with transaction events, transaction traces, and errors that occur in that transaction.

Parameter Type Description
id string A unique user identifier.

With an empty id or no transaction, it logs User id is empty or not in a transaction, not assigning `enduser.id` attribute ... and does nothing.

Note: User IDs can be personal data. Prefer an opaque internal ID over an email address.

recordCustomEvent(eventType, attributes)

Records a custom event, queryable with NRQL (SELECT * FROM <eventType>). Events can be recorded inside or outside transactions.

Parameter Type Description
eventType string Event type name. Must match /^[a-zA-Z0-9:_ ]+$/ and be at most 255 characters.
attributes object A plain object. Keys must be at most 255 characters; values must be string, number, or boolean.

Returns: false when disabled by high security mode or api.custom_events_enabled: false; otherwise undefined.

newrelic.recordCustomEvent('CheckoutCompleted', {
  orderId: order.id,
  total: order.total,
  currency: 'EUR',
  firstPurchase: true
})

Validation details:

  • All arguments are checked before giving up, so one call can log several warnings (for example recordCustomEvent eventType of my-event is invalid, it must match /^[a-zA-Z0-9:_ ]+$/). Any failure means the event is dropped. Note that - and . are not allowed in the type.
  • attributes must be a plain object; an array or null is rejected (recordCustomEvent requires an object for its second argument ...).
  • Attribute values of other types are omitted individually, with an info log Omitting attribute <key> from <eventType> custom event call, type must be boolean, number, or string.
  • If custom_insights_events.enabled is false, the call returns silently without any log.
  • At most custom_insights_events.max_samples_stored events (default 3000) are kept per harvest cycle; beyond that, events are sampled by priority. Inside a sampled transaction, the event uses the transaction's priority; outside, a random priority.

recordMetric(name, value)

Records a custom metric named Custom/<name>.

Parameter Type Description
name string Metric name, following New Relic metric naming (segments separated by /).
value number or object A single measurement, or pre-aggregated statistics.

When value is a number, it is recorded as one measurement (for example a duration in your own unit).

When value is an object, it must have numeric count, total, min, max, and sumOfSquares; totalExclusive is optional and defaults to total. The statistics are merged with previous values for the same metric. This is useful for aggregating yourself and reporting periodically:

newrelic.recordMetric('Queue/depth', queue.length)

newrelic.recordMetric('Batch/processingTime', {
  count: 10,
  total: 4.2,
  min: 0.2,
  max: 0.9,
  sumOfSquares: 2.1
})

A non-string name logs Metric name must be a string. A missing statistic logs Metric object must include <key> as a number and records nothing.

incrementMetric(name, value)

Increments the call count of the custom metric Custom/<name>, acting as a counter.

Parameter Type Description
name string Metric name.
value integer Optional amount. Defaults to 1. 0 is accepted.

A non-integer value (such as 1.5) logs Metric Increment value must be an integer and is ignored.

newrelic.incrementMetric('Cache/miss')
newrelic.incrementMetric('Emails/sent', batch.length)

See Also