APM agent samplers control which transactions within a given service your agent sends to New Relic. This page covers sampler types such as adaptive and trace ID ratio based, adaptive sampling targets, and how to configure sampling based on upstream sampling decisions.
Configuration examples in this guide use YAML format (Java agent). For agent-specific syntax and the complete parameter reference, see:
An upstream service decided not to sample this trace
Control sampling for traces the upstream service rejected
When it applies: The distributed trace originates from the current service (this is the first service in the distributed trace).
Example scenario: Your API gateway is the entry point for customer requests. Configure root sampling to capture 20% of these customer-initiated traces.
distributed_tracing:
sampler:
root:
trace_id_ratio_based:
ratio:0.2# 20% of traces originating here
When it applies: An upstream service decided to sample this distributed trace (the upstream service sent a sampling decision of "sampled" in the distributed trace context).
Common pattern: If the upstream service sampled the distributed trace, always sample it in the current service too:
distributed_tracing:
sampler:
remote_parent_sampled:
always_on # Always capture traces sampled by upstream
Alternative pattern: Sample a percentage of the traces already sampled by the upstream service:
distributed_tracing:
sampler:
remote_parent_sampled:
trace_id_ratio_based:
ratio:0.6# Sample 60% of traces sampled by upstream
Prudence
Overriding upstream "sampled" decisions can create fragmented traces where only some services are present. Use this pattern only when you have a specific need to drop traces that were sampled upstream.
When it applies: An upstream service decided not to sample this distributed trace (the upstream service sent a sampling decision of "not sampled" in the trace context).
Common pattern: If the upstream service did not sample the distributed trace, never sample it in the current service:
distributed_tracing:
sampler:
remote_parent_not_sampled:
always_off # Don't sample traces that upstream rejected
Alternative pattern: Sample some distributed traces even if upstream chose to not sample them (use cautiously):
distributed_tracing:
sampler:
remote_parent_not_sampled:
trace_id_ratio_based:
ratio:0.05# Sample 5% even if upstream said not to
Prudence
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.
Sampler types
APM agents provide four sampler types, each appropriate for different scenarios.
Disabling sampling entirely for a specific context
How it works: Dynamically adapts to the throughput of the service to sample a target number of root traces per minute, regardless of traffic volume. Always samples transactions that were sampled by an upstream service and doesn't count those towards the adaptive sampling target.
Default behavior: APM agents default to using the adaptive sampler. Most APM agents have a default adaptive sampling target of 10 transactions per minute. See each APM agent's configuration docs for more details.
When to use:
You want a consistent number of transactions sampled per minute - regardless of traffic changes - rather than a consistent percentage of traffic.
You want dynamic adjustment to space out sampling throughout each minute.
You want to sample all transactions that were sampled by the upstream service and not have those count towards the adaptive sampling target.
Configuration:
distributed_tracing:
sampler:
root: adaptive
How it adapts:
Low traffic (10 requests/min): Samples every request to hit target
Medium traffic (100 requests/min): Samples approximately every 5th request to hit target
High traffic (1000 requests/min): Samples approximately every 50th request to hit target
Conseil
The adaptive sampler always samples traces that were sampled by an upstream service. These traces don't count towards the configured adaptive sampling target.
Adaptive sampling targets
Adaptive sampling targets control how many traces per minute the agent attempts to capture. Understanding global vs per-context targets is crucial for predictable behavior.
The adaptive_sampling_target is shared by all contexts and is the default sampling target. A context may override
the global adaptive_sampling_target with its own, context-specific sampling_target.
The adaptive_sampling_target can be set to any integer between 1 and 120, inclusive.
Configuration:
distributed_tracing:
sampler:
adaptive_sampling_target:10# Applied to all contexts without explicit override
root: adaptive
Result: The agent attempts to capture approximately 10 transactions per minute that originate from the current service.
Each sampling context can override the global target with its own sampling_target.
The sampling_target can be set to any integer between 1 and 120, inclusive.
Configuration:
distributed_tracing:
sampler:
adaptive_sampling_target:10# Global default
root:
adaptive:
sampling_target:5# Overrides global default to capture 5 traces/min
Result: The agent attempts to capture 5 transactions per minute that originate from the current service, overriding the global default of 10.
Reasons to increase adaptive sampling targets
The default 10 traces/minute was designed for transaction tracing, not distributed tracing. For distributed tracing, you often want higher sampling to:
Fill service map gaps: Rare endpoints might never get sampled at 10/min
Improve trace diversity: See more transaction types and code paths
How it works: Samples a fixed percentage of traces based on the trace ID.
Because the sampling decision is based on trace ID, the same trace will get the same decision across all services using the same ratio sampler and APM language agent.
When to use:
You need a consistent percentage of traffic sampled.
You want deterministic sampling (the same distributed traces are sampled across all services with the same APM language agent).
You would like to avoid the behavior of the adaptive sampler where transactions that were sampled by the upstream service are always sampled and don't count towards the adaptive sampling target.
Every trace_id_ratio_based sampler must supply a ratio decimal between 0.0 (exclusive) and 1.0 (inclusive).
The ratio specifies the percentage of traces to capture.
Important
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 instead.
Configuration:
distributed_tracing:
sampler:
root:
trace_id_ratio_based:
ratio:0.1# 10% of traces
Important characteristic: The trace ID determines whether a trace is sampled. If multiple services use the same ratio and Language Agent, they'll make consistent decisions for the same trace.
Example: Sample 10% of root distributed traces and 50% of upstream-sampled distributed traces:
distributed_tracing:
sampler:
root:
trace_id_ratio_based:
ratio:0.1
remote_parent_sampled:
trace_id_ratio_based:
ratio:0.5
How it works: Samples all transactions matching this context.
When to use:
You need complete trace coverage for a specific context (root, remote_parent_sampled, remote_parent_not_sampled)
You want to follow or override the upstream service's sampling decision
Configuration:
distributed_tracing:
sampler:
remote_parent_sampled:
always_on # Capture all upstream-sampled traces
Prudence
Using always_on will capture every transaction for the given context, which can generate significant data volume for high-traffic services.
How it works: Samples none of the transactions for a given context.
When to use:
You want to accept the upstream service's decision not to sample
You want to disable sampling for a specific context
Configuration:
distributed_tracing:
sampler:
remote_parent_not_sampled:
always_off # Don't sample if upstream did NOT sample
Suggested configuration
With so many samplers to choose from, it can be hard to find the right configuration for your service. The best
way to find the configuration that works for you is to observe the distribution of traces your service has today,
and make small adjustments to work towards the distribution of traces that you want.
We recommend this configuration as a starting point:
distributed_tracing:
sampler:
root:
trace_id_ratio_based:
ratio:0.1
remote_parent_sampled:
always_on
remote_parent_not_sampled:
always_off
This configuration samples 10% of traces from the root context, all traces from the remote_parent_sampled context,
and no traces from the remote_parent_not_sampled context.
For some applications, this configuration is a reasonable starting point for a balanced distribution of traces. For others - for example, those where
most traces originate from an upstream service - this configuration may over-prioritize remote_parent_sampled traces
and under-prioritize root traces. In that case, try modifying the remote_parent_sampled configuration to capture
only a percentage of upstream-sampled traces:
distributed_tracing:
sampler:
root:
trace_id_ratio_based:
ratio:0.1
remote_parent_sampled:
trace_id_ratio_based:
ratio:0.2# Sample 20% of sampled traces originating upstream, instead of all of them
remote_parent_not_sampled:
always_off
What's next
Now that you understand sampling:
See the complete sampler configuration reference for your agent: Java, Node.js, Python
Sampling configuration can be complex. Start with a single pattern and iterate based on your actual trace volume and needs. Use supportability metrics and trace queries to verify your configuration is working as expected.