diff --git a/oteps/0250-Composite_Samplers.md b/oteps/0250-Composite_Samplers.md index 49debadf3b0..8653fca9327 100644 --- a/oteps/0250-Composite_Samplers.md +++ b/oteps/0250-Composite_Samplers.md @@ -194,18 +194,38 @@ The arguments are the same as for [`ShouldSample`](https://github.com/open-telem The return value is a structure (`SamplingIntent`) with the following elements: - The THRESHOLD value represented as a 14-character hexadecimal string, with value of `null` representing non-probabilistic `DROP` decision (implementations MAY use different representation, if it appears more performant or convenient), +- A function (`IsAdjustedCountReliable`) that provides a `boolean` value indicating that the adjusted count (calculated as reciprocal of the sampling probability) can be faithfully used to estimate span metrics, - A function (`GetAttributes`) that provides a set of `Attributes` to be added to the `Span` in case of 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. +#### Requirements for the basic samplers + +The `ConsistentAlwaysOff` sampler MUST provide a `SamplingIntent` with + +- The THRESHOLD value of `null` (or equivalent), +- `IsAdjustedCountReliable` returning `false`, +- `GetAttributes` returning an empty set, +- `UpdateTraceState` returning its argument, without any modifications. + +The `ConsistentAlwaysOn` sampler MUST provide a `SamplingIntent` with + +- The THRESHOLD value of `00000000000000` (or equivalent), +- `IsAdjustedCountReliable` returning `true`, +- `GetAttributes` returning an empty set, +- `UpdateTraceState` returning its argument, without any modifications. + + #### Constructing `SamplingResult` 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`, -- In case of a 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 `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, -- The sampler modifies (or removes) the `th` value for the `ot` key in the `Tracestate` according to the final sampling `Decision` and the THRESHOLD used in the second step above. +- 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`, +- In case of negative sampling decision, it removes the `th` value for the `ot` key from the `Tracestate`. ### ConsistentRuleBased @@ -226,7 +246,8 @@ Upon invocation of its `GetSamplingIntent` function, it MUST go through the whol `ConsistentAnyOf` sampler MUST return a `SamplingIntent` which is constructed as follows: -- If any of the delegates returned a non-`null` threshold value, the resulting threshold is the lexicographical minimum value from the set of those non-`null` values, otherwise `null`. +- If any of the delegates returned a non-`null` threshold value, the resulting threshold is the lexicographical minimum value T from the set of those non-`null` values, otherwise `null`. +- The `IsAdjustedCountReliable` returns `true`, if any of the delegates returning the threshold value equal to T returns `true` upon calling its `IsAdjustedCountReliable` function, otherwise it returns `false`. - The `GetAttributes` function calculates the union of `Attribute` sets as returned by the calls to `GetAttributes` function for each delegate, in the declared order. - The `UpdateTraceState` function makes a chain of calls to the `UpdateTraceState` functions as returned by the delegates, passing the received `Tracestate` as argument to subsequent calls and returning the last value received. @@ -246,8 +267,9 @@ Upon invocation of its `GetSamplingIntent` function, the composite sampler MUST The returned `SamplingIntent` is constructed as follows. -- If using the obtained threshold value as the final threshold would entail sampling more spans than the declared target rate, the sampler SHOULD increase the threshold to a value that would meet the target rate. Several algorithms can be used for threshold adjustment, no particular behavior is prescribed by the specification though. -- The `GetAttributes` function returns the union of the set of `Attributes` returned by calling the delegate's `GetAttributes` and own `Attributes`. +- If using the obtained threshold value as the final threshold would entail sampling more spans than the declared target rate, the sampler SHOULD set the threshold to a value that would meet the target rate. Several algorithms can be used for threshold adjustment, no particular behavior is prescribed by the specification though. +- The `IsAdjustedCountReliable` returns the result of calling this function on the `SamplingIntent` provided by the delegate. +- The `GetAttributes` function returns the result of calling this function on the `SamplingIntent` provided by the delegate. - The `UpdateTraceState` function returns the `Tracestate` as returned by calling `UpdateTraceState` from the delegate's `SamplingIntent`. TO DO: consider introducing a `ConsistentConjuntion` sampler (similar to `Conjunction` from Approach One) that would generalize the relationship between the delegate and the principal sampler, and remove the explicit delegate from `ConsistentRateLimiting`.