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

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 transaction attributes

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

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

Custom span event attributes

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.

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

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

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 New Relic One 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.

Java user attributes are incompatible with high security mode.

Enable collection of user attributes

To collect user attributes with Java agent 3.10.0 or higher:

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

  2. In the class_transformer stanza, 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
  3. Restart your web server.
View user attributes in dashboards

Within a few minutes of enabling com.newrelic.instrumentation.servlet-user, you can query the new user attribute. For example, you could use this NRQL query to obtain a unique count of all users:

SELECT uniqueCount(user) FROM Transaction SINCE 1 day ago

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.attributes.enabled
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:

destination.attributes.include
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:

destination.attributes.exclude
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:

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 doesn't 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.

Match 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

If you need more help, check out these support and learning resources: