[samplers/probability] Implements a traceIdRatio sampler by yuanyuanzhao3 · Pull Request #8714 · open-telemetry/opentelemetry-go-contrib

yuanyuanzhao3 · 2026-03-20T21:29:14Z

Description

Implements a TraceIdRatioBased sampler in go.opentelemetry.io/contrib/samplers/probability/traceidratio 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() (opentelemetry-go#8012) for proper indication of th value for extrapolated metrics support

Dependencies

This module temporarily uses replace directives to pin to the opentelemetry-go commit that includes IsRandom/WithRandom (opentelemetry-go#8012, merge commit 2ffde5a42). These replaces should be removed once opentelemetry-go releases a version that includes those APIs.

Co-Author

Joshua MacDonald jmacd@users.noreply.github.com

…s to the threshold based sampling algorithm. Made-with: Cursor

…dRatio based sampler.

codecov · 2026-03-20T21:52:27Z

Codecov Report

❌ Patch coverage is 95.41284% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.2%. Comparing base (b24435f) to head (3cd6a7b).
⚠️ Report is 26 commits behind head on main.

Files with missing lines	Patch %	Lines
samplers/probability/traceidratio/sampler.go	94.6%	2 Missing and 1 partial ⚠️
samplers/probability/traceidratio/version.go	0.0%	2 Missing ⚠️

Additional details and impacted files

@@          Coverage Diff           @@
##            main   #8714    +/-   ##
======================================
  Coverage   82.2%   82.2%            
======================================
  Files        183     186     +3     
  Lines      13812   13921   +109     
======================================
+ Hits       11354   11449    +95     
- Misses      2054    2068    +14     
  Partials     404     404

Files with missing lines	Coverage Δ
samplers/probability/traceidratio/tracestate.go	`100.0% <100.0%> (ø)`
samplers/probability/traceidratio/version.go	`0.0% <0.0%> (ø)`
samplers/probability/traceidratio/sampler.go	`94.6% <94.6%> (ø)`

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

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

…ndomness (explicit or from traceid with random tracestate flag) exists.

…h` key resulting in an empty otts. This happens when `th` was the only subkey in `ot` in the incoming tracestate. However, the incoming traceid or tracestate lacks randomness, so we end up erasing `th`.

…ses and fixing lints.

yuanyuanzhao3 · 2026-03-23T18:06:11Z

@jmacd as FYI.

jmacd

Nice! Thank you.

General comments:

I think this belongs in the core SDK (eventually), as a core part of the OTel tracing specification
With this PR it is definitely time to remove the older probability sampler.
#6176

jmacd · 2026-03-26T15:35:40Z

+	if fraction < probabilityZeroThreshold {
+		return sdktrace.NeverSample()
+	}
+


For the record, this code is identical to https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/1a616d98873ca26622ef6d4698c2e7d1ddd7a25f/pkg/sampling/probability.go#L33, a variation on https://opentelemetry.io/docs/specs/otel/trace/tracestate-probability-sampling/#converting-floating-point-probability-to-threshold-value.

yuanyuanzhao3 · 2026-03-27T15:04:35Z

Nice! Thank you.

General comments:

I think this belongs in the core SDK (eventually), as a core part of the OTel tracing specification

With this PR it is definitely time to remove the older probability sampler.
Deprecate and remove go.opentelemetry.io/contrib/samplers/probability/consistent #6176

I think so as well. I'm under the impression that this is a temporary home while the sampler is being developed and battle-hardened. Eventually it'll graduate to the core SDK.

@dashpole who suggested this place:

It looks like the TraceIDRatioBased sampler is still development stability, right? In that case we will need to add the sampler in a v0.* module. It might need to live in contrib, similar to the minsev logging processor: https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/processors/minsev.

Co-authored-by: Joshua MacDonald <jmacd@users.noreply.github.com>

…ailures in codespell and markdown lint checks Made-with: Cursor

dashpole · 2026-03-30T19:29:22Z

If this is going to be part of the sdk/trace module eventually, then we should probably put it in go.opentelemetry.io/otel/sdk/trace/x (new experimental trace module, following our x package pattern).

I would personally prefer to wait until we have a stable replacement to add deprecation warnings to the probability sampler. The deprecation warning isn't very actionable without a stable replacement.

yuanyuanzhao3 · 2026-03-31T13:36:55Z

If this is going to be part of the sdk/trace module eventually, then we should probably put it in go.opentelemetry.io/otel/sdk/trace/x (new experimental trace module, following our x package pattern).

Are you suggesting to do this now or wait? Not sure what the "prefer to wait" comment is about.

I would personally prefer to wait until we have a stable replacement to add deprecation warnings to the probability sampler. The deprecation warning isn't very actionable without a stable replacement.

dashpole · 2026-03-31T14:10:21Z

Are you suggesting to do this now or wait? Not sure what the "prefer to wait" comment is about.

I want to wait to add deprecation warnings to the old probability sampler. You can move this back to core in the new experimental module now.

Edit: I meant wait on the probability sampler deprecation. Not wait on the traceidratio sampler.

yuanyuanzhao3 · 2026-03-31T15:23:00Z

Are you suggesting to do this now or wait? Not sure what the "prefer to wait" comment is about.

I want to wait to add deprecation warnings to the old probability sampler. You can move this back to core in the new experimental module now.

Edit: I meant wait on the probability sampler deprecation. Not wait on the traceidratio sampler.

I can't find the new sdk/trace/x package. Is this under https://github.com/open-telemetry/opentelemetry-go/tree/main/sdk/trace?

dashpole · 2026-03-31T15:25:00Z

We need to add a new module.

yuanyuanzhao3 · 2026-03-31T15:51:40Z

We need to add a new module.

ok. any established patterns for the structure under sdk/<...>/x? Can't find examples in the vicinity.

dmathieu · 2026-04-01T07:31:01Z

See https://github.com/open-telemetry/opentelemetry-go/tree/main/sdk/log/internal/x

yuanyuanzhao3 · 2026-04-02T14:29:17Z

FYI, I created the PR in the core SDK depot under sdk/trace/x: open-telemetry/opentelemetry-go#8123

jmacd · 2026-04-10T15:49:03Z

Thanks @yuanyuanzhao3 and @dashpole. The convention sdk/trace/x makes sense.

[samplers/probability] Implements a traceIdRatio sampler that conform…

6482e20

…s to the threshold based sampling algorithm. Made-with: Cursor

yuanyuanzhao3 requested a review from a team as a code owner March 20, 2026 21:29

[samplers/probability] Adds PR number for change log entry for traceI…

efc52f5

…dRatio based sampler.

yuanyuanzhao3 added 4 commits March 23, 2026 10:54

[samplers/probability] TraceIdRatioBased: addresses lints.

6471758

[samplers/probability] TraceIdRatioBased: adding testcase where no ra…

f363410

…ndomness (explicit or from traceid with random tracestate flag) exists.

[sampler/probability] TraceIdRatioBased: adding test where erasing `t…

f4b6053

…h` key resulting in an empty otts. This happens when `th` was the only subkey in `ot` in the incoming tracestate. However, the incoming traceid or tracestate lacks randomness, so we end up erasing `th`.

[sampler/probability] traceidratio sampler: adding a few more test ca…

7be9550

…ses and fixing lints.

jmacd approved these changes Mar 26, 2026

View reviewed changes

yuanyuanzhao3 and others added 3 commits March 27, 2026 11:55

Update samplers/probability/traceidratio/sampler.go

25c7e5a

Co-authored-by: Joshua MacDonald <jmacd@users.noreply.github.com>

Merge branch 'main' into traceidratio-sampler

d962991

[samplers/probability] Re-trigger CI: resolve transient Docker pull f…

3cd6a7b

…ailures in codespell and markdown lint checks Made-with: Cursor

dashpole closed this Apr 2, 2026

Conversation

yuanyuanzhao3 commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Features

Dependencies

Related

Co-Author

Uh oh!

codecov Bot commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

yuanyuanzhao3 commented Mar 23, 2026

Uh oh!

jmacd left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jmacd Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

yuanyuanzhao3 commented Mar 27, 2026

Uh oh!

dashpole commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yuanyuanzhao3 commented Mar 31, 2026 • edited by dashpole Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dashpole commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yuanyuanzhao3 commented Mar 31, 2026

Uh oh!

dashpole commented Mar 31, 2026

Uh oh!

yuanyuanzhao3 commented Mar 31, 2026

Uh oh!

dmathieu commented Apr 1, 2026

Uh oh!

yuanyuanzhao3 commented Apr 2, 2026

Uh oh!

jmacd commented Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

yuanyuanzhao3 commented Mar 20, 2026 •

edited

Loading

codecov Bot commented Mar 20, 2026 •

edited

Loading

dashpole commented Mar 30, 2026 •

edited

Loading

yuanyuanzhao3 commented Mar 31, 2026 •

edited by dashpole

Loading

dashpole commented Mar 31, 2026 •

edited

Loading