[samplers/probability] Implements a traceIdRatio sampler

CHANGELOG.md

@@ -10,6 +10,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Added
 
+- Add trace ID ratio sampler in `go.opentelemetry.io/contrib/samplers/probability/traceidratio` that conforms to the threshold-based sampling algorithm. (#8714)
 - Configuration file can now be set via `OTEL_CONFIG_FILE` in `go.opentelemetry.io/contrib/otelconf`. (#8639)
 - Added support for `service` resource detector in `go.opentelemetry.io/contrib/otelconf`. (#8674)
 - Added support for `attribute_count_limit` and `attribute_value_length_limit` in tracer provider configuration in `go.opentelemetry.io/contrib/otelconf`. (#8687)

samplers/probability/traceidratio/go.mod

@@ -0,0 +1,33 @@
+module go.opentelemetry.io/contrib/samplers/probability/traceidratio
+
+go 1.25.0
+
+// Replace directives for opentelemetry-go commit with IsRandom/WithRandom (PR #8012).
+// Remove when using a released version of opentelemetry-go that includes these APIs.
+replace (
+	go.opentelemetry.io/otel => go.opentelemetry.io/otel v0.0.0-20260313082256-2ffde5a4289b
+	go.opentelemetry.io/otel/metric => go.opentelemetry.io/otel/metric v0.0.0-20260313082256-2ffde5a4289b
+	go.opentelemetry.io/otel/sdk => go.opentelemetry.io/otel/sdk v0.0.0-20260313082256-2ffde5a4289b
+	go.opentelemetry.io/otel/sdk/metric => go.opentelemetry.io/otel/sdk/metric v0.0.0-20260313082256-2ffde5a4289b
+	go.opentelemetry.io/otel/trace => go.opentelemetry.io/otel/trace v0.0.0-20260313082256-2ffde5a4289b
+)
+
+require (
+	github.com/stretchr/testify v1.11.1
+	go.opentelemetry.io/otel v1.42.0
+	go.opentelemetry.io/otel/sdk v1.42.0
+	go.opentelemetry.io/otel/trace v1.42.0
+)
+
+require (
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel/metric v1.42.0 // indirect
+	golang.org/x/sys v0.42.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

samplers/probability/traceidratio/go.sum

@@ -0,0 +1,44 @@
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v0.0.0-20260313082256-2ffde5a4289b h1:9V5tad0Zrnu5A38XtA38tS2i7iIh0QncGaAPDfbeecg=
+go.opentelemetry.io/otel v0.0.0-20260313082256-2ffde5a4289b/go.mod h1:lJNsdRMxCUIWuMlVJWzecSMuNjE7dOYyWlqOXWkdqCc=
+go.opentelemetry.io/otel/metric v0.0.0-20260313082256-2ffde5a4289b h1:BXYSujuqUpkvYLAuniNgbPfbXXuN4qbdqcfKZ6yjsL4=
+go.opentelemetry.io/otel/metric v0.0.0-20260313082256-2ffde5a4289b/go.mod h1:RlUN/7vTU7Ao/diDkEpQpnz3/92J9ko05BIwxYa2SSI=
+go.opentelemetry.io/otel/sdk v0.0.0-20260313082256-2ffde5a4289b h1:CyLUNdZpcIlnTLtnE3gHCIlG76C9L6CVMz6r7NUe9NM=
+go.opentelemetry.io/otel/sdk v0.0.0-20260313082256-2ffde5a4289b/go.mod h1:xaSffVzFG55EcPDReZb7hNa30cBwL0AMXQgPeGkMPtk=
+go.opentelemetry.io/otel/sdk/metric v0.0.0-20260313082256-2ffde5a4289b h1:LwXN9llvuRNj2WiKhrZsYfMjPm68lMrdIYOmdliJ38g=
+go.opentelemetry.io/otel/sdk/metric v0.0.0-20260313082256-2ffde5a4289b/go.mod h1:2i8yfZkjLqri5gxkYhyCXv6sOIC/2x0Cne9MXpUMLUE=
+go.opentelemetry.io/otel/trace v0.0.0-20260313082256-2ffde5a4289b h1:ABOfwjz5qmdgSN+L6qpdui5JLYvxBm1FmUNz1XkwyY8=
+go.opentelemetry.io/otel/trace v0.0.0-20260313082256-2ffde5a4289b/go.mod h1:f3K9S+IFqnumBkKhRJMeaZeNk9epyhnCmQh/EysQCdc=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
+golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
+golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

samplers/probability/traceidratio/sampler.go

@@ -0,0 +1,140 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// Package traceidratio provides a trace ID ratio-based sampler per the
+// OpenTelemetry specification.
+package traceidratio // import "go.opentelemetry.io/contrib/samplers/probability/traceidratio"
+
+import (
+	"encoding/binary"
+	"fmt"
+	"math"
+	"strconv"
+	"strings"
+
+	"go.opentelemetry.io/otel"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	"go.opentelemetry.io/otel/trace"
+)
+
+const (
+	// DefaultSamplingPrecision is the default precision for threshold encoding.
+	DefaultSamplingPrecision = 4
+	maxAdjustedCount         = 1 << 56
+	// randomnessMask masks the least significant 56 bits of the trace ID per
+	// W3C Trace Context Level 2 Random Trace ID Flag.
+	// https://www.w3.org/TR/trace-context-2/#random-trace-id-flag
+	randomnessMask = maxAdjustedCount - 1
+
+	probabilityZeroThreshold = 1 / float64(maxAdjustedCount)
+	probabilityOneThreshold  = 1 - 0x1p-52
+)
+
+// Sampler is a sampler that samples a fraction of traces based on
+// the trace ID. It is exported for testing (e.g., to assert threshold values).
+type Sampler struct {
+	threshold   uint64
+	thkv        string
+	description string
+}
+
+// Threshold returns the rejection threshold for testing.
+func (ts *Sampler) Threshold() uint64 {
+	return ts.threshold
+}
+
+// ShouldSample implements sdktrace.Sampler.
+func (ts *Sampler) ShouldSample(p sdktrace.SamplingParameters) sdktrace.SamplingResult {
+	psc := trace.SpanContextFromContext(p.ParentContext)
+	state := psc.TraceState()
+
+	existingOtts := state.Get("ot")
+
+	var randomness uint64
+	var hasRandomness bool
+	if existingOtts != "" {
+		randomness, hasRandomness = tracestateRandomness(existingOtts)
+	}
+
+	if !hasRandomness {
+		randomness = binary.BigEndian.Uint64(p.TraceID[8:16]) & randomnessMask
+	}
+
+	if ts.threshold > randomness {
+		return sdktrace.SamplingResult{
+			Decision:   sdktrace.Drop,
+			Tracestate: state,
+		}
+	}
+
+	var newOtts string
+	// Only when the randomness we extracted (either from explicit rv value or from trace ID) is present,
+	// can we insert or update the th key-value. Otherwise, we should erase any existing `th` key-value
+	// to signal that the span is not guaranteed to be statistically representative of the trace.
+	// This logic is specified in
+	// https://opentelemetry.io/docs/specs/otel/trace/tracestate-probability-sampling/#general-requirements
+	if hasRandomness || psc.TraceFlags().IsRandom() {
+		newOtts = InsertOrUpdateTraceStateThKeyValue(existingOtts, ts.thkv)
+	} else {
+		newOtts = eraseTraceStateThKeyValue(existingOtts)
+	}
+
+	if newOtts == "" {
+		state = state.Delete("ot")
+		return sdktrace.SamplingResult{Decision: sdktrace.RecordAndSample, Tracestate: state}
+	}
+	combined, err := state.Insert("ot", newOtts)
+	if err != nil {
+		// This in practice should never happen because `ot` is a valid key and any new value we
+		// create for it is an update to `th` and should always be valid.
+		otel.Handle(fmt.Errorf("could not combine tracestate: %w", err))
+		return sdktrace.SamplingResult{Decision: sdktrace.Drop, Tracestate: state}
+	}
+	return sdktrace.SamplingResult{Decision: sdktrace.RecordAndSample, Tracestate: combined}
+}
+
+// Description implements sdktrace.Sampler.
+func (ts *Sampler) Description() string {
+	return ts.description
+}
+
+// TraceIDRatioBased samples a given fraction of traces. Fractions >= 1 will
+// always sample. Fractions < 0 are treated as zero. To respect the parent
+// trace's SampledFlag, the TraceIDRatioBased sampler should be used as a
+// delegate of a Parent sampler.
+//
+//nolint:revive // TraceIDRatioBased is the standard OpenTelemetry sampler name
+func TraceIDRatioBased(fraction float64) sdktrace.Sampler {
+	const (
+		maxp  = 14
+		defp  = DefaultSamplingPrecision
+		hbits = 4
+	)
+	if fraction > probabilityOneThreshold {
+		return sdktrace.AlwaysSample()
+	}
+	if fraction < probabilityZeroThreshold {
+		return sdktrace.NeverSample()
+	}
+
+	_, expF := math.Frexp(fraction)
+	_, expR := math.Frexp(1 - fraction)
+	precision := min(maxp, max(defp+expF/-hbits, defp+expR/-hbits))
+
+	scaled := uint64(math.Round(fraction * float64(maxAdjustedCount)))
+	threshold := maxAdjustedCount - scaled
+
+	if shift := hbits * (maxp - precision); shift != 0 {
+		half := uint64(1) << (shift - 1)
+		threshold += half
+		threshold >>= shift
+		threshold <<= shift
+	}
+
+	tvalue := strings.TrimRight(strconv.FormatUint(maxAdjustedCount+threshold, 16)[1:], "0")
+	return &Sampler{
+		threshold:   threshold,
+		thkv:        "th:" + tvalue,
+		description: fmt.Sprintf("TraceIDRatioBased{%g}", fraction),
+	}
+}