Skip to content

[trace/sampling] Revises ProbabilitySampler handling when randomness is not available #5039

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
yuanyuanzhao3 wants to merge 2 commits into from
+30 −26
Closed

[trace/sampling] Revises ProbabilitySampler handling when randomness is not available #5039

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3055661
[trace/sampling] Revises `ProbabilitySampler` spec to avoid and/or er…
yuanyuanzhao3 Apr 20, 2026
361d52a
Add CHANGELOG entry for ProbabilitySampler ot.th revision
yuanyuanzhao3 Apr 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@ release.

### Traces

- Revise `ProbabilitySampler` specification to avoid or erase the `ot.th` key
when trace ID randomness and an explicit `rv` value are not available. ([#5039](https://github.com/open-telemetry/opentelemetry-specification/pull/5039))

### Metrics

### Logs
Expand Down
53 changes: 27 additions & 26 deletions specification/trace/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,8 @@ weight: 3
- [Requirements for `TraceIdRatioBased` sampler algorithm](#requirements-for-traceidratiobased-sampler-algorithm)
- [Compatibility warnings for `TraceIdRatioBased` sampler](#compatibility-warnings-for-traceidratiobased-sampler)
+ [ProbabilitySampler](#probabilitysampler)
- [`ProbabilitySampler` sampler configuration](#probabilitysampler-sampler-configuration)
- [`ProbabilitySampler` sampler algorithm](#probabilitysampler-sampler-algorithm)
- [`ProbabilitySampler` configuration](#probabilitysampler-configuration)
- [`ProbabilitySampler` sampling algorithm](#probabilitysampler-sampling-algorithm)
- [Compatibility warnings for `ProbabilitySampler`](#compatibility-warnings-for-probabilitysampler)
+ [ParentBased](#parentbased)
+ [JaegerRemoteSampler](#jaegerremotesampler)
Expand Down Expand Up @@ -506,32 +506,32 @@ to use ProbabilitySampler.
**Status**: [Development](../document-status.md)

The `ProbabilitySampler` implements simple, ratio-based probability sampling using randomness features specified in the [W3C Trace Context Level 2][W3CCONTEXTMAIN] Candidate Recommendation.
OpenTelemetry follows W3C Trace Context Level 2, which specifies 56 bits of randomness,
[specifying how to make consistent probability sampling decisions using 56 bits of randomness][CONSISTENTSAMPLING].
W3C Trace Context Level 2 specifies 56 bits of randomness.
OpenTelemetry follows that model and [specifies how to make consistent probability sampling decisions using the 56 bits of randomness][CONSISTENTSAMPLING].

The `ProbabilitySampler` sampler MUST ignore the parent `SampledFlag`.
The `ProbabilitySampler` MUST ignore the parent `SampledFlag`.
For respecting the parent `SampledFlag`, see the `ParentBased` sampler specified below.

Note that this is a non-composable form of probability
sampler. `ProbabilitySampler` directly implements the SDKs Sampler
sampler. `ProbabilitySampler` directly implements the SDK's Sampler
API, whereas [`ComposableProbability`](#composableprobability) is the
composable form for use with [`CompositeSampler`](#compositesampler).

[W3CCONTEXTMAIN]: https://www.w3.org/TR/trace-context-2/

##### `ProbabilitySampler` sampler configuration
##### `ProbabilitySampler` configuration

The `ProbabilitySampler` sampler is typically configured using a 32-bit or 64-bit floating point number to express the sampling ratio.
The `ProbabilitySampler` is typically configured using a 32-bit or 64-bit floating point number to express the sampling ratio.
The minimum valid sampling ratio is `2^-56`, and the maximum valid sampling ratio is 1.0.
From an input sampling ratio, a rejection threshold value is calculated; see [consistent-probability sampler requirements][CONSISTENTSAMPLING] for details on converting sampling ratios into thresholds with variable precision.
From the input sampling ratio, a rejection threshold value is calculated; see [consistent-probability sampler requirements][CONSISTENTSAMPLING] for details on converting sampling ratios into thresholds with variable precision.

[CONSISTENTSAMPLING]: ./tracestate-probability-sampling.md

##### `ProbabilitySampler` sampler algorithm
##### `ProbabilitySampler` sampling algorithm

Given a Sampler configured with a sampling threshold `T` and Context with randomness value `R` (typically, the 7 rightmost bytes of the trace ID), when `ShouldSample()` is called, it uses the expression `R >= T` to decide whether to return `RECORD_AND_SAMPLE` or `DROP`.
Given a `ProbabilitySampler` configured with a sampling threshold `T` and Context with randomness value `R` (typically, the 7 rightmost bytes of the trace ID), when `ShouldSample()` is called, it uses the expression `R >= T` to decide whether to return `RECORD_AND_SAMPLE` or `DROP`.

* If randomness value (R) is greater or equal to the rejection threshold (T), meaning when (R >= T), return `RECORD_AND_SAMPLE`, otherwise, return `DROP`.
* If randomness value (R) is greater than or equal to the rejection threshold (T), meaning when (R >= T), return `RECORD_AND_SAMPLE`, otherwise, return `DROP`.
* When (R >= T), the OpenTelemetry TraceState SHOULD be modified to include the key-value `th:T` for rejection threshold value (T), as specified for the [OpenTelemetry TraceState `th` sub-key][TRACESTATEHANDLING].

[TRACESTATEHANDLING]: ./tracestate-handling.md#sampling-threshold-value-th
Expand All @@ -542,21 +542,22 @@ When a `ProbabilitySampler` makes a decision for a non-root Span
based on TraceID randomness, there is a possibility that the TraceID
was in fact generated by an older SDK, unaware of this specification.
The Trace random flag lets us disambiguate these two cases. This flag
propagates information to let ProbabilitySampler Samplers confirm that
TraceIDs are random, however this requires W3C Trace Context Level 2
to be supported by every Trace SDK that has handled the context.

When a ProbabilitySampler Sampler makes a decision for a non-root Span
propagates information to let ProbabilitySampler confirm whether
TraceIDs are random. For this disambiguation to work across the trace,
each Trace SDK that has handled the context MUST propagate the trace
flags from `traceparent` without dropping bits it does not interpret, so
the Random flag can reach downstream samplers. An SDK does not need to
implement all of W3C Trace Context Level 2 for this to work; forwarding
the trace flags unchanged is sufficient.

When a ProbabilitySampler makes a decision for a non-root Span
using [TraceID randomness when the Trace random flag was not
set](#presumption-of-traceid-randomness), the SDK SHOULD issue a
warning statement in its log with a compatibility warning. As an
example of this compatibility warning:

```
WARNING: The ProbabilitySampler sampler is presuming TraceIDs are random
and expects the Trace random flag to be set in confirmation. Please
upgrade your caller(s) to use W3C Trace Context Level 2.
```
set](#presumption-of-traceid-randomness) AND an explicit `rv` value is not available in `tracestate`,
the SDK SHOULD NOT include the sampler's `th` value in the OpenTelemetry (`ot`) entry in `tracestate`.
Furthermore, the sampler MUST erase any existing `th` sub-key from the
OpenTelemetry (`ot`) `tracestate` entry.
This is done so downstream processors and connectors can recognize this situation and MUST NOT infer statistical information
from spans sampled using this method.

#### ParentBased

Expand Down
Loading