From a9a0488878b601ed4071837e3549cf52ca036324 Mon Sep 17 00:00:00 2001 From: Peter Findeisen Date: Tue, 24 Jun 2025 13:33:17 -0700 Subject: [PATCH 1/4] 4566 Clarifications for Composite Samplers proposal Addressing issue #4566. --- oteps/trace/0250-Composite_Samplers.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/oteps/trace/0250-Composite_Samplers.md b/oteps/trace/0250-Composite_Samplers.md index 39b18643008..c530137334d 100644 --- a/oteps/trace/0250-Composite_Samplers.md +++ b/oteps/trace/0250-Composite_Samplers.md @@ -101,6 +101,10 @@ The return value is a structure (`SamplingIntent`) with the following elements: - A function (`GetAttributes`) that provides a set of `Attributes` to be added to the `Span` in case of a positive final sampling decision, - A function (`UpdateTraceState`) that, given an input `Tracestate` and sampling Decision, provides a `Tracestate` to be associated with the `Span`. The samplers SHOULD NOT add or modify the `th` value for the `ot` key within these functions. The root node of the tree of composite samplers is solely responsible for setting or clearing this value (see Constructing `SamplingResult` below). +Returning `IsAdjustedCountReliable` as `false` indicates that even if the THRESHOLD value can be used to make the sampling decision, such decision may not be compatilbe with the Consistent Probability Sampling principles outlined in [TraceState: Probability Sampling](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/tracestate-probability-sampling.md#tracestate-probability-sampling), and, as the function name indicates, estimating metrics (such as call count) based on collected spans will not be possible. +For example, the sampling probability used in the process to arrive at the THRESHOLD value might directly or indirectly depend on the trace randomness value, the parent's `sampled` flag, or another non-probabilistic factor. +See [ConsistentParentBased](#consistentparentbased) for an example of that. + #### Requirements for the basic samplers The `ConsistentAlwaysOff` sampler MUST provide a `SamplingIntent` with @@ -119,7 +123,7 @@ The `ConsistentAlwaysOn` sampler MUST provide a `SamplingIntent` with The `ConsistentFixedThreshold` sampler, which is essentially `TraceIdRatioBased` sampler but implementing the `Composable` interface, MUST provide a `SamplingIntent` with -- The THRESHOLD value representing the threshold calculated according to the proposed [sampler requirements following OTEP 235](https://github.com/open-telemetry/opentelemetry-specification/pull/4166), +- The THRESHOLD value representing the threshold calculated according to the proposed [Rejection Threshold](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/tracestate-probability-sampling.md#rejection-threshold-t), - `IsAdjustedCountReliable` returning `true`, - `GetAttributes` returning an empty set, - `UpdateTraceState` returning its argument, without any modifications. @@ -129,11 +133,13 @@ The `ConsistentFixedThreshold` sampler, which is essentially `TraceIdRatioBased` The process of constructing the final `SamplingResult` in response to a call to `ShouldSample` on the root sampler of the composite samplers tree consists of the following steps. - The sampler gets its own `SamplingIntent`, it is a recursive process as described below (unless the sampler is a leaf), -- The sampler compares the received THRESHOLD value with the trace Randomness value to arrive at the final sampling `Decision`, +- If the received THRESHOLD value is `null`, the sampling decision is `DROP`, otherwise +- The sampler calls the received `IsAdjustedCountReliable` function, and in case of `true` derives the Randomness value R from the TraceState or TraceId as described in [Randomness Value (R)](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/tracestate-probability-sampling.md#randomness-value-r), and in case of `false` it generates a new Randomness value R by hex-encoding a new random 56-bit number +- The sampler compares (lexicographically or by other means, depending on the implementation) the received THRESHOLD value with the Randomness value R to arrive at the final sampling `Decision` as described in [Decision algorithm](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/tracestate-probability-sampling.md#decision-algorithm), - The sampler calls the received `UpdateTraceState` function passing the parent `Tracestate` and the final sampling `Decision` to get the new `Tracestate` to be associated with the `Span` - again, in most cases this is a recursive step, - In case of positive sampling decision: - the sampler calls the received `GetAttributes` function to determine the set of `Attributes` to be added to the `Span`, in most cases it will be a recursive step, - - the sampler calls the received `IsAdjustedCountReliable` function, and in case of `true` it modifies the `th` value for the `ot` key in the `Tracestate` according to the received THRESHOLD; if the returned value is `false`, it removes the `th` value for the `ot` key from the `Tracestate`, + - if the `IsAdjustedCountReliable` function returned `true` it modifies the `th` value for the `ot` key in the `Tracestate` according to the received THRESHOLD; if the returned value was `false`, it removes the `th` value for the `ot` key from the `Tracestate`, - In case of negative sampling decision, it removes the `th` value for the `ot` key from the `Tracestate`. ### ConsistentRuleBased From 5da90036cc959045e10a694567dd8511006c439d Mon Sep 17 00:00:00 2001 From: Peter Findeisen Date: Thu, 31 Jul 2025 11:27:05 -0700 Subject: [PATCH 2/4] Update oteps/trace/0250-Composite_Samplers.md Co-authored-by: Kent Quirk --- oteps/trace/0250-Composite_Samplers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/oteps/trace/0250-Composite_Samplers.md b/oteps/trace/0250-Composite_Samplers.md index c530137334d..acd98d58d62 100644 --- a/oteps/trace/0250-Composite_Samplers.md +++ b/oteps/trace/0250-Composite_Samplers.md @@ -101,7 +101,7 @@ The return value is a structure (`SamplingIntent`) with the following elements: - A function (`GetAttributes`) that provides a set of `Attributes` to be added to the `Span` in case of a positive final sampling decision, - A function (`UpdateTraceState`) that, given an input `Tracestate` and sampling Decision, provides a `Tracestate` to be associated with the `Span`. The samplers SHOULD NOT add or modify the `th` value for the `ot` key within these functions. The root node of the tree of composite samplers is solely responsible for setting or clearing this value (see Constructing `SamplingResult` below). -Returning `IsAdjustedCountReliable` as `false` indicates that even if the THRESHOLD value can be used to make the sampling decision, such decision may not be compatilbe with the Consistent Probability Sampling principles outlined in [TraceState: Probability Sampling](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/tracestate-probability-sampling.md#tracestate-probability-sampling), and, as the function name indicates, estimating metrics (such as call count) based on collected spans will not be possible. +Returning `IsAdjustedCountReliable` as `false` indicates that even if the THRESHOLD value can be used to make the sampling decision, such decision may not be compatible with the Consistent Probability Sampling principles outlined in [TraceState: Probability Sampling](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/tracestate-probability-sampling.md#tracestate-probability-sampling), and, as the function name indicates, estimating metrics (such as call count) based on collected spans will not be possible. For example, the sampling probability used in the process to arrive at the THRESHOLD value might directly or indirectly depend on the trace randomness value, the parent's `sampled` flag, or another non-probabilistic factor. See [ConsistentParentBased](#consistentparentbased) for an example of that. From d1890766b1241cbaa39b4da4cf52de98be190f7f Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Thu, 14 Aug 2025 08:44:08 -0700 Subject: [PATCH 3/4] Add note about PR 4569 after release --- oteps/trace/0250-Composite_Samplers.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/oteps/trace/0250-Composite_Samplers.md b/oteps/trace/0250-Composite_Samplers.md index acd98d58d62..356442ce612 100644 --- a/oteps/trace/0250-Composite_Samplers.md +++ b/oteps/trace/0250-Composite_Samplers.md @@ -8,6 +8,9 @@ The composite samplers invoke the delegate samplers, but eventually make the fin The new samplers proposed here have been designed to work with Consistent Probability Samplers. For detailed description of this concept see [probability sampling (OTEP 235)](https://github.com/open-telemetry/oteps/blob/main/text/trace/0235-sampling-threshold-in-trace-state.md). Also see Draft PR 3910 [Probability Samplers based on W3C Trace Context Level 2](https://github.com/open-telemetry/opentelemetry-specification/pull/3910). +Document history: +- **Revision** [Specification release 1.48.0 was released before a minor update to this OTEP, which states that when an "unreliable" sampling threshold is used to make a sampling decision, a new independent randomness value should be used and discarded to preserve independence.](https://github.com/open-telemetry/opentelemetry-specification/pull/4569). + **Table of content:** - [Motivation](#motivation) From 482f9aa7ed85a6800a066132bcffa00eb0bb51e5 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 14 Aug 2025 19:24:39 +0200 Subject: [PATCH 4/4] Update oteps/trace/0250-Composite_Samplers.md --- oteps/trace/0250-Composite_Samplers.md | 1 + 1 file changed, 1 insertion(+) diff --git a/oteps/trace/0250-Composite_Samplers.md b/oteps/trace/0250-Composite_Samplers.md index 356442ce612..55f26bc6cfc 100644 --- a/oteps/trace/0250-Composite_Samplers.md +++ b/oteps/trace/0250-Composite_Samplers.md @@ -9,6 +9,7 @@ The new samplers proposed here have been designed to work with Consistent Probab Also see Draft PR 3910 [Probability Samplers based on W3C Trace Context Level 2](https://github.com/open-telemetry/opentelemetry-specification/pull/3910). Document history: + - **Revision** [Specification release 1.48.0 was released before a minor update to this OTEP, which states that when an "unreliable" sampling threshold is used to make a sampling decision, a new independent randomness value should be used and discarded to preserve independence.](https://github.com/open-telemetry/opentelemetry-specification/pull/4569). **Table of content:**