Node.js agent attributes

This document describes the New Relic Node.js agent attributes, details how to enable or disable attributes, and describes the rules the agent follows to determine which attributes to include or exclude for a destination.

These attribute settings apply to Node.js agent version 2.7.1 or higher. If you use an older version of the agent, see Update legacy attribute configuration.

Find and use attributes

New Relic attributes are key-value pairs containing information that determines the properties of event and transaction data. Attributes can help you gain greater insight into your application and annotate the data in New Relic Insights.

Attributes (both default and custom) can be found in:

You can customize exactly which attributes will be sent to each of these destinations.

Node.js-specific attributes

In addition to the default APM attributes, the Node.js agent collects attributes from these sources:

HTTP response codes

The response status code for a web request. The key for this attribute is httpResponseCode.

The default setting for each destination is:

  • Transaction traces: Enabled
  • Error analytics: Enabled
  • APM events: Enabled
  • Browser events: Disabled
HTTP response messages

The response status message if present for a web request. The key for this attribute is httpResponseMessage.

The default setting for each destination is:

  • Transaction traces: Enabled
  • Error analytics: Enabled
  • APM events: Enabled
  • Browser events: Disabled
Custom attributes

Attributes added to an addCustomAttribute() call to the Node.js agent API. The key name for this attribute depends on what you specify when you call the method.

The default setting for each destination is:

  • Transaction traces: Enabled
  • Error analytics: Enabled
  • APM events: Enabled
  • Browser events: Disabled

Before creating custom attributes, review New Relic's list of reserved terms used by NRQL and Insights. Otherwise unexpected results may occur.

noticeError() API calls

Attributes added to a noticeError() call on the Node.js agent API. The key name for this attribute depends on what you specify when you call the method.

The default setting for each destination is:

  • Transaction traces: Unavailable
  • Error analytics: Enabled
  • APM events: Unavailable
  • Browser events: Unavailable
Request and response headers

The Node.js agent can capture response and request headers as attributes. By default, the Node.js agent will collect all request headers that are not excluded.

Excluded HTTP request headers by default:

  • request.headers.cookie
  • request.headers.authorization
  • request.headers.proxy-authorization
  • request.headers.set-cookie*
  • request.headers.x-*

Captured response header: response.headers.content-type

You can disable collecting all the headers by setting allow_all_headers to false in your newrelic.js file.

The default setting for each destination is:

  • Transaction traces: Enabled
  • Error analytics: Enabled
  • APM events: Enabled
  • Browser events: Disabled
Request parameters

Request parameters from the transaction. The Node.js agent captures GET parameters by default. In order to capture POST parameters, use the addCustomAttribute() Node.js agent API call.

Configure attributes

You can customize what types of attributes the Node.js agent sends to each destination. This is most common for security reasons, when you have certain sensitive attributes you do not want to reported to New Relic.

Use the following configuration properties along with the attribute rules to enable or disable attributes:

allow_all_headers

Enabled by default. Set this to false for the agent to only collect a subset of headers.

destination.attributes.enabled
Destination Configuration option Default
All attributes.enabled True
Transaction traces transaction_tracer.attributes.enabled True
Error analytics error_collector.attributes.enabled True
APM events transaction_events.attributes.enabled True
Browser events browser_monitoring.attributes.enabled False

Enable or disable attributes entirely. If you set a destination to false, no attributes will be sent to that destination regardless of your include/exclude settings. If a destination is enabled, all user attributes are sent to that destination by default.

destination.attributes.include
Destination Configuration option Default
All attributes.include (none)
Transaction traces transaction_tracer.attributes.include (none)
Error analytics error_collector.attributes.include (none)
APM events transaction_events.attributes.include (none)
Browser events browser_monitoring.attributes.include (none)

Specify particular attribute keys you want the agent to report to New Relic. For all destinations, this is a list of strings that is empty by default. The .exclude properties override the .include properties.

destination.attributes.exclude
Destination Configuration option Default
All attributes.exclude (none)
Transaction traces transaction_tracer.attributes.exclude (none)
Error analytics error_collector.attributes.exclude (none)
APM events transaction_events.attributes.exclude (none)
Browser events browser_monitoring.attributes.exclude (none)

Specify particular attribute keys you do not want the agent to report to New Relic. For all destinations this is a list of strings that is empty by default. The .exclude properties override the .include properties.

Attribute rules

The Node.js agent follows these rules when determining which attributes to include or exclude for a destination:

Setting attributes.enabled to false overrides all other settings.

If you set the main attributes.enabled property to false, the agent does not report any attributes at all.

Disable all attributes

Agent configuration:

  • attributes.enabled: false
  • attributes.include: request.parameters.*
  • error_collector.attributes.enabled: true

Input keys:

  • foo
  • bar
  • request.parameters.foo
  • request.parameters.bar

Agent output:

  • Transaction traces: No attributes
  • Error analytics: No attributes
  • APM events: No attributes
  • Browser events: No attributes
Setting a destination to false overrides include/exclude.

When you set enabled to false for a destination, the agent ignores your include/exclude settings and not report any attributes for that destination.

Disable one destination

Agent configuration:

  • transaction_tracer.attributes.enabled: false
  • attributes.include: one, two*
  • transaction_tracer.attributes.include: three, four

Input keys:

  • one
  • two
  • three
  • four

Agent output:

  • Transaction traces: No attributes
  • Error analytics: one, two
  • APM events: one, two
  • Browser events: No attributes
Exclude overrides include.

The .exclude properties override the .include properties.

Conflict between include and exclude settings

Agent configuration:

  • attributes.enabled: true
  • attributes.include: foo, myCustomAtt
  • attributes.exclude: password, myCustomAtt

Input keys:

  • foo
  • myCustomAtt
  • password

Agent output:

  • Transaction traces: foo
  • Error analytics: foo
  • APM events: foo
  • Browser events: foo
More specific rules take priority.

If multiple include or exclude attributes affect the same key, the most specific setting will have priority.

Conflicts with specific settings

Agent configuration:

  • attributes.enabled: true
  • attributes.include: foo, myCustomAtt
  • attributes.exclude: password, myCustomAtt
  • browser_monitoring.attributes.enabled: true

Input keys:

  • food
  • food.bread
  • food.fruit.banana
  • food.fruit.apple

Agent output:

  • Transaction traces: food.fruit.apple
  • Error analytics: food.fruit.banana, food.fruit.apple
  • APM events: food.fruit.banana, food.fruit.apple
  • Browser events: food.fruit.banana, food.fruit.apple
Keys are case-sensitive.

The keys specified in the .include and .exclude properties are case-sensitive.

Keys do not match the specified case

Agent configuration:

  • attributes.enabled: true
  • attributes.exclude: password, PaSsWoRd

Input keys:

  • password
  • Password
  • PASSWORD
  • PaSsWoRd
  • PassWORD

Agent output:

  • Transaction traces: Password, PASSWORD, PassWORD
  • Error analytics: Password, PASSWORD, PassWORD
  • APM events: Password, PASSWORD, PassWORD
  • Browser events: Password, PASSWORD, PassWORD
Use an asterisk for wildcards.

You can use an asterisk * at the end of a key as a wildcard. This will match a set of attributes with the same prefix.

Wildcard matches multiple input keys

Agent configuration:

  • attributes.enabled: true
  • attributes.include: custom*
  • attributes.exclude: request.parameters.*

Input keys:

  • custom
  • custom.key1
  • custom.key2
  • request.parameters.
  • request.parameters.foo
  • request.parameters.bar

Agent output:

  • Transaction traces: custom, custom.key1, custom.key2
  • Error analytics: custom, custom.key1, custom.key2
  • APM events: custom, custom.key1, custom.key2
  • Browser events: custom, custom.key1, custom.key2

For more help

Recommendations for learning more: