| 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 |
} |