diff --git a/CHANGELOG.md b/CHANGELOG.md index d988257b244..56eaa9655a8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 651eb4a3fa1..b69966cdd58 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -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) @@ -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 @@ -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