Debian Codegraph @

sdk/trace/provider.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 "errors"
9 "fmt"
10 "sync"
11 "sync/atomic"
12
13 "go.opentelemetry.io/otel"
14 "go.opentelemetry.io/otel/internal/global"
15 "go.opentelemetry.io/otel/sdk/instrumentation"
16 "go.opentelemetry.io/otel/sdk/resource"
17 "go.opentelemetry.io/otel/sdk/trace/internal/observ"
18 "go.opentelemetry.io/otel/trace"
19 "go.opentelemetry.io/otel/trace/embedded"
20 "go.opentelemetry.io/otel/trace/noop"
21 )
22
23 const defaultTracerName = "go.opentelemetry.io/otel/sdk/tracer"
24
25 // tracerProviderConfig.
26 type tracerProviderConfig struct {
27 // processors contains collection of SpanProcessors that are processing pipeline
28 // for spans in the trace signal.
29 // SpanProcessors registered with a TracerProvider and are called at the start
30 // and end of a Span's lifecycle, and are called in the order they are
31 // registered.
32 processors []SpanProcessor
33
34 // sampler is the default sampler used when creating new spans.
35 sampler Sampler
36
37 // idGenerator is used to generate all Span and Trace IDs when needed.
38 idGenerator IDGenerator
39
40 // spanLimits defines the attribute, event, and link limits for spans.
41 spanLimits SpanLimits
42
43 // resource contains attributes representing an entity that produces telemetry.
44 resource *resource.Resource
45 }
46
47 // MarshalLog is the marshaling function used by the logging system to represent this Provider.
48 func (cfg tracerProviderConfig) MarshalLog() any {
49 return struct {
50 SpanProcessors []SpanProcessor
51 SamplerType string
52 IDGeneratorType string
53 SpanLimits SpanLimits
54 Resource *resource.Resource
55 }{
56 SpanProcessors: cfg.processors,
57 SamplerType: fmt.Sprintf("%T", cfg.sampler),
58 IDGeneratorType: fmt.Sprintf("%T", cfg.idGenerator),
59 SpanLimits: cfg.spanLimits,
60 Resource: cfg.resource,
61 }
62 }
63
64 // TracerProvider is an OpenTelemetry TracerProvider. It provides Tracers to
65 // instrumentation so it can trace operational flow through a system.
66 type TracerProvider struct {
67 embedded.TracerProvider
68
69 mu sync.Mutex
70 namedTracer map[instrumentation.Scope]*tracer
71 spanProcessors atomic.Pointer[spanProcessorStates]
72
73 isShutdown atomic.Bool
74
75 // These fields are not protected by the lock mu. They are assumed to be
76 // immutable after creation of the TracerProvider.
77 sampler Sampler
78 idGenerator IDGenerator
79 spanLimits SpanLimits
80 resource *resource.Resource
81 }
82
83 var _ trace.TracerProvider = &TracerProvider{}
84
85 // NewTracerProvider returns a new and configured TracerProvider.
86 //
87 // By default the returned TracerProvider is configured with:
88 // - a ParentBased(AlwaysSample) Sampler
89 // - a random number IDGenerator
90 // - the resource.Default() Resource
91 // - the default SpanLimits.
92 //
93 // The passed opts are used to override these default values and configure the
94 // returned TracerProvider appropriately.
95 func NewTracerProvider(opts ...TracerProviderOption) *TracerProvider {
96 o := tracerProviderConfig{
97 spanLimits: NewSpanLimits(),
98 }
99 o = applyTracerProviderEnvConfigs(o)
100
101 for _, opt := range opts {
102 o = opt.apply(o)
103 }
104
105 o = ensureValidTracerProviderConfig(o)
106
107 tp := &TracerProvider{
108 namedTracer: make(map[instrumentation.Scope]*tracer),
109 sampler: o.sampler,
110 idGenerator: o.idGenerator,
111 spanLimits: o.spanLimits,
112 resource: o.resource,
113 }
114 global.Info("TracerProvider created", "config", o)
115
116 spss := make(spanProcessorStates, 0, len(o.processors))
117 for _, sp := range o.processors {
118 spss = append(spss, newSpanProcessorState(sp))
119 }
120 tp.spanProcessors.Store(&spss)
121
122 return tp
123 }
124
125 // Tracer returns a Tracer with the given name and options. If a Tracer for
126 // the given name and options does not exist it is created, otherwise the
127 // existing Tracer is returned.
128 //
129 // If name is empty, DefaultTracerName is used instead.
130 //
131 // This method is safe to be called concurrently.
132 func (p *TracerProvider) Tracer(name string, opts ...trace.TracerOption) trace.Tracer {
133 // This check happens before the mutex is acquired to avoid deadlocking if Tracer() is called from within Shutdown().
134 if p.isShutdown.Load() {
135 return noop.NewTracerProvider().Tracer(name, opts...)
136 }
137 c := trace.NewTracerConfig(opts...)
138 if name == "" {
139 name = defaultTracerName
140 }
141 is := instrumentation.Scope{
142 Name: name,
143 Version: c.InstrumentationVersion(),
144 SchemaURL: c.SchemaURL(),
145 Attributes: c.InstrumentationAttributes(),
146 }
147
148 t, ok := func() (trace.Tracer, bool) {
149 p.mu.Lock()
150 defer p.mu.Unlock()
151 // Must check the flag after acquiring the mutex to avoid returning a valid tracer if Shutdown() ran
152 // after the first check above but before we acquired the mutex.
153 if p.isShutdown.Load() {
154 return noop.NewTracerProvider().Tracer(name, opts...), true
155 }
156 t, ok := p.namedTracer[is]
157 if !ok {
158 t = &tracer{
159 provider: p,
160 instrumentationScope: is,
161 }
162
163 var err error
164 t.inst, err = observ.NewTracer()
165 if err != nil {
166 otel.Handle(err)
167 }
168
169 p.namedTracer[is] = t
170 }
171 return t, ok
172 }()
173 if !ok {
174 // This code is outside the mutex to not hold the lock while calling third party logging code:
175 // - That code may do slow things like I/O, which would prolong the duration the lock is held,
176 // slowing down all tracing consumers.
177 // - Logging code may be instrumented with tracing and deadlock because it could try
178 // acquiring the same non-reentrant mutex.
179 global.Info(
180 "Tracer created",
181 "name",
182 name,
183 "version",
184 is.Version,
185 "schemaURL",
186 is.SchemaURL,
187 "attributes",
188 is.Attributes,
189 )
190 }
191 return t
192 }
193
194 // RegisterSpanProcessor adds the given SpanProcessor to the list of SpanProcessors.
195 func (p *TracerProvider) RegisterSpanProcessor(sp SpanProcessor) {
196 // This check prevents calls during a shutdown.
197 if p.isShutdown.Load() {
198 return
199 }
200 p.mu.Lock()
201 defer p.mu.Unlock()
202 // This check prevents calls after a shutdown.
203 if p.isShutdown.Load() {
204 return
205 }
206
207 current := p.getSpanProcessors()
208 newSPS := make(spanProcessorStates, 0, len(current)+1)
209 newSPS = append(newSPS, current...)
210 newSPS = append(newSPS, newSpanProcessorState(sp))
211 p.spanProcessors.Store(&newSPS)
212 }
213
214 // UnregisterSpanProcessor removes the given SpanProcessor from the list of SpanProcessors.
215 func (p *TracerProvider) UnregisterSpanProcessor(sp SpanProcessor) {
216 // This check prevents calls during a shutdown.
217 if p.isShutdown.Load() {
218 return
219 }
220 p.mu.Lock()
221 defer p.mu.Unlock()
222 // This check prevents calls after a shutdown.
223 if p.isShutdown.Load() {
224 return
225 }
226 old := p.getSpanProcessors()
227 if len(old) == 0 {
228 return
229 }
230 spss := make(spanProcessorStates, len(old))
231 copy(spss, old)
232
233 // stop the span processor if it is started and remove it from the list
234 var stopOnce *spanProcessorState
235 var idx int
236 for i, sps := range spss {
237 if sps.sp == sp {
238 stopOnce = sps
239 idx = i
240 }
241 }
242 if stopOnce != nil {
243 stopOnce.state.Do(func() {
244 if err := sp.Shutdown(context.Background()); err != nil {
245 otel.Handle(err)
246 }
247 })
248 }
249 if len(spss) > 1 {
250 copy(spss[idx:], spss[idx+1:])
251 }
252 spss[len(spss)-1] = nil
253 spss = spss[:len(spss)-1]
254
255 p.spanProcessors.Store(&spss)
256 }
257
258 // ForceFlush immediately exports all spans that have not yet been exported for
259 // all the registered span processors.
260 func (p *TracerProvider) ForceFlush(ctx context.Context) error {
261 spss := p.getSpanProcessors()
262 if len(spss) == 0 {
263 return nil
264 }
265
266 var err error
267 for _, sps := range spss {
268 select {
269 case <-ctx.Done():
270 return ctx.Err()
271 default:
272 }
273
274 err = errors.Join(err, sps.sp.ForceFlush(ctx))
275 }
276 return err
277 }
278
279 // Shutdown shuts down TracerProvider. All registered span processors are shut down
280 // in the order they were registered and any held computational resources are released.
281 // After Shutdown is called, all methods are no-ops.
282 func (p *TracerProvider) Shutdown(ctx context.Context) error {
283 // This check prevents deadlocks in case of recursive shutdown.
284 if p.isShutdown.Load() {
285 return nil
286 }
287 p.mu.Lock()
288 defer p.mu.Unlock()
289 // This check prevents calls after a shutdown has already been done concurrently.
290 if !p.isShutdown.CompareAndSwap(false, true) { // did toggle?
291 return nil
292 }
293
294 var retErr error
295 for _, sps := range p.getSpanProcessors() {
296 select {
297 case <-ctx.Done():
298 return ctx.Err()
299 default:
300 }
301
302 var err error
303 sps.state.Do(func() {
304 err = sps.sp.Shutdown(ctx)
305 })
306 retErr = errors.Join(retErr, err)
307 }
308 p.spanProcessors.Store(&spanProcessorStates{})
309 return retErr
310 }
311
312 func (p *TracerProvider) getSpanProcessors() spanProcessorStates {
313 return *(p.spanProcessors.Load())
314 }
315
316 // TracerProviderOption configures a TracerProvider.
317 type TracerProviderOption interface {
318 apply(tracerProviderConfig) tracerProviderConfig
319 }
320
321 type traceProviderOptionFunc func(tracerProviderConfig) tracerProviderConfig
322
323 func (fn traceProviderOptionFunc) apply(cfg tracerProviderConfig) tracerProviderConfig {
324 return fn(cfg)
325 }
326
327 // WithSyncer registers the exporter with the TracerProvider using a
328 // SimpleSpanProcessor.
329 //
330 // This is not recommended for production use. The synchronous nature of the
331 // SimpleSpanProcessor that will wrap the exporter make it good for testing,
332 // debugging, or showing examples of other feature, but it will be slow and
333 // have a high computation resource usage overhead. The WithBatcher option is
334 // recommended for production use instead.
335 func WithSyncer(e SpanExporter) TracerProviderOption {
336 return WithSpanProcessor(NewSimpleSpanProcessor(e))
337 }
338
339 // WithBatcher registers the exporter with the TracerProvider using a
340 // BatchSpanProcessor configured with the passed opts.
341 func WithBatcher(e SpanExporter, opts ...BatchSpanProcessorOption) TracerProviderOption {
342 return WithSpanProcessor(NewBatchSpanProcessor(e, opts...))
343 }
344
345 // WithSpanProcessor registers the SpanProcessor with a TracerProvider.
346 func WithSpanProcessor(sp SpanProcessor) TracerProviderOption {
347 return traceProviderOptionFunc(func(cfg tracerProviderConfig) tracerProviderConfig {
348 cfg.processors = append(cfg.processors, sp)
349 return cfg
350 })
351 }
352
353 // WithResource returns a TracerProviderOption that will configure the
354 // Resource r as a TracerProvider's Resource. The configured Resource is
355 // referenced by all the Tracers the TracerProvider creates. It represents the
356 // entity producing telemetry.
357 //
358 // If this option is not used, the TracerProvider will use the
359 // resource.Default() Resource by default.
360 func WithResource(r *resource.Resource) TracerProviderOption {
361 return traceProviderOptionFunc(func(cfg tracerProviderConfig) tracerProviderConfig {
362 var err error
363 cfg.resource, err = resource.Merge(resource.Environment(), r)
364 if err != nil {
365 otel.Handle(err)
366 }
367 return cfg
368 })
369 }
370
371 // WithIDGenerator returns a TracerProviderOption that will configure the
372 // IDGenerator g as a TracerProvider's IDGenerator. The configured IDGenerator
373 // is used by the Tracers the TracerProvider creates to generate new Span and
374 // Trace IDs.
375 //
376 // If this option is not used, the TracerProvider will use a random number
377 // IDGenerator by default.
378 func WithIDGenerator(g IDGenerator) TracerProviderOption {
379 return traceProviderOptionFunc(func(cfg tracerProviderConfig) tracerProviderConfig {
380 if g != nil {
381 cfg.idGenerator = g
382 }
383 return cfg
384 })
385 }
386
387 // WithSampler returns a TracerProviderOption that will configure the Sampler
388 // s as a TracerProvider's Sampler. The configured Sampler is used by the
389 // Tracers the TracerProvider creates to make their sampling decisions for the
390 // Spans they create.
391 //
392 // This option overrides the Sampler configured through the OTEL_TRACES_SAMPLER
393 // and OTEL_TRACES_SAMPLER_ARG environment variables. If this option is not used
394 // and the sampler is not configured through environment variables or the environment
395 // contains invalid/unsupported configuration, the TracerProvider will use a
396 // ParentBased(AlwaysSample) Sampler by default.
397 func WithSampler(s Sampler) TracerProviderOption {
398 return traceProviderOptionFunc(func(cfg tracerProviderConfig) tracerProviderConfig {
399 if s != nil {
400 cfg.sampler = s
401 }
402 return cfg
403 })
404 }
405
406 // WithSpanLimits returns a TracerProviderOption that configures a
407 // TracerProvider to use the SpanLimits sl. These SpanLimits bound any Span
408 // created by a Tracer from the TracerProvider.
409 //
410 // If any field of sl is zero or negative it will be replaced with the default
411 // value for that field.
412 //
413 // If this or WithRawSpanLimits are not provided, the TracerProvider will use
414 // the limits defined by environment variables, or the defaults if unset.
415 // Refer to the NewSpanLimits documentation for information about this
416 // relationship.
417 //
418 // Deprecated: Use WithRawSpanLimits instead which allows setting unlimited
419 // and zero limits. This option will be kept until the next major version
420 // incremented release.
421 func WithSpanLimits(sl SpanLimits) TracerProviderOption {
422 if sl.AttributeValueLengthLimit <= 0 {
423 sl.AttributeValueLengthLimit = DefaultAttributeValueLengthLimit
424 }
425 if sl.AttributeCountLimit <= 0 {
426 sl.AttributeCountLimit = DefaultAttributeCountLimit
427 }
428 if sl.EventCountLimit <= 0 {
429 sl.EventCountLimit = DefaultEventCountLimit
430 }
431 if sl.AttributePerEventCountLimit <= 0 {
432 sl.AttributePerEventCountLimit = DefaultAttributePerEventCountLimit
433 }
434 if sl.LinkCountLimit <= 0 {
435 sl.LinkCountLimit = DefaultLinkCountLimit
436 }
437 if sl.AttributePerLinkCountLimit <= 0 {
438 sl.AttributePerLinkCountLimit = DefaultAttributePerLinkCountLimit
439 }
440 return traceProviderOptionFunc(func(cfg tracerProviderConfig) tracerProviderConfig {
441 cfg.spanLimits = sl
442 return cfg
443 })
444 }
445
446 // WithRawSpanLimits returns a TracerProviderOption that configures a
447 // TracerProvider to use these limits. These limits bound any Span created by
448 // a Tracer from the TracerProvider.
449 //
450 // The limits will be used as-is. Zero or negative values will not be changed
451 // to the default value like WithSpanLimits does. Setting a limit to zero will
452 // effectively disable the related resource it limits and setting to a
453 // negative value will mean that resource is unlimited. Consequentially, this
454 // means that the zero-value SpanLimits will disable all span resources.
455 // Because of this, limits should be constructed using NewSpanLimits and
456 // updated accordingly.
457 //
458 // If this or WithSpanLimits are not provided, the TracerProvider will use the
459 // limits defined by environment variables, or the defaults if unset. Refer to
460 // the NewSpanLimits documentation for information about this relationship.
461 func WithRawSpanLimits(limits SpanLimits) TracerProviderOption {
462 return traceProviderOptionFunc(func(cfg tracerProviderConfig) tracerProviderConfig {
463 cfg.spanLimits = limits
464 return cfg
465 })
466 }
467
468 func applyTracerProviderEnvConfigs(cfg tracerProviderConfig) tracerProviderConfig {
469 for _, opt := range tracerProviderOptionsFromEnv() {
470 cfg = opt.apply(cfg)
471 }
472
473 return cfg
474 }
475
476 func tracerProviderOptionsFromEnv() []TracerProviderOption {
477 var opts []TracerProviderOption
478
479 sampler, err := samplerFromEnv()
480 if err != nil {
481 otel.Handle(err)
482 }
483
484 if sampler != nil {
485 opts = append(opts, WithSampler(sampler))
486 }
487
488 return opts
489 }
490
491 // ensureValidTracerProviderConfig ensures that given TracerProviderConfig is valid.
492 func ensureValidTracerProviderConfig(cfg tracerProviderConfig) tracerProviderConfig {
493 if cfg.sampler == nil {
494 cfg.sampler = ParentBased(AlwaysSample())
495 }
496 if cfg.idGenerator == nil {
497 cfg.idGenerator = defaultIDGenerator()
498 }
499 if cfg.resource == nil {
500 cfg.resource = resource.Default()
501 }
502 return cfg
503 }