Distributed tracing settings control how the agent propagates trace context across services, configures span event collection, and enables Infinite Tracing.
Distributed tracing lets you see the path that a request takes as it travels through a distributed system. It is on by default for Java agent version 7.4.0 or higher.
In the config file, you can override this manually in the distributed_tracing section. You can also override this using a prefixed system property (newrelic.config.distributed_tracing) or an environment variable (NEW_RELIC_DISTRIBUTED_TRACING_ENABLED). See the examples below.
By default, supported versions of the agent utilize both the newrelic header and W3C Trace Context headers for distributed tracing. The newrelic distributed tracing header allows interoperability with older agents that don't support W3C Trace Context headers. Agent versions that support W3C Trace Context headers will prioritize them over newrelic headers for distributed tracing.
If you do not want to utilize the newrelic header, setting this to true will result in the agent excluding the newrelic header and only using W3C Trace Context headers for distributed tracing.
For example, to exclude newrelic headers in the config file, you would use:
distributed_tracing:
exclude_newrelic_header:true
To exclude newrelic headers using a system property, you would use:
Integer, between 1 (inclusive) and 120 (inclusive)
Default
120
Sets the global adaptive sampling target, shared by the root, remote_parent_sampled, and remote_parent_not_sampled contexts. This target controls the number of traces per minute the adaptive sampler attempts to capture. A context can override this global default with its own context-specific adaptive.sampling_target.
distributed_tracing:
sampler:
adaptive_sampling_target:30# Applied to all contexts without an explicit override
Overrides the global adaptive_sampling_target for the root context only, setting the number of root traces per minute the adaptive sampler attempts to capture.
distributed_tracing:
sampler:
adaptive_sampling_target:120# Global default
root:
adaptive:
sampling_target:5# Overrides global default to capture 5 traces/min for the root context
Type
Float, between 0.0 (exclusive) and 1.0 (inclusive)
The ratio property is required when using the trace_id_ratio_based sampler. If a ratio is not set, the default
Adaptive Sampler will be used for this context instead.
Since the Adaptive Sampler usually samples upstream-sampled traces (and does not count these towards the sampling target),
this setting generally has no effect. To sample only some remote_parent_sampled traces, prefer the trace_id_ratio_based sampler.
Type
Float, between 0.0 (exclusive) and 1.0 (inclusive)
The ratio property is required when using the trace_id_ratio_based sampler. If a ratio is not set, the default
Adaptive Sampler will be used for this context instead.
distributed_tracing:
sampler:
remote_parent_sampled:
trace_id_ratio_based:
ratio:0.2# Sample 20% of traces sampled by upstream
Type
String or nested property
Default
adaptive
Configures the sampler used for the remote parent not sampled context (an upstream service decided NOT to sample this trace). The possible values are:
Since the Adaptive Sampler usually does not sample traces that were not sampled by an upstream service, this setting
generally has no effect. To guarantee capture of some remote_parent_not_sampled traces, prefer the trace_id_ratio_based sampler.
Type
Float, between 0.0 (exclusive) and 1.0 (inclusive)
The ratio property is required when using the trace_id_ratio_based sampler. If a ratio is not set, the default
Adaptive Sampler will be used for this context instead.
distributed_tracing:
sampler:
remote_parent_not_sampled:
trace_id_ratio_based:
ratio:0.05# Sample 5% even if upstream said not to
Caution
Overriding upstream "not sampled" decisions can create fragmented traces where only some services are present. Use this pattern only when you have a specific need to see activity in a downstream service even when upstream didn't sample it.
For a deep dive into how these samplers work, adaptive sampling targets, and sampling contexts, see Configure sampling. For real-world configuration scenarios, see Sampler configuration examples.
You can also use the system property newrelic.config.infinite_tracing.trace_observer.host or the environment variable NEW_RELIC_INFINITE_TRACING_TRACE_OBSERVER_HOST.
Set span events configuration in the span_events section. These settings can be overridden with a newrelic.config.span_events prefixed system property. Options include:
Type
Boolean
Default
true
Used to enable/disable span event reporting.
Type
Integer
Default
2000
Max
10000
Determines the number of span events that can be captured during an agent harvest cycle. Available in Java agent 7.4.0 and above.
When configuring the agent for AI monitoring, set to max value 10000. Ensures that the maximum amount of traces are captured.
Important
Increasing the number of span events can lead to additional agent overhead.
Type
Boolean
Default
true
This setting can be used to turn on or off all attributes for span events. If attributes.enabled at the root level is false, no attributes will be sent to span events regardless on how this property (span_events.attributes.enabled) is set.
Type
List of strings
Default
(none)
If attributes are enabled for span events, all attribute keys found in this list will be sent to New Relic in span_events. For more information, see the agent attribute rules.
Type
List of strings
Default
(none)
All attribute keys found in this list will not be sent to New Relic in span events. For more information, see the agent attribute rules.
Cross application tracing has been deprecated as of agent version 7.4.0 and will be removed in a future agent version.
Instead of using cross application tracing, we recommend our distributed tracing features. Distributed tracing is an improvement on the cross application tracing feature and is recommended for large, distributed systems.
Set the cross application tracing options in the cross_application_tracer section. These settings can be overridden with a newrelic.config.cross_application_tracer prefixed system property.
Cross application tracing adds request and response headers to external calls using the Apache HttpClient libraries. This provides better performance data when calling applications monitored by other New Relic agents.