Adaptive Tail Sampling Processor
OpenTelemetry Collector processor · contrib distribution
The Adaptive Tail Sampling Processor performs adaptive trace sampling using first-match rules-based routing to adaptive samplers. Each sampler produces a known sample rate which is encoded as ot=th in W3C TraceState for correct downstream metric weighting.
- Component ID:
contrib-adaptivetailsamplingprocessor - Name:
adaptivetailsamplingprocessor - Type: processor
- Distribution: contrib
- Repository:
opentelemetry-collector-contrib
Stability
| Level | Signals |
|---|---|
| alpha | traces |
Internal telemetry
| Metric | Type | Value type | Unit | Stability | Enabled | Attributes | Description |
|---|---|---|---|---|---|---|---|
processor_adaptive_tail_sampling_decision_sample_rate | histogram | int | {rate} | development | yes | Distribution of effective sample rates produced per rule. Useful for detecting adaptive samplers settling at unexpected rates. | |
processor_adaptive_tail_sampling_decision_triggers | sum (monotonic) | int | {decisions} | development | yes | Number of trace decisions made, labelled by which event triggered the decision (root_span, trace_timeout, eviction, shutdown, span_limit). | |
processor_adaptive_tail_sampling_fingerprint_duration | histogram | int | us | development | yes | Time spent extracting a rule's fingerprint per decision, in microseconds, labelled by rule. A relative signal for spotting expensive fingerprints (wide scopes such as any. on large traces); absolute values depend on host and load. | |
processor_adaptive_tail_sampling_fleet_member_count | gauge | int | {instances} | development | yes | Current fleet member count reported by the fleet_tracker extension; the processor divides each rule's goal_throughput by this value. Not emitted when fleet_tracker is unset. | |
processor_adaptive_tail_sampling_fleet_tracker_errors | sum (monotonic) | int | {errors} | development | yes | Number of non-positive member counts received from the fleet tracker; the last good count is kept. | |
processor_adaptive_tail_sampling_incoming_tracestate_unparseable | sum (monotonic) | int | {spans} | development | yes | Number of spans whose incoming W3C tracestate could not be parsed when applying the sampling threshold. | |
processor_adaptive_tail_sampling_ottl_eval_errors | sum (monotonic) | int | {errors} | development | yes | Number of OTTL condition evaluation errors, labelled by the rule the condition belongs to (_root_span_condition for the root-span condition). | |
processor_adaptive_tail_sampling_sampler_burst_count | sum (monotonic) | int | {bursts} | development | yes | Cumulative number of intervals in which an adaptive sampler (adaptive_percentage or adaptive_throughput) detected a burst of traffic, labelled by rule, sampler_type, and sampler_algorithm. Not emitted for adaptive_throughput rules using the windowed algorithm, which do not track this counter. | |
processor_adaptive_tail_sampling_sampler_keyspace_size | gauge | int | {keys} | development | yes | Current number of distinct sampling keys tracked by an adaptive sampler (adaptive_percentage or adaptive_throughput), labelled by rule, sampler_type, and sampler_algorithm. A rising value indicates growing key cardinality, which can degrade sampler accuracy and memory use. | |
processor_adaptive_tail_sampling_sampler_request_count | sum (monotonic) | int | {requests} | development | yes | Cumulative number of sample-rate requests made to an adaptive sampler (adaptive_percentage or adaptive_throughput) since it started, labelled by rule, sampler_type, and sampler_algorithm. | |
processor_adaptive_tail_sampling_trace_span_count | histogram | int | {spans} | development | yes | Distribution of buffered span counts per trace at decision time, labelled by rule. Useful for sizing span_limit against the real trace-size distribution. | |
processor_adaptive_tail_sampling_traces_active | gauge | int | {traces} | development | yes | Number of traces currently in the accumulation buffer awaiting a decision. | |
processor_adaptive_tail_sampling_traces_dropped | sum (monotonic) | int | {traces} | development | yes | Number of traces that were dropped, labelled by the rule that selected them. Sentinel rule values are prefixed with an underscore (e.g. _unmatched, _eviction). | |
processor_adaptive_tail_sampling_traces_evicted | sum (monotonic) | int | {traces} | development | yes | Number of traces evicted from the buffer due to num_traces pressure. Evicted traces are decided immediately per the configured eviction policy. | |
processor_adaptive_tail_sampling_traces_sampled | sum (monotonic) | int | {traces} | development | yes | Number of traces that were sampled, labelled by the rule that selected them. Sentinel rule values are prefixed with an underscore (e.g. _eviction). |