Skip to content

Commit d43e95b

Browse files
PeterF778kentquirkjmacdcarlosalberto
authored
Clarify in Composite Samplers OTEP the unreliable threshold case (#4569)
Addressing issue #4566. Fixes #4566 ## Changes Clarifying the meaning of `IsAjustedCountReliable`, providing guidance for selecting the Randomness value R for sampling decision making. * [ ] Related issues #4566 * [ ] Related [OTEP(s)](https://github.com/open-telemetry/oteps) # OTEP-0250 --------- Co-authored-by: Kent Quirk <[email protected]> Co-authored-by: Joshua MacDonald <[email protected]> Co-authored-by: Carlos Alberto Cortez <[email protected]>
1 parent 982ed98 commit d43e95b

File tree

1 file changed

+13
-3
lines changed

1 file changed

+13
-3
lines changed

oteps/trace/0250-Composite_Samplers.md

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ The composite samplers invoke the delegate samplers, but eventually make the fin
88
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).
99
Also see Draft PR 3910 [Probability Samplers based on W3C Trace Context Level 2](https://github.com/open-telemetry/opentelemetry-specification/pull/3910).
1010

11+
Document history:
12+
13+
- **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).
14+
1115
**Table of content:**
1216

1317
- [Motivation](#motivation)
@@ -101,6 +105,10 @@ The return value is a structure (`SamplingIntent`) with the following elements:
101105
- A function (`GetAttributes`) that provides a set of `Attributes` to be added to the `Span` in case of a positive final sampling decision,
102106
- 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).
103107

108+
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.
109+
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.
110+
See [ConsistentParentBased](#consistentparentbased) for an example of that.
111+
104112
#### Requirements for the basic samplers
105113

106114
The `ConsistentAlwaysOff` sampler MUST provide a `SamplingIntent` with
@@ -119,7 +127,7 @@ The `ConsistentAlwaysOn` sampler MUST provide a `SamplingIntent` with
119127

120128
The `ConsistentFixedThreshold` sampler, which is essentially `TraceIdRatioBased` sampler but implementing the `Composable` interface, MUST provide a `SamplingIntent` with
121129

122-
- 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),
130+
- 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),
123131
- `IsAdjustedCountReliable` returning `true`,
124132
- `GetAttributes` returning an empty set,
125133
- `UpdateTraceState` returning its argument, without any modifications.
@@ -129,11 +137,13 @@ The `ConsistentFixedThreshold` sampler, which is essentially `TraceIdRatioBased`
129137
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.
130138

131139
- The sampler gets its own `SamplingIntent`, it is a recursive process as described below (unless the sampler is a leaf),
132-
- The sampler compares the received THRESHOLD value with the trace Randomness value to arrive at the final sampling `Decision`,
140+
- If the received THRESHOLD value is `null`, the sampling decision is `DROP`, otherwise
141+
- 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
142+
- 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),
133143
- 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,
134144
- In case of positive sampling decision:
135145
- 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,
136-
- 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`,
146+
- 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`,
137147
- In case of negative sampling decision, it removes the `th` value for the `ot` key from the `Tracestate`.
138148

139149
### ConsistentRuleBased

0 commit comments

Comments
 (0)