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 when you query it. You can also automatically forward user information to New Relic.

Both default and custom attributes are visible in transaction traces, distributed traces, and error analytics; APM events and Browser events in dashboards. 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.

Tip

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:

Attributes added by a call to the NewRelic.addCustomParameter(...) 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
Important
Before creating custom attributes, review New Relic's list of reserved terms used by NRQL. Otherwise, you might get some unexpected results.

Attributes added by a call to the NewRelic.getAgent().getTracedMethod().addCustomAttribute(...) Java agent API. The key name for this attribute depends on what you specify when you call the method.

These attributes are added to span events, which can be found in the distributed tracing UI or directly queried in the query builder.

Important

Before creating custom attributes, review New Relic's list of reserved terms used by NRQL. Otherwise, you might get unexpected results.

The Java agent can capture the following 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.
The attribute system does not apply to any header values other than the ones listed above. If you want to capture additional request headers not listed here, you must use the custom_request_headers config option to specify headers for the agent to capture. Alternatively, you can directly record the headers yourself using 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

The Java agent captures request methods GET, POST and PUT by default as part of the request.method attribute.

Request parameters from the transaction are not captured by default. Use the addCustomParameter() Java agent API to capture request parameters.

The key for these attributes is request.parameters.*. If capturing sensitive information is a concern, you can use these options:

Avoid using wild cards in attributes.include. Instead, explicitly specify each field to capture.
If you want to use a wild card in attributes.include, explicitly exclude the sensitive fields using attributes.exclude.

Collect user attributes

With APM's Java agent, you can automatically collect user information in by editing your configuration file. You can then run NRQL queries against user information without needing to create custom attributes manually. This feature is available with New Relic's Java agent 3.10.0 or higher.

Important

Java user attributes are incompatible with high-security mode.

To collect the enduser.id user attribute via the public api with Java agent 8.1.0 or higher, call:

NewRelic.setUserId(String userId);

Here's an example code snippet setting the user ID:

@Trace(dispatcher = true)
public void run() {
    NewRelic.setUserId("example-user-id");
}

To collect user attributes via our servlet instrumentation with Java agent 3.10.0 or higher:

Open newrelic.yml, usually located in the same directory as newrelic.jar.

In the class_transformer section, edit com.newrelic.instrumentation.servlet-user to set enabled to true:

class_transformer:
  # This instrumentation reports the name of the user principal returned from 
  # HttpServletRequest.getUserPrincipal() when servlets and filters are invoked.
  com.newrelic.instrumentation.servlet-user:
    enabled: true

Restart your web server.

If you are using the 8.1.0 release of the Java agent, or higher, you can query the enduser.id attribute through either enabling com.newrelic.instrumentation.servlet-user or using the public API and waiting a few minutes. For example, you could use the following NRQL query to obtain a unique count of all users:

SELECT uniqueCount(enduser.id) FROM Transaction SINCE 1 day ago

Or if you are using the 3.10.0 release of the Java agent or higher, and enabled com.newrelic.instrumentation.servlet-user, you can query the user attribute within a few minutes:

SELECT uniqueCount(user) FROM Transaction SINCE 1 day ago

In both cases, if errors are reported, you can use the user attribute(s) to see how many users are impacted in a given error group.

Configure attributes: Enable, include, and exclude

You can configure which types of attributes, or which specific attributes, the Java agent reports to New Relic. This is often done for security reasons, when there are certain sensitive attributes you don't want reported to New Relic. To learn what settings override other settings, see the attribute configuration rules.

Attribute configuration options:

Destination	Configuration option	Default
All	`attributes.enabled`	True
Transaction traces	`transaction_tracer.attributes.enabled`	True
Transaction segments	`transaction_segments.attributes.enabled`	True
Error analytics	`error_collector.attributes.enabled`	True
APM events	`transaction_events.attributes.enabled`	True
Browser events	`browser_monitoring.attributes.enabled`	False
Span events	`span_events.attributes.enabled`	True

Other resources:

See the Java agent config file template.
See rules governing attribute configuration, including what settings override other settings.

Destination	Configuration option	Default
All	`attributes.include`	(none)
Transaction traces	`transaction_tracer.attributes.include`	(none)
Transaction segments	`transaction_segments.attributes.include`	(none)
Error analytics	`error_collector.attributes.include`	(none)
APM events	`transaction_events.attributes.include`	(none)
Browser events	`browser_monitoring.attributes.include`	(none)
Span events	`span_events.attributes.include`	(none)

Other resources:

See the Java agent config file template.
See rules governing attribute configuration, including what settings override other settings.

Destination	Configuration option	Default
All	`attributes.exclude`	(none)
Transaction traces	`transaction_tracer.attributes.exclude`	(none)
Transaction segments	`transaction_segments.attributes.exclude`	(none)
Error analytics	`error_collector.attributes.exclude`	(none)
APM events	`transaction_events.attributes.exclude`	(none)
Browser events	`browser_monitoring.attributes.exclude`	(none)
Span events	`span_events.attributes.exclude`	(none)

Other resources:

See the Java agent config file template.
See rules governing attribute configuration, including what settings override other settings.

Attribute rules

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

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

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

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

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

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

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.

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

Tip

Java-specific attributes

HTTP response codes

HTTP response messages

JVM threads

Locked JVM threads

Custom transaction attributes

Important

Custom span event attributes

Important

NoticeError() API calls

Request and response headers

Request parameters

Collect user attributes

Important

Enable collection of user attributes

View user attributes in dashboards

Configure attributes: Enable, include, and exclude

destination.attributes.enabled

destination.attributes.include

destination.attributes.exclude

Attribute rules

Setting attributes.enabled to false overrides all other settings.

Disabling all attributes

Setting a destination to false overrides include/exclude.

Disable one destination

Exclude overrides include.

Conflict between include and exclude settings

More specific rules take priority.

Conflicting specific settings

Keys are case-sensitive.

Keys which do not match the specified case

Use an asterisk for wildcards.

Match multiple input keys

Java agent attributes

Tip

Java-specific attributes .css-21sua1{background:none;border:none;width:0;padding:0;}

HTTP response messages

JVM threads

Locked JVM threads

Custom transaction attributes

Custom span event attributes

NoticeError() API calls

Request and response headers

Request parameters

Collect user attributes

Important

Enable collection of user attributes

View user attributes in dashboards

Configure attributes: Enable, include, and exclude

destination.attributes.enabled

destination.attributes.include

destination.attributes.exclude

Attribute rules

Setting attributes.enabled to false overrides all other settings.

Setting a destination to false overrides include/exclude.

Exclude overrides include.

More specific rules take priority.

Keys are case-sensitive.

Use an asterisk for wildcards.

Java-specific attributes