diff --git a/CHANGELOG.md b/CHANGELOG.md index f02987a0951..2f826d6abb2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,9 @@ release. ### Traces +- Restore `TraceIdRatioBased` and give it a deprecation timeline. Update recommended + warnings based on feedback in issue [#4601](https://github.com/open-telemetry/opentelemetry-specification/issues/4601). + ([#4627](https://github.com/open-telemetry/opentelemetry-specification/pull/4627)) - Changes of `TracerConfig.disabled` MUST be eventually visible. ([#4645](https://github.com/open-telemetry/opentelemetry-specification/pull/4645)) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 6045bcd8e97..12ccfac020b 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -33,10 +33,12 @@ weight: 3 + [AlwaysOn](#alwayson) + [AlwaysOff](#alwaysoff) + [TraceIdRatioBased](#traceidratiobased) - - [`TraceIdRatioBased` sampler configuration](#traceidratiobased-sampler-configuration) - - [`TraceIdRatioBased` sampler algorithm](#traceidratiobased-sampler-algorithm) - - [`TraceIdRatioBased` sampler description](#traceidratiobased-sampler-description) - - [`TraceIdRatioBased` sampler compatibility warning](#traceidratiobased-sampler-compatibility-warning) + - [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) + - [Compatibility warnings for `ProbabilitySampler`](#compatibility-warnings-for-probabilitysampler) + [ParentBased](#parentbased) + [JaegerRemoteSampler](#jaegerremotesampler) + [CompositeSampler](#compositesampler) @@ -45,7 +47,7 @@ weight: 3 - [Built-in ComposableSamplers](#built-in-composablesamplers) * [ComposableAlwaysOn](#composablealwayson) * [ComposableAlwaysOff](#composablealwaysoff) - * [ComposableTraceIDRatioBased](#composabletraceidratiobased) + * [ComposableProbability](#composableprobability) * [ComposableParentThreshold](#composableparentthreshold) * [ComposableRuleBased](#composablerulebased) * [ComposableAnnotating](#composableannotating) @@ -428,13 +430,86 @@ The default sampler is `ParentBased(root=AlwaysOn)`. #### TraceIdRatioBased +**Status**: [Stable](../document-status.md) + +The `TraceIdRatioBased` sampler is deprecated in favor of the +composable [`ProbabilitySampler`](#probabilitysampler). This +component is being [phased out to address a "TODO" in the 1.0 trace +specification](https://github.com/open-telemetry/opentelemetry-specification/issues/1413). +OpenTelemetry SDK implementors SHALL NOT remove or modify the behavior +of the original `TraceIdRatioBased` sampler until at least January 1, +2027. At that time, SDK implementors are encouraged to silently +replace TraceIdRatioBased configuration with an equally-configured +`ProbabilitySampler`. + +* The `TraceIdRatioBased` MUST ignore the parent `SampledFlag`. To respect the +parent `SampledFlag`, the `TraceIdRatioBased` should be used as a delegate of +the `ParentBased` sampler specified below. +* Description MUST return a string of the form `"TraceIdRatioBased{RATIO}"` + with `RATIO` replaced with the Sampler instance's trace sampling ratio + represented as a decimal number. The precision of the number SHOULD follow + implementation language standards and SHOULD be high enough to identify when + Samplers have different ratios. For example, if a TraceIdRatioBased Sampler + had a sampling ratio of 1 to every 10,000 spans it COULD return + `"TraceIdRatioBased{0.000100}"` as its description. + +##### Requirements for `TraceIdRatioBased` sampler algorithm + +**Status**: [Stable](../document-status.md) + +* The sampling algorithm MUST be deterministic. A trace identified by a given + `TraceId` is sampled or not independent of language, time, etc. To achieve this, + implementations MUST use a deterministic hash of the `TraceId` when computing + the sampling decision. By ensuring this, running the sampler on any child `Span` + will produce the same decision. +* A `TraceIdRatioBased` sampler with a given sampling probability MUST also sample all + traces that any `TraceIdRatioBased` sampler with a lower sampling probability would + sample. This is important when a backend system may want to run with a higher + sampling probability than the frontend system, this way all frontend traces will + still be sampled and extra traces will be sampled on the backend only. + +##### Compatibility warnings for `TraceIdRatioBased` sampler + +**Status**: [Development](../document-status.md) + +**WARNING:** The exact algorithm was never specified. This sampler is not +defined so as to be compatible with any other SDK, therefore is considered unstable. +Only the configuration and creation APIs are stable. +It is recommended to use this sampler algorithm only for root spans +(in combination with [`ParentBased`](#parentbased)) because different language +SDKs or even different versions of the same language SDKs may produce inconsistent +results for the same input. + +When this sampler observes a non-empty parent span context, meaning +when it is used not as a root sampler, the SDK SHOULD emit a warning +such as: + +``` +WARNING: The TraceIdRatioBased sampler is operating as a child sampler; +the behavior is subject to change. Please upgrade this SDK configuration +to use ProbabilitySampler. +``` + +In such a scenario, this sampler can also detect the use of a +`ProbabilitySampler` by inspecting Tracestate for OpenTelemetry +tracestate (`ot=...`) with `th` or `rv` subkeys, in which case the +warning MAY be more direct: + +``` +WARNING: The TraceIdRatioBased sampler is operating as a child sampler +and a parent is using ProbabilitySampler. Please upgrade this SDK configuration +to use ProbabilitySampler. +``` + +#### ProbabilitySampler + **Status**: [Development](../document-status.md) -The `TraceIdRatioBased` sampler implements simple, ratio-based probability sampling using randomness features specified in the [W3C Trace Context Level 2][W3CCONTEXTMAIN] Candidate Recommendation. +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]. -The `TraceIdRatioBased` sampler MUST ignore the parent `SampledFlag`. +The `ProbabilitySampler` sampler MUST ignore the parent `SampledFlag`. For respecting the parent `SampledFlag`, see the `ParentBased` sampler specified below. Note that the "ratio-based" part of this Sampler's name implies that @@ -444,17 +519,22 @@ specification, the Sampler decision is more nuanced: only a portion of the identifier is used, after checking whether the OpenTelemetry TraceState field contains an explicit randomness value. +Note that this is a non-composable form of probaiblity +sampler. `ProbabilitySampler` directly implements the SDKs Sampler +API, whereas [`ComposableProbability`](#composableprobability) is the +composable form for use with [`CompositeSampler`](#compositesampler). + [W3CCONTEXTMAIN]: https://www.w3.org/TR/trace-context-2/ -##### `TraceIdRatioBased` sampler configuration +##### `ProbabilitySampler` sampler configuration -The `TraceIdRatioBased` sampler is typically configured using a 32-bit or 64-bit floating point number to express the sampling ratio. +The `ProbabilitySampler` sampler 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. [CONSISTENTSAMPLING]: ./tracestate-probability-sampling.md -##### `TraceIdRatioBased` sampler algorithm +##### `ProbabilitySampler` sampler 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`. @@ -463,40 +543,24 @@ Given a Sampler configured with a sampling threshold `T` and Context with random [TRACESTATEHANDLING]: ./tracestate-handling.md#sampling-threshold-value-th -##### `TraceIdRatioBased` sampler description +##### Compatibility warnings for `ProbabilitySampler` -The `TraceIdRatioBased` GetDescription MUST return a string of the form `"TraceIdRatioBased{RATIO}"` -with `RATIO` replaced with the Sampler instance's trace sampling ratio -represented as a decimal number. The precision of the number SHOULD follow -implementation language standards and SHOULD be high enough to identify when -Samplers have different ratios. For example, if a TraceIdRatioBased Sampler -had a sampling ratio of 1 to every 10,000 spans it could return -`"TraceIdRatioBased{0.000100}"` as its description. - -##### `TraceIdRatioBased` sampler compatibility warning - -This specification has been revised from the original -`TraceIdRatioBased` Sampler definition. The present definition for -`TraceIdRatioBased` uses a new definition for trace randomness, where -unless an explicit randomness value is set in the OpenTelemetry -TraceState `rv` sub-key, Samplers are meant to presume that TraceIDs -contain the necessary 56 bits of randomness. - -When a TraceIdRatioBased Sampler makes a decision for a non-root Span +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 TraceIdRatioBased Samplers confirm that +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 TraceIdRatioBased Sampler makes a decision for a non-root Span -using TraceID randomness, but the Trace random flag was not set, the -SDK SHOULD issue a warning statement in its log with a compatibility -warning. As an example of this compatibility warning: +When a ProbabilitySampler Sampler 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 TraceIdRatioBased sampler is presuming TraceIDs are random +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. ``` @@ -604,7 +668,7 @@ randomness values MUST not be modified. * Sets `threshold_reliable` to `false` * Does not add any attributes -###### ComposableTraceIDRatioBased +###### ComposableProbability * Returns a `SamplingIntent` with threshold determined by the configured sampling ratio * Sets `threshold_reliable` to `true` @@ -617,6 +681,9 @@ randomness values MUST not be modified. A ratio value of 0 is considered non-probabilistic. For the zero case a `ComposableAlwaysOff` instance SHOULD be returned instead. +Note that the top-level `ProbabilitySampler` can be implemented using +a `Composite(ComposableProbability(ratio))` configuration. + ###### ComposableParentThreshold * For spans without a parent context, delegate to the root sampler