Debian Codegraph @

sdk/trace/sampling.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 package trace // import "go.opentelemetry.io/otel/sdk/trace"
5
6 import (
7 "context"
8 "encoding/binary"
9 "fmt"
10
11 "go.opentelemetry.io/otel/attribute"
12 "go.opentelemetry.io/otel/trace"
13 )
14
15 // Sampler decides whether a trace should be sampled and exported.
16 type Sampler interface {
17 // DO NOT CHANGE: any modification will not be backwards compatible and
18 // must never be done outside of a new major release.
19
20 // ShouldSample returns a SamplingResult based on a decision made from the
21 // passed parameters.
22 ShouldSample(parameters SamplingParameters) SamplingResult
23 // DO NOT CHANGE: any modification will not be backwards compatible and
24 // must never be done outside of a new major release.
25
26 // Description returns information describing the Sampler.
27 Description() string
28 // DO NOT CHANGE: any modification will not be backwards compatible and
29 // must never be done outside of a new major release.
30 }
31
32 // SamplingParameters contains the values passed to a Sampler.
33 type SamplingParameters struct {
34 ParentContext context.Context
35 TraceID trace.TraceID
36 Name string
37 Kind trace.SpanKind
38 Attributes []attribute.KeyValue
39 Links []trace.Link
40 }
41
42 // SamplingDecision indicates whether a span is dropped, recorded and/or sampled.
43 type SamplingDecision uint8
44
45 // Valid sampling decisions.
46 const (
47 // Drop will not record the span and all attributes/events will be dropped.
48 Drop SamplingDecision = iota
49
50 // RecordOnly indicates the span's IsRecording method returns true, but trace.FlagsSampled flag
51 // must not be set.
52 RecordOnly
53
54 // RecordAndSample indicates the span's IsRecording method returns true and trace.FlagsSampled flag
55 // must be set.
56 RecordAndSample
57 )
58
59 // SamplingResult conveys a SamplingDecision, set of Attributes and a Tracestate.
60 type SamplingResult struct {
61 Decision SamplingDecision
62 Attributes []attribute.KeyValue
63 Tracestate trace.TraceState
64 }
65
66 type traceIDRatioSampler struct {
67 traceIDUpperBound uint64
68 description string
69 }
70
71 func (ts traceIDRatioSampler) ShouldSample(p SamplingParameters) SamplingResult {
72 state := trace.SpanContextFromContext(p.ParentContext).TraceState()
73 x := binary.BigEndian.Uint64(p.TraceID[8:16]) >> 1
74 if x < ts.traceIDUpperBound {
75 return SamplingResult{
76 Decision: RecordAndSample,
77 Tracestate: state,
78 }
79 }
80 return SamplingResult{
81 Decision: Drop,
82 Tracestate: state,
83 }
84 }
85
86 func (ts traceIDRatioSampler) Description() string {
87 return ts.description
88 }
89
90 // TraceIDRatioBased samples a given fraction of traces. Fractions >= 1 will
91 // always sample. Fractions < 0 are treated as zero. To respect the
92 // parent trace's `SampledFlag`, the `TraceIDRatioBased` sampler should be used
93 // as a delegate of a `Parent` sampler.
94 //
95 //nolint:revive // revive complains about stutter of `trace.TraceIDRatioBased`
96 func TraceIDRatioBased(fraction float64) Sampler {
97 // Cannot use AlwaysSample() and NeverSample(), must return spec-compliant descriptions.
98 // See https://opentelemetry.io/docs/specs/otel/trace/sdk/#traceidratiobased.
99 if fraction >= 1 {
100 return predeterminedSampler{
101 description: "TraceIDRatioBased{1}",
102 decision: RecordAndSample,
103 }
104 }
105
106 if fraction <= 0 {
107 return predeterminedSampler{
108 description: "TraceIDRatioBased{0}",
109 decision: Drop,
110 }
111 }
112
113 return &traceIDRatioSampler{
114 traceIDUpperBound: uint64(fraction * (1 << 63)),
115 description: fmt.Sprintf("TraceIDRatioBased{%g}", fraction),
116 }
117 }
118
119 type alwaysOnSampler struct{}
120
121 func (alwaysOnSampler) ShouldSample(p SamplingParameters) SamplingResult {
122 return SamplingResult{
123 Decision: RecordAndSample,
124 Tracestate: trace.SpanContextFromContext(p.ParentContext).TraceState(),
125 }
126 }
127
128 func (alwaysOnSampler) Description() string {
129 // https://opentelemetry.io/docs/specs/otel/trace/sdk/#alwayson
130 return "AlwaysOnSampler"
131 }
132
133 // AlwaysSample returns a Sampler that samples every trace.
134 // Be careful about using this sampler in a production application with
135 // significant traffic: a new trace will be started and exported for every
136 // request.
137 func AlwaysSample() Sampler {
138 return alwaysOnSampler{}
139 }
140
141 type alwaysOffSampler struct{}
142
143 func (alwaysOffSampler) ShouldSample(p SamplingParameters) SamplingResult {
144 return SamplingResult{
145 Decision: Drop,
146 Tracestate: trace.SpanContextFromContext(p.ParentContext).TraceState(),
147 }
148 }
149
150 func (alwaysOffSampler) Description() string {
151 // https://opentelemetry.io/docs/specs/otel/trace/sdk/#alwaysoff
152 return "AlwaysOffSampler"
153 }
154
155 // NeverSample returns a Sampler that samples no traces.
156 func NeverSample() Sampler {
157 return alwaysOffSampler{}
158 }
159
160 type predeterminedSampler struct {
161 description string
162 decision SamplingDecision
163 }
164
165 func (s predeterminedSampler) ShouldSample(p SamplingParameters) SamplingResult {
166 return SamplingResult{
167 Decision: s.decision,
168 Tracestate: trace.SpanContextFromContext(p.ParentContext).TraceState(),
169 }
170 }
171
172 func (s predeterminedSampler) Description() string {
173 return s.description
174 }
175
176 // ParentBased returns a sampler decorator which behaves differently,
177 // based on the parent of the span. If the span has no parent,
178 // the decorated sampler is used to make sampling decision. If the span has
179 // a parent, depending on whether the parent is remote and whether it
180 // is sampled, one of the following samplers will apply:
181 // - remoteParentSampled(Sampler) (default: AlwaysOn)
182 // - remoteParentNotSampled(Sampler) (default: AlwaysOff)
183 // - localParentSampled(Sampler) (default: AlwaysOn)
184 // - localParentNotSampled(Sampler) (default: AlwaysOff)
185 func ParentBased(root Sampler, samplers ...ParentBasedSamplerOption) Sampler {
186 return parentBased{
187 root: root,
188 config: configureSamplersForParentBased(samplers),
189 }
190 }
191
192 type parentBased struct {
193 root Sampler
194 config samplerConfig
195 }
196
197 func configureSamplersForParentBased(samplers []ParentBasedSamplerOption) samplerConfig {
198 c := samplerConfig{
199 remoteParentSampled: AlwaysSample(),
200 remoteParentNotSampled: NeverSample(),
201 localParentSampled: AlwaysSample(),
202 localParentNotSampled: NeverSample(),
203 }
204
205 for _, so := range samplers {
206 c = so.apply(c)
207 }
208
209 return c
210 }
211
212 // samplerConfig is a group of options for parentBased sampler.
213 type samplerConfig struct {
214 remoteParentSampled, remoteParentNotSampled Sampler
215 localParentSampled, localParentNotSampled Sampler
216 }
217
218 // ParentBasedSamplerOption configures the sampler for a particular sampling case.
219 type ParentBasedSamplerOption interface {
220 apply(samplerConfig) samplerConfig
221 }
222
223 // WithRemoteParentSampled sets the sampler for the case of sampled remote parent.
224 func WithRemoteParentSampled(s Sampler) ParentBasedSamplerOption {
225 return remoteParentSampledOption{s}
226 }
227
228 type remoteParentSampledOption struct {
229 s Sampler
230 }
231
232 func (o remoteParentSampledOption) apply(config samplerConfig) samplerConfig {
233 config.remoteParentSampled = o.s
234 return config
235 }
236
237 // WithRemoteParentNotSampled sets the sampler for the case of remote parent
238 // which is not sampled.
239 func WithRemoteParentNotSampled(s Sampler) ParentBasedSamplerOption {
240 return remoteParentNotSampledOption{s}
241 }
242
243 type remoteParentNotSampledOption struct {
244 s Sampler
245 }
246
247 func (o remoteParentNotSampledOption) apply(config samplerConfig) samplerConfig {
248 config.remoteParentNotSampled = o.s
249 return config
250 }
251
252 // WithLocalParentSampled sets the sampler for the case of sampled local parent.
253 func WithLocalParentSampled(s Sampler) ParentBasedSamplerOption {
254 return localParentSampledOption{s}
255 }
256
257 type localParentSampledOption struct {
258 s Sampler
259 }
260
261 func (o localParentSampledOption) apply(config samplerConfig) samplerConfig {
262 config.localParentSampled = o.s
263 return config
264 }
265
266 // WithLocalParentNotSampled sets the sampler for the case of local parent
267 // which is not sampled.
268 func WithLocalParentNotSampled(s Sampler) ParentBasedSamplerOption {
269 return localParentNotSampledOption{s}
270 }
271
272 type localParentNotSampledOption struct {
273 s Sampler
274 }
275
276 func (o localParentNotSampledOption) apply(config samplerConfig) samplerConfig {
277 config.localParentNotSampled = o.s
278 return config
279 }
280
281 func (pb parentBased) ShouldSample(p SamplingParameters) SamplingResult {
282 psc := trace.SpanContextFromContext(p.ParentContext)
283 if psc.IsValid() {
284 if psc.IsRemote() {
285 if psc.IsSampled() {
286 return pb.config.remoteParentSampled.ShouldSample(p)
287 }
288 return pb.config.remoteParentNotSampled.ShouldSample(p)
289 }
290
291 if psc.IsSampled() {
292 return pb.config.localParentSampled.ShouldSample(p)
293 }
294 return pb.config.localParentNotSampled.ShouldSample(p)
295 }
296 return pb.root.ShouldSample(p)
297 }
298
299 func (pb parentBased) Description() string {
300 return fmt.Sprintf("ParentBased{root:%s,remoteParentSampled:%s,"+
301 "remoteParentNotSampled:%s,localParentSampled:%s,localParentNotSampled:%s}",
302 pb.root.Description(),
303 pb.config.remoteParentSampled.Description(),
304 pb.config.remoteParentNotSampled.Description(),
305 pb.config.localParentSampled.Description(),
306 pb.config.localParentNotSampled.Description(),
307 )
308 }
309
310 // AlwaysRecord returns a sampler decorator which ensures that every span
311 // is passed to the SpanProcessor, even those that would be normally dropped.
312 // It converts `Drop` decisions from the root sampler into `RecordOnly` decisions,
313 // allowing processors to see all spans without sending them to exporters. This is
314 // typically used to enable accurate span-to-metrics processing.
315 func AlwaysRecord(root Sampler) Sampler {
316 return alwaysRecord{root}
317 }
318
319 type alwaysRecord struct {
320 root Sampler
321 }
322
323 func (ar alwaysRecord) ShouldSample(p SamplingParameters) SamplingResult {
324 rootSamplerSamplingResult := ar.root.ShouldSample(p)
325 if rootSamplerSamplingResult.Decision == Drop {
326 return SamplingResult{
327 Decision: RecordOnly,
328 Tracestate: trace.SpanContextFromContext(p.ParentContext).TraceState(),
329 }
330 }
331 return rootSamplerSamplingResult
332 }
333
334 func (ar alwaysRecord) Description() string {
335 return "AlwaysRecord{root:" + ar.root.Description() + "}"
336 }