From db5b7c95aba0f8da05860847dbdf93a622abd0c9 Mon Sep 17 00:00:00 2001 From: Kent Quirk Date: Tue, 30 Jan 2024 12:08:47 -0500 Subject: [PATCH] Threshold propagation in trace state (open-telemetry/oteps#235) This is intended to capture the proposal developed by [the Sampling SIG](https://docs.google.com/document/d/1gASMhmxNt9qCa8czEMheGlUW2xpORiYoD7dBD7aNtbQ/edit#heading=h.mngoctm0c84w). --------- Co-authored-by: Joshua MacDonald Co-authored-by: Spencer Wilson <5624115+spencerwilson@users.noreply.github.com> Co-authored-by: Otmar Ertl Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com> --- .../0235-sampling-threshold-calculation.png | Bin 0 -> 122136 bytes .../0235-sampling-threshold-in-trace-state.md | 184 ++++++++++++++++++ 2 files changed, 184 insertions(+) create mode 100644 oteps/img/0235-sampling-threshold-calculation.png create mode 100644 oteps/trace/0235-sampling-threshold-in-trace-state.md diff --git a/oteps/img/0235-sampling-threshold-calculation.png b/oteps/img/0235-sampling-threshold-calculation.png new file mode 100644 index 0000000000000000000000000000000000000000..b4a9063b6d33623bca884d29b8160777dbc740d8 GIT binary patch literal 122136 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%0Dr*SF%mCsXV!U2?khL{P@ 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 literal 0 HcmV?d00001 diff --git a/oteps/trace/0235-sampling-threshold-in-trace-state.md b/oteps/trace/0235-sampling-threshold-in-trace-state.md new file mode 100644 index 000000000..014744a73 --- /dev/null +++ b/oteps/trace/0235-sampling-threshold-in-trace-state.md @@ -0,0 +1,184 @@ +# Sampling Threshold Propagation in TraceState + +## Motivation + +Sampling is a broad topic; here it refers to the independent decisions made at points in a distributed tracing system of whether to collect a span or not. Multiple sampling decisions can be made before a span is finally consumed. When sampling is to be performed at multiple points in the process, the only way to reason about it effectively is to make sure that the sampling decisions are **consistent**. +In this context, consistency means that a positive sampling decision made for a particular span with probability p1 implies a positive sampling decision for any span belonging to the same trace, if it is made with probability p2 >= p1. + +## Explanation + +The existing, experimental [specification for probability sampling using TraceState](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/tracestate-probability-sampling.md) is limited to powers-of-two probabilities, and is designed to work without making assumptions about TraceID randomness. +This system can only achieve non-power-of-two sampling using interpolation between powers of two, which is unnecessarily restrictive. +In existing sampling systems, sampling probabilities like 1%, 10%, and 75% are common, and it should be possible to express these without interpolation. +There is also a need for consistent sampling in the collection path (outside of the head-sampling paths) and using inherent randomness in the traceID is a less-expensive solution than referencing a custom `r-value` from the tracestate in every span. +This proposal introduces a new value with the key `th` as an alternative to the `p` value in the previous specification. +The `p` value is limited to powers of two, while the `th` value in this proposal supports a large range of values. +This proposal allows for the continued expression of randomness using `r-value` as specified there using the key `r`. +To distinguish the cases, this proposal uses the key `rv`. + +In the general case, in order to make consistent sampling decisions across the entire path of the trace, two values MUST be present in the `SpanContext`: + +1. A _random_ (or pseudo-random) 56-bit value, called `R` below. +2. A 56-bit _rejection threshold_ (or just "threshold") as expressed in the TraceState, called `T` below. `T` represents the maximum threshold that was applied in all previous consistent sampling stages. If the current sampling stage applies a greater-valued threshold than any stage before, it MUST update (increase) the threshold correspondingly. + +One way to think about _rejection threshold_ is that is the number of spans that would be discarded out of 2^56 considered spans. This means that spans where `R >= T` will be sampled. + +Here is an example involving three participants `A`, `B`, and `C`: + +`A` -> `B` -> `C` + +where -> indicates a parent -> child relationship. + +`A` uses consistent probability sampling with a sampling probability of 0.25 (this corresponds to a rejection probability of .75). +`B` uses consistent probability sampling with a sampling probability of 0.5. +`C` uses a parent-based sampler. + +When `A` samples a span, its outgoing traceparent will have the 'sampled' flag SET and the 'th' in its outgoing tracestate will be set to `0xc0_0000_0000_0000`. +When `A` does not sample a span, its outgoing traceparent will have the 'sampled' flag UNSET but the 'th' in its outgoing tracestate will still be set to `0xc0_0000_0000_0000`. +When B samples a span, its outgoing traceparent will have the 'sampled' flag SET and the 'th' in its outgoing tracestate will be set to `0x80_0000_0000_0000`. +C (being a parent based sampler) samples a span purely based on its parent (B in this case), it will use the sampled flag to make the decision. Its outgoing 'th' value will continue to reflect what it got from B (`0x80_0000_0000_0000`), and this is useful to understand its adjusted count. + +This design requires that as a given span progresses along its collection path, `th` is non-decreasing (and, in particular, must be increased at stages that apply lower sampling probabilities). +It does not, however, restrict a span's initial `th` in any way (e.g., relating it to that of its parent, if it has one). +It is acceptable for B to have a lesser initial `th` than A has. It would not be ok if some later-stage sampler decreased A's `th`. + +The system has the following invariant: + +`(R >= T) = sampled flag` + +The sampling decision is propagated with the following algorithm: + +* If the `th` key is not specified, this implies that non-probabilistic sampling may be taking place. +* Else derive `T` by parsing the `th` key as a hex value as described below. +* If `T` is 0, Always Sample. +* Compare the 56 bits of `T` with the 56 bits of `R`. If `T > R`, then do not sample. + +The `R` value MUST be derived as follows: + +* If the key `rv` is present in the Tracestate header, then `R = rv`. +* Else if the Random Trace ID Flag is `true` in the traceparent header, then `R` is the lowest-order 56 bits of the trace-id. +* Else `R` MUST be generated as a random value in the range `[0, (2**56)-1]` and added to the Tracestate header with key `rv`. + +The preferred way to propagate the `R` value is as the lowest 56 bits of the trace-id. +If these bits are in fact random, the `random` trace-flag SHOULD be set as specified in [the W3C trace context specification](https://w3c.github.io/trace-context/#trace-id). +There are circumstances where trace-id randomness is inadequate (for example, sampling a group of traces together); in these cases, an `rv` value is required. + +The value of the `rv` and `th` keys MUST be expressed as up to 14 hexadecimal digits from the set `[0-9a-f]`. For `th` keys only, trailing zeros (but not leading zeros) may be omitted. `rv` keys MUST always be exactly 14 hex digits. + +Examples: + +- `th` value is missing: non-probabalistic sampling may be taking place. +- `th=4` -- equivalent to `th=40000000000000`, which is a 25% rejection threshold, corresponding to a 75% sampling probability. +- `th=c` -- equivalent to `th=c0000000000000`, which is a rejection threshold of 75%, corresponding to a sampling probability of 25%. +- `th=08` -- equivalent to `th=08000000000000`, which is a rejection threshold of 3.125%, corresponding to a sampling probability of 96.875%. +- `th=0` -- equivalent to `th=00000000000000`, which is a 0% rejection threshold, which means Always Sample. + +The `T` value MUST be derived as follows: + +* If the `th` key is not present in the Tracestate header, then non-probabalistic sampling may be in use. +* Else the value corresponding to the `th` key should be interpreted as above. + +Sampling Decisions MUST be propagated by setting the value of the `th` key in the Tracestate header according to the above. + +## Initializing and updating T and R values + +There are two categories of sampler: + +- **Head samplers:** Implementations of [`Sampler`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.29.0/specification/trace/sdk.md#sampler), called by a `Tracer` during span creation. +- **Downstream samplers:** Any component that, given an ended Span, decides whether to drop or forward ("sample") it on to the next component in the system. Also known as "collection-path samplers" or "sampling processors". _Tail samplers_ are a special class of downstream samplers that buffer the spans in a trace and select a sampling probability for the trace as a whole using data from any span in the buffered trace. + +This section defines behavior for each kind of sampler. + +### Head samplers + +A head sampler is responsible for computing the `rv` and `th` values in a new span's initial [`TraceState`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.29.0/specification/trace/api.md#tracestate). Notable inputs to that computation include the parent span's trace state (if a parent span exists) and the new span's trace ID. + +First, a consistent `Sampler` decides which sampling probability to use. The sampler MAY select any value of T. If a valid `SpanContext` is provided in the call to `ShouldSample` (indicating that the span being created will be a child span), + +- Choosing a T greater than the parent span's is expected to result in partial traces (the parent may be sampled but its child, the current span, dropped). +- Choosing a T less than or equal to the parent span is expected to result in complete traces (this is definition of consistent probability sampling). + +For the output TraceState, + +- The `th` key MUST be defined with a value corresponding to the sampling probability the sampler actually used. +- The `rv` value, if present on the input TraceState, MUST be defined and equal to the parent span's `rv`. Otherwise, `rv` MUST be defined if and only if the effective R was _generated_ during the decision, per the "derive R" algorithm given earlier. + +TODO: For _new_ spans, `ShouldSample` doesn't currently have a way to know the new Span's `TraceFlags`, so it can't determine whether the Random Trace ID Flag is set, and in turn can't execute the "derive R" algorithm. Maybe it should take `TraceFlags` as an additional parameter, just like it takes `TraceId`? + +### Downstream samplers + +A downstream sampler, in contrast, may output a given ended Span with a _modified_ trace state, complying with following rules: + +- If the chosen sampling probability is 1, the sampler MUST NOT modify any existing `th`, nor set any `th`. +- Otherwise, the chosen sampling probability is in `(0, 1)`. In this case the sampler MUST output the span with a `th` equal to `max(input th, chosen th)`. In other words, `th` MUST NOT be decreased (as it is not possible to retroactively adjust an earlier stage's sampling probability), and it MUST be increased if a lower sampling probability was used. This case represents the common case where a downstream sampler is reducing span throughput in the system. + +## Visual + +![Sampling decision flow](../img/0235-sampling-threshold-calculation.png) + +## Algorithms + +The `th` and `rv` values may be represented and manipulated in a variety of forms depending on the capabilities of the processor and needs of the implementation. As 56-bit values, they are compatible with byte arrays and 64-bit integers, and can also be manipulated with 64-bit floating point with a truly negligible loss of precision. + +The following examples are in Python3. They are intended as examples only for clarity, and not as a suggested implementation. + +### Converting t-value to a 56-bit integer threshold + +To convert a t-value string to a 56-bit integer threshold, pad it on the right with 0s so that it is 14 digits in length, and then parse it as a hexadecimal value. + +```py +padded = (tvalue + "00000000000000")[:14] +threshold = int('0x' + padded, 16) +``` + +### Converting integer threshold to a t-value + +To convert a 56-bit integer threshold value to the t-value representation, emit it as a hexadecimal value (without a leading '0x'), optionally with trailing zeros omitted: + +```py +h = hex(tvalue).rstrip('0') +# remove leading 0x +tv = 'tv='+h[2:] +``` + +### Testing rv vs threshold + +Given rv and threshold as 64-bit integers, a sample should be taken if rv is greater than or equal to the threshold. + +``` +shouldSample = (rv >= threshold) +``` + +### Converting threshold to a sampling probability + +The sampling probability is a value from 0.0 to 1.0, which can be calculated using floating point by dividing by 2^56: + +```py +# embedded _ in numbers for clarity (permitted by Python3) +maxth = 0x100_0000_0000_0000 # 2^56 +prob = float(maxth - threshold) / maxth +``` + +### Converting threshold to an adjusted count (sampling rate) + +The adjusted count indicates the approximate quantity of items from the population that this sample represents. It is equal to `1/probability`. It is not defined for spans that were obtained via non-probabilistic sampling (a sampled span with no `th` value). + +## Trade-offs and mitigations + +This proposal is the result of long negotiations on the Sampling SIG over what is required and various alternative forms of expressing it. [This issue](https://github.com/open-telemetry/opentelemetry-specification/issues/3602) exhaustively covers the various formats that were discussed and their pros and cons. This proposal is the result of that decision. + +## Prior art and alternatives + +The existing specification for `r-value` and `p-value` attempted to solve this problem, but were limited to powers of 2, which is inadequate. + +## Open questions + +This specification leaves room for different implementation options. For example, comparing hex strings or converting them to numeric format are both viable alternatives for handling the threshold. + +We also know that some implementations prefer to use a sampling probability (in the range from 0-1.0) or a sampling rate (1/probability); this design permits conversion to and from these formats without loss up to at least 6 decimal digits of precision. + +## Future possibilities + +This permits sampling systems to propagate consistent sampling information downstream where it can be compensated for. +For example, this will enable the tail-sampling processor in the OTel Collector to propagate its sampling decisions to backends in a standard way. +This permits backend systems to use the effective sampling probability in data presentations.