Java agent attributes

New Relic attributes are key-value pairs containing information that determines the properties of an event or transaction. These key-value pairs can help you gain greater insight into your application and annotate the data in New Relic Insights. You can also automatically forward user information to New Relic Insights.

Both default and custom attributes are visible in APM transaction traces and error analytics; APM events in Insights; and Browser events in Insights. You can customize exactly which attributes will be sent to each of these destinations.

This document describes the Java 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 version 3.7.0 or higher of the Java agent. If you use an older version of the agent, see Update legacy attribute configuration.

Java-specific attributes

In addition to the default APM attributes, the Java 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
JVM threads

The name of the thread. The key for this attribute is jvm.thread_name.

The default setting for each destination is:

  • Transaction traces: Enabled
  • Error analytics: Enabled
  • APM events: Disabled
  • Browser events: Unavailable
Locked JVM threads

The name of a locked thread. The key for this attribute is jvm.lock_thread_name.

The default setting for each destination is:

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

Attributes added to an addCustomParameter() call to the Java 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: Disabled
  • 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 Java 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 Java agent can capture response and request headers as attributes:

Captured HTTP request headers:

  • request.headers.referer
  • request.headers.accept
  • request.headers.contentLength
  • request.headers.host
  • request.headers.userAgent

Captured response header: response.headers.contentType

The agent does not capture other request headers by default. You also cannot specify additional request headers to be captured as attributes by including them within the attributes.include stanza of the newrelic.yml.

If you want to capture additional request headers, whether custom or standard, use the addCustomParameter() method from the Java agent API.

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 Java agent captures GET parameters by default. In order to capture POST parameters, use the addCustomParameter() Java agent API call. The key for these attributes is request.parameters.*.

Configure attributes

You can customize what types of attributes the Java 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:

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 Java 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.

Disabling 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.

Conflicting 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 which 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 matching 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

Additional documentation resources include:

Join the discussion about Java monitoring in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.