sdk/trace/x: Add experimental TraceIDRatioBased sampler by yuanyuanzhao3 · Pull Request #8123 · open-telemetry/opentelemetry-go

yuanyuanzhao3 · 2026-04-01T21:45:21Z

Description

Adds an experimental XTraceIDRatioBased sampler in go.opentelemetry.io/otel/sdk/trace/x that conforms to the OpenTelemetry specification's threshold-based sampling algorithm.

Features

Threshold-based sampling: Uses the least significant 56 bits of the trace ID (per W3C Trace Context Level 2 Random Trace ID Flag) for deterministic sampling decisions
Tracestate th handling: Encodes and propagates the sampling threshold in the W3C ot tracestate vendor key for consistent downstream sampling
Random bit support: Integrates with TraceFlags.IsRandom() and WithRandom() (trace: add Random Trace ID Flag #8012) for proper indication of th value for extrapolated metrics support

Files

sdk/trace/x/sampler.go — Core sampler implementation (XTraceIDRatioBased)
sdk/trace/x/sampler_test.go — Tests for sampler behavior
sdk/trace/x/tracestate.go — Tracestate th/rv key helpers
sdk/trace/x/tracestate_test.go — Tests for tracestate helpers
sdk/trace/x/README.md — Documentation for the experimental feature

Co-Author

Joshua MacDonald [email protected]

Add a threshold-based TraceIDRatioBased sampler that conforms to the OpenTelemetry specification. It uses the least significant 56 bits of the trace ID for deterministic sampling decisions and propagates the sampling threshold via the `th` sub-key in the W3C `ot` tracestate vendor key. When an explicit `rv` (randomness value) is present in the tracestate, it is used instead of the trace ID.

codecov · 2026-04-01T21:56:21Z

Codecov Report

❌ Patch coverage is 97.14286% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.2%. Comparing base (97a086e) to head (6c0d82c).
⚠️ Report is 23 commits behind head on main.

Files with missing lines	Patch %	Lines
sdk/trace/x/sampler.go	94.4%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##            main   #8123     +/-   ##
=======================================
+ Coverage   81.8%   82.2%   +0.4%     
=======================================
  Files        308     311      +3     
  Lines      23709   24316    +607     
=======================================
+ Hits       19396   20007    +611     
+ Misses      3935    3929      -6     
- Partials     378     380      +2

Files with missing lines	Coverage Δ
sdk/trace/x/tracestate.go	`100.0% <100.0%> (ø)`
sdk/trace/x/sampler.go	`94.4% <94.4%> (ø)`

... and 28 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

dashpole

I'm a bit confused by this still. I see we already have a TraceIDRatioBased sampler in the SDK. I also see that the sampler is marked deprecated in the spec: https://opentelemetry.io/docs/specs/otel/trace/sdk/#traceidratiobased, so i'm not sure why we would be adding new features to it. The changes here seem to align with the ProbabilitySampler specification, not the TraceIDRatioBased sampler specification, so i'm not sure why this is named TraceIDRatioBased, and links to that specification.

@jmacd maybe you can clarify? Is the intent that SDKs introduce a ProbabilitySampler artifact along-side the TraceIDRatioBased sampler? Or is the intent that we only keep TraceIDRatioBased, but update it to follow the ProbabilitySampler spec (is that breaking)?

dashpole · 2026-04-06T15:36:42Z

sdk/trace/x/sampler.go

+
+const (
+	// DefaultSamplingPrecision is the default precision for threshold encoding.
+	DefaultSamplingPrecision = 4


Does this need to be exported? Is it useful for users in some way?

dashpole · 2026-04-07T15:52:11Z

sdk/trace/x/sampler.go

+// delegate of a ParentBased sampler.
+//
+//nolint:revive // XTraceIDRatioBased matches the OpenTelemetry sampler naming convention.
+func XTraceIDRatioBased(fraction float64) sdktrace.Sampler {


No need to prefix this with X, since it is already in an experimental package.

Mainly wanted to make it explicit that this is intended to become part of the TraceIDRatioBased but is now different (I'm aware it is under a different package). I can rename if that's what we want.

dashpole · 2026-04-07T16:05:48Z

sdk/trace/x/sampler.go

+	return &xTraceIDRatioSampler{
+		threshold:   threshold,
+		thkv:        "th:" + tvalue,
+		description: fmt.Sprintf("XTraceIDRatioBased{%g}", fraction),


This is required to be TraceIdRatioBased{%g} by the specification.

yuanyuanzhao3 · 2026-04-08T15:03:06Z

I'm a bit confused by this still. I see we already have a TraceIDRatioBased sampler in the SDK. I also see that the sampler is marked deprecated in the spec: https://opentelemetry.io/docs/specs/otel/trace/sdk/#traceidratiobased, so i'm not sure why we would be adding new features to it. The changes here seem to align with the ProbabilitySampler specification, not the TraceIDRatioBased sampler specification, so i'm not sure why this is named TraceIDRatioBased, and links to that specification.

@jmacd maybe you can clarify? Is the intent that SDKs introduce a ProbabilitySampler artifact along-side the TraceIDRatioBased sampler? Or is the intent that we only keep TraceIDRatioBased, but update it to follow the ProbabilitySampler spec (is that breaking)?

Not @jmacd, but here's my understanding:

This is intended to be a new API-level compatible replacement for the original TraceIDRatioBased sampler. The difference lies in the underlying sampling algorithm and the information it passes through tracestate, which allows proper extrapolation of span metrics. I don't believe the previous tracestate information was ever used by any of our supported connectors (but others might know a place or two that I'm not aware of).

The new spec: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/tracestate-probability-sampling.md is what this PR is about and it is a kind of probability sampling.

I do not know why the place https://opentelemetry.io/docs/specs/otel/trace/sdk/#traceidratiobased is marking TraceIdRatioBased as deprecated.

dashpole · 2026-04-08T15:22:19Z

sdk/trace/x/sampler.go

+		hbits = 4
+	)
+	if fraction > probabilityOneThreshold {
+		return sdktrace.AlwaysSample()


This doesn't propagate th properly, right? It also doesn't return the correct description.

Same comment for NeverSample below.

I compared with https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/208b7c0565fe51033fa8d8b3d96a3c3dcba79a3f/pkg/sampling/probability.go#L33, which is an ancestor of this. It returns an error in these cases.

I realize this may have happened because in an earlier implementation of this, I had assumed that AlwaysSample() would return a sampler that sets ot=th:0. @yuanyuanzhao3 sadly note that https://opentelemetry.io/docs/specs/otel/trace/sdk/#alwayson does not dictate to set th:0, and I'm not sure myself whether this counts as oversight or just the path of least resistance. It suggests we should have ProbabilitySampler with fraction=1 fix this, later we can discuss modifying the OTel SDK (which is I think what we want).

dashpole · 2026-04-08T15:23:06Z

The new spec: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/tracestate-probability-sampling.md is what this PR is about and it is a kind of probability sampling.

I do not know why the place https://opentelemetry.io/docs/specs/otel/trace/sdk/#traceidratiobased is marking TraceIdRatioBased as deprecated.

The sdk/trace package (and experimental features in sdk/trace/x) needs to follow the specification in https://opentelemetry.io/docs/specs/otel/trace/sdk. The only place that tracestate-probability-sampling.md is referenced from in the SDK spec is from https://opentelemetry.io/docs/specs/otel/trace/sdk/#probabilitysampler. So if you are implementing https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/tracestate-probability-sampling.md, I assume it should follow the ProbabilitySampler specification in the SDK.

If my understanding is correct, please make sure it follows the ProbabilitySampler specification.

Other than naming this ProbabilitySampler, i don't see the compatibility warning described here: https://opentelemetry.io/docs/specs/otel/trace/sdk/#compatibility-warnings-for-probabilitysampler

jmacd · 2026-04-10T15:53:06Z

I can probably explain some confusion -- there was a late-entering change in the sampling specification as it moved from OTEP 235 to the SDK specification, where we decided on the name ProbabilitySampler and that TraceIDRatioBased would have a deprecation period.

@yuanyuanzhao3 see open-telemetry/opentelemetry-specification#4627 for details. Sorry for the confusion! Thank you @dashpole for your guidance.

yuanyuanzhao3 requested review from MrAlias, XSAM, dashpole, dmathieu, flc1125 and pellared as code owners April 1, 2026 21:45

sdk/trace/x: adding changelog entry for new XTraceIdRatioBased sampler.

40b38a2

yuanyuanzhao3 mentioned this pull request Apr 2, 2026

[samplers/probability] Implements a traceIdRatio sampler open-telemetry/opentelemetry-go-contrib#8714

Closed

dashpole reviewed Apr 7, 2026

View reviewed changes

dashpole reviewed Apr 8, 2026

View reviewed changes

[sdk/trace/x] Renames TraceIDRatioBased sampler and constructs.

6c0d82c

yuanyuanzhao3 changed the title ~~sdk/trace/x: Add experimental XTraceIDRatioBased sampler~~ sdk/trace/x: Add experimental TraceIDRatioBased sampler Apr 9, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

sdk/trace/x: Add experimental TraceIDRatioBased sampler#8123

sdk/trace/x: Add experimental TraceIDRatioBased sampler#8123
yuanyuanzhao3 wants to merge 3 commits intoopen-telemetry:mainfrom
yuanyuanzhao3:traceidratio-sampler-x

yuanyuanzhao3 commented Apr 1, 2026

Uh oh!

codecov bot commented Apr 1, 2026 •

edited

Loading

Uh oh!

dashpole left a comment

Uh oh!

dashpole Apr 6, 2026

Uh oh!

dashpole Apr 7, 2026

Uh oh!

yuanyuanzhao3 Apr 8, 2026

Uh oh!

dashpole Apr 7, 2026

Uh oh!

yuanyuanzhao3 commented Apr 8, 2026

Uh oh!

dashpole Apr 8, 2026

Uh oh!

jmacd Apr 10, 2026 •

edited

Loading

Uh oh!

dashpole commented Apr 8, 2026

Uh oh!

jmacd commented Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

yuanyuanzhao3 commented Apr 1, 2026

Description

Features

Files

Related

Co-Author

Uh oh!

codecov bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

dashpole left a comment

Choose a reason for hiding this comment

Uh oh!

dashpole Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

dashpole Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

yuanyuanzhao3 Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

dashpole Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

yuanyuanzhao3 commented Apr 8, 2026

Uh oh!

dashpole Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

jmacd Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dashpole commented Apr 8, 2026

Uh oh!

jmacd commented Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov bot commented Apr 1, 2026 •

edited

Loading

jmacd Apr 10, 2026 •

edited

Loading