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 thenewrelic.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 usingattributes.exclude
.
- Avoid using wild cards in
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:
- Open
newrelic.yml
, usually located in the same directory asnewrelic.jar
. -
In the
class_transformer
stanza, editcom.newrelic.instrumentation.servlet-user
to setenabled
totrue
: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.
- Open
- View user attributes in dashboards
-
Within a few minutes of enabling
com.newrelic.instrumentation.servlet-user
, you can query the newuser
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 tofalse
, 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