Skip to content

Move experimental sampling specification into OTEPs #4673

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jmacd merged 12 commits into from
Oct 10, 2025
Merged

Move experimental sampling specification into OTEPs #4673

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
9e01495
Move experimental sampling specification into OTEPs
jmacd Oct 1, 2025
111520d
Apply the PR number
jmacd Oct 1, 2025
1b0b1cf
Annotate, remove front matter
jmacd Oct 1, 2025
5e5b316
PR num
jmacd Oct 1, 2025
c794f31
tracestate-handling.md link
jmacd Oct 1, 2025
caef2cb
note about the one change
jmacd Oct 1, 2025
d9322f5
links fixed
jmacd Oct 1, 2025
25b3835
use permalinks
jmacd Oct 1, 2025
6fdb481
whitespace
jmacd Oct 2, 2025
fbaa4d8
archived
jmacd Oct 9, 2025
6f8c5e5
Merge branch 'main' into jmacd/deprecate_experimental_sampler
jmacd Oct 9, 2025
3d40ec0
Merge branch 'jmacd/deprecate_experimental_sampler' of github.com:jma…
jmacd Oct 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ release.
([#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))
- Remove text related to the former expermental probability sampling specification.
([#4673](https://github.com/open-telemetry/opentelemetry-specification/pull/4673))

### Metrics

Expand Down
120 changes: 28 additions & 92 deletions ...tate-probability-sampling-experimental.md → ...4673-experimental-probability-sampling.md
View file
Open in desktop
Copy link
Copy Markdown
Contributor

@chalin chalin Oct 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jmacd et all: thanks for the cleanup. Note that if you remove a page from the spec, you need to add a redirect rule, otherwise website users will get a 404, as shows up from the link-check failure in https://github.com/open-telemetry/opentelemetry.io/actions/runs/18428326656/job/52512470938?pr=7872.

Copy link
Copy Markdown
Contributor

@chalin chalin Oct 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Issue to track this:

Original file line number Diff line number Diff line change
@@ -1,91 +1,27 @@
<!--- Hugo front matter used to generate the website version of this page:
linkTitle: Probability Sampling
--->

# TraceState: Probability Sampling

**Status**: [Development](../document-status.md)

<details>
<summary>Table of Contents</summary>

<!-- toc -->

- [Overview](#overview)
* [Definitions](#definitions)
+ [Sampling](#sampling)
+ [Adjusted count](#adjusted-count)
+ [Sampler](#sampler)
+ [Parent-based sampler](#parent-based-sampler)
+ [Probability sampler](#probability-sampler)
+ [Consistent probability sampler](#consistent-probability-sampler)
+ [Trace completeness](#trace-completeness)
+ [Non-probability sampler](#non-probability-sampler)
+ [Always-on consistent probability sampler](#always-on-consistent-probability-sampler)
+ [Always-off sampler](#always-off-sampler)
- [Consistent Probability sampling](#consistent-probability-sampling)
* [Conformance](#conformance)
* [Completeness guarantee](#completeness-guarantee)
* [Context invariants](#context-invariants)
+ [Sampled flag](#sampled-flag)
- [Requirement: Inconsistent p-values are unset](#requirement-inconsistent-p-values-are-unset)
+ [P-value](#p-value)
- [Requirement: Out-of-range p-values are unset](#requirement-out-of-range-p-values-are-unset)
+ [R-value](#r-value)
- [Requirement: Out-of-range r-values unset both p and r](#requirement-out-of-range-r-values-unset-both-p-and-r)
- [Requirement: R-value is generated with the correct probabilities](#requirement-r-value-is-generated-with-the-correct-probabilities)
+ [Examples: Context invariants](#examples-context-invariants)
- [Example: Probability sampled context](#example-probability-sampled-context)
- [Example: Probability unsampled](#example-probability-unsampled)
* [Samplers](#samplers)
+ [ParentConsistentProbabilityBased sampler](#parentconsistentprobabilitybased-sampler)
- [Requirement: ParentConsistentProbabilityBased API](#requirement-parentconsistentprobabilitybased-api)
- [Requirement: ParentConsistentProbabilityBased does not modify valid tracestate](#requirement-parentconsistentprobabilitybased-does-not-modify-valid-tracestate)
- [Requirement: ParentConsistentProbabilityBased calls the configured root sampler for root spans](#requirement-parentconsistentprobabilitybased-calls-the-configured-root-sampler-for-root-spans)
- [Requirement: ParentConsistentProbabilityBased respects the sampled flag for non-root spans](#requirement-parentconsistentprobabilitybased-respects-the-sampled-flag-for-non-root-spans)
+ [ConsistentProbabilityBased sampler](#consistentprobabilitybased-sampler)
- [Requirement: TraceIdRatioBased API compatibility](#requirement-traceidratiobased-api-compatibility)
- [Requirement: ConsistentProbabilityBased sampler sets r for root span](#requirement-consistentprobabilitybased-sampler-sets-r-for-root-span)
- [Requirement: ConsistentProbabilityBased sampler unsets p when not sampled](#requirement-consistentprobabilitybased-sampler-unsets-p-when-not-sampled)
- [Requirement: ConsistentProbabilityBased sampler sets p when sampled](#requirement-consistentprobabilitybased-sampler-sets-p-when-sampled)
- [Requirement: ConsistentProbabilityBased sampler records unbiased adjusted counts](#requirement-consistentprobabilitybased-sampler-records-unbiased-adjusted-counts)
- [Requirement: ConsistentProbabilityBased sampler sets r for non-root span](#requirement-consistentprobabilitybased-sampler-sets-r-for-non-root-span)
- [Requirement: ConsistentProbabilityBased sampler decides not to sample for probabilities less than 2**-62](#requirement-consistentprobabilitybased-sampler-decides-not-to-sample-for-probabilities-less-than-2-62)
+ [Examples: Consistent probability samplers](#examples-consistent-probability-samplers)
- [Example: Setting R-value for a root span](#example-setting-r-value-for-a-root-span)
- [Example: Handling inconsistent P-value](#example-handling-inconsistent-p-value)
- [Example: Handling corrupt R-value](#example-handling-corrupt-r-value)
* [Composition rules](#composition-rules)
+ [List of requirements](#list-of-requirements)
- [Requirement: Combining multiple sampling decisions using logical `or`](#requirement-combining-multiple-sampling-decisions-using-logical-or)
- [Requirement: Combine multiple consistent probability samplers using the minimum p-value](#requirement-combine-multiple-consistent-probability-samplers-using-the-minimum-p-value)
- [Requirement: Unset p when multiple consistent probability samplers decide not to sample](#requirement-unset-p-when-multiple-consistent-probability-samplers-decide-not-to-sample)
- [Requirement: Use probability sampler p-value when its decision to sample is combined with non-probability samplers](#requirement-use-probability-sampler-p-value-when-its-decision-to-sample-is-combined-with-non-probability-samplers)
- [Requirement: Use p-value 63 when a probability sampler decision not to sample is combined with a non-probability sampler decision to sample](#requirement-use-p-value-63-when-a-probability-sampler-decision-not-to-sample-is-combined-with-a-non-probability-sampler-decision-to-sample)
+ [Examples: Composition](#examples-composition)
- [Example: Probability and non-probability sampler in a root context](#example-probability-and-non-probability-sampler-in-a-root-context)
- [Example: Two consistent probability samplers](#example-two-consistent-probability-samplers)
* [Producer and consumer recommendations](#producer-and-consumer-recommendations)
+ [Trace producer: completeness](#trace-producer-completeness)
- [Recommendation: use non-descending power-of-two probabilities](#recommendation-use-non-descending-power-of-two-probabilities)
+ [Trace producer: correctness](#trace-producer-correctness)
- [Recommendation: sampler delegation](#recommendation-sampler-delegation)
+ [Trace producer: interoperability with `ParentBased` sampler](#trace-producer-interoperability-with-parentbased-sampler)
+ [Trace producer: interoperability with `TraceIDRatioBased` sampler](#trace-producer-interoperability-with-traceidratiobased-sampler)
+ [Trace consumer](#trace-consumer)
- [Recommendation: Recognize inconsistent r-values](#recommendation-recognize-inconsistent-r-values)
* [Appendix: Statistical test requirements](#appendix-statistical-test-requirements)
+ [Test procedure: non-powers of two](#test-procedure-non-powers-of-two)
- [Requirement: Pass 12 non-power-of-two statistical tests](#requirement-pass-12-non-power-of-two-statistical-tests)
+ [Test procedure: exact powers of two](#test-procedure-exact-powers-of-two)
- [Requirement: Pass 3 power-of-two statistical tests](#requirement-pass-3-power-of-two-statistical-tests)
+ [Test implementation](#test-implementation)
- [Appendix](#appendix)
* [Methods for generating R-values](#methods-for-generating-r-values)

<!-- tocstop -->

</details>
**Status**: Archived

This document contains the final state of the old, experimental
"tracestate probability sampling" specification. This specification is
recorded as an OTEP so that we can remove it from the OpenTelemetry
specification and still refer to it.

Changes to the document made below, summarized:

- Links to [`sdk.md`][SDK_SPEC]: references were general in nature, as the SDK
specification was never updated to refer to this document; these
links were updated to a current permalink to avoid breaking in the
future.
- Links to [`tracestate-handling.md`][TRACESTATE_HANDLING]:
these links were updated to a version of the file that was current
when this file was written, before
[PR#4162](https://github.com/open-telemetry/opentelemetry-specification/pull/4162)
added the new specification.
- Remove the table of contents.

[TRACESTATE_HANDLING]: https://github.com/open-telemetry/opentelemetry-specification/blob/ec3779c3d0044503a1ec
[SDK_SPEC]: https://github.com/open-telemetry/opentelemetry-specification/blob/03e4ea2748e18e63d1e00e58e373ca55768fb1b0/specification/trace/tracestate-handling.md

## Overview

Expand Down Expand Up @@ -256,7 +192,7 @@ values via the context, termed "p-value" and "r-value".

Both fields are propagated via the OpenTelemetry `tracestate` under
the `ot` vendor tag using the rules for [tracestate
handling](tracestate-handling.md). Both fields are represented as
specification][TRACESTATE_HANDLING]. Both fields are represented as
unsigned decimal integers requiring at most 6 bits of information.

This sampling scheme selects items from among a fixed set of 63
Expand Down Expand Up @@ -326,7 +262,7 @@ information: the TraceId, the SpanId, and the trace flags. The
`sampled` trace flag has been defined by W3C to signal an intent to
sample the context.

The [Sampler API](sdk.md#sampler) is responsible for setting the
The [Sampler API][SDK_SPEC#sampler] is responsible for setting the
`sampled` flag and the `tracestate`.

P-value and r-value are set in the OpenTelemetry `tracestate`, under
Expand Down Expand Up @@ -478,7 +414,7 @@ unsampled context.
#### ParentConsistentProbabilityBased sampler

The `ParentConsistentProbabilityBased` sampler is meant as an optional
replacement for the [`ParentBased` Sampler](sdk.md#parentbased). It is
replacement for the [`ParentBased` Sampler][SDK_SPEC#parentbased]. It is
required to first validate the `tracestate` and then respect the
`sampled` flag in the W3C traceparent.

Expand Down Expand Up @@ -508,7 +444,7 @@ traceparent header.

The `ConsistentProbabilityBased` sampler is meant as an optional
replacement for the [`TraceIdRatioBased`
Sampler](sdk.md#traceidratiobased). In the case where it is used as a
Sampler][SDK_SPEC#traceidratiobased]. In the case where it is used as a
root sampler, the `ConsistentProbabilityBased` sampler is required to
produce a valid `tracestate`. In the case where it is used in a
non-root context, it is required to validate the incoming `tracestate`
Expand Down Expand Up @@ -764,7 +700,7 @@ the parent's sampled trace flag or the OpenTelemetry tracestate
r-value and p-value, as these decisions would lead to incorrect
adjusted counts.

For example, the built-in [`ParentBased` sampler](sdk.md#parentbased)
For example, the built-in [`ParentBased` sampler][SDK_SPEC#parentbased]
supports configuring the delegated-to sampler based on whether the parent
context is remote or non-remote, sampled or unsampled. If a
`ParentBased` sampler delegates to a `ConsistentProbabilityBased`
Expand Down Expand Up @@ -794,7 +730,7 @@ replacing `TraceIDRatioBased` samplers with conforming

#### Trace producer: interoperability with `TraceIDRatioBased` sampler

The [`TraceIDRatioBased` specification](sdk.md#traceidratiobased)
The [`TraceIDRatioBased` specification][SDK_SPEC#traceidratiobased]
includes a RECOMMENDATION against being used for non-root spans
because it does not specify how to make the sampler decision
consistent across the trace. A `TraceIDRatioBased` sampler at the
Expand Down
Loading