Debian Codegraph @

sdk/metric/provider.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 package metric // import "go.opentelemetry.io/otel/sdk/metric"
5
6 import (
7 "context"
8 "sync/atomic"
9
10 "go.opentelemetry.io/otel/internal/global"
11 "go.opentelemetry.io/otel/metric"
12 "go.opentelemetry.io/otel/metric/embedded"
13 "go.opentelemetry.io/otel/metric/noop"
14 "go.opentelemetry.io/otel/sdk/instrumentation"
15 )
16
17 // MeterProvider handles the creation and coordination of Meters. All Meters
18 // created by a MeterProvider will be associated with the same Resource, have
19 // the same Views applied to them, and have their produced metric telemetry
20 // passed to the configured Readers.
21 type MeterProvider struct {
22 embedded.MeterProvider
23
24 pipes pipelines
25 meters cache[instrumentation.Scope, *meter]
26
27 forceFlush, shutdown func(context.Context) error
28 stopped atomic.Bool
29 }
30
31 // Compile-time check MeterProvider implements metric.MeterProvider.
32 var _ metric.MeterProvider = (*MeterProvider)(nil)
33
34 // NewMeterProvider returns a new and configured MeterProvider.
35 //
36 // By default, the returned MeterProvider is configured with the default
37 // Resource and no Readers. Readers cannot be added after a MeterProvider is
38 // created. This means the returned MeterProvider, one created with no
39 // Readers, will perform no operations.
40 func NewMeterProvider(options ...Option) *MeterProvider {
41 conf := newConfig(options)
42 flush, sdown := conf.readerSignals()
43
44 mp := &MeterProvider{
45 pipes: newPipelines(conf.res, conf.readers, conf.views, conf.exemplarFilter, conf.cardinalityLimit),
46 forceFlush: flush,
47 shutdown: sdown,
48 }
49 // Log after creation so all readers show correctly they are registered.
50 global.Info("MeterProvider created",
51 "Resource", conf.res,
52 "Readers", conf.readers,
53 "Views", len(conf.views),
54 )
55 return mp
56 }
57
58 // Meter returns a Meter with the given name and configured with options.
59 //
60 // The name should be the name of the instrumentation scope creating
61 // telemetry. This name may be the same as the instrumented code only if that
62 // code provides built-in instrumentation.
63 //
64 // Calls to the Meter method after Shutdown has been called will return Meters
65 // that perform no operations.
66 //
67 // This method is safe to call concurrently.
68 func (mp *MeterProvider) Meter(name string, options ...metric.MeterOption) metric.Meter {
69 if name == "" {
70 global.Warn("Invalid Meter name.", "name", name)
71 }
72
73 if mp.stopped.Load() {
74 return noop.Meter{}
75 }
76
77 c := metric.NewMeterConfig(options...)
78 s := instrumentation.Scope{
79 Name: name,
80 Version: c.InstrumentationVersion(),
81 SchemaURL: c.SchemaURL(),
82 Attributes: c.InstrumentationAttributes(),
83 }
84
85 global.Info("Meter created",
86 "Name", s.Name,
87 "Version", s.Version,
88 "SchemaURL", s.SchemaURL,
89 "Attributes", s.Attributes,
90 )
91
92 return mp.meters.Lookup(s, func() *meter {
93 return newMeter(s, mp.pipes)
94 })
95 }
96
97 // ForceFlush flushes all pending telemetry.
98 //
99 // This method honors the deadline or cancellation of ctx. An appropriate
100 // error will be returned in these situations. There is no guaranteed that all
101 // telemetry be flushed or all resources have been released in these
102 // situations.
103 //
104 // ForceFlush calls ForceFlush(context.Context) error
105 // on all Readers that implements this method.
106 //
107 // This method is safe to call concurrently.
108 func (mp *MeterProvider) ForceFlush(ctx context.Context) error {
109 if mp.forceFlush != nil {
110 return mp.forceFlush(ctx)
111 }
112 return nil
113 }
114
115 // Shutdown shuts down the MeterProvider flushing all pending telemetry and
116 // releasing any held computational resources.
117 //
118 // This call is idempotent. The first call will perform all flush and
119 // releasing operations. Subsequent calls will perform no action and will
120 // return an error stating this.
121 //
122 // Measurements made by instruments from meters this MeterProvider created
123 // will not be exported after Shutdown is called.
124 //
125 // This method honors the deadline or cancellation of ctx. An appropriate
126 // error will be returned in these situations. There is no guaranteed that all
127 // telemetry be flushed or all resources have been released in these
128 // situations.
129 //
130 // This method is safe to call concurrently.
131 func (mp *MeterProvider) Shutdown(ctx context.Context) error {
132 // Even though it may seem like there is a synchronization issue between the
133 // call to `Store` and checking `shutdown`, the Go concurrency model ensures
134 // that is not the case, as all the atomic operations executed in a program
135 // behave as though executed in some sequentially consistent order. This
136 // definition provides the same semantics as C++'s sequentially consistent
137 // atomics and Java's volatile variables.
138 // See https://go.dev/ref/mem#atomic and https://pkg.go.dev/sync/atomic.
139
140 mp.stopped.Store(true)
141 if mp.shutdown != nil {
142 return mp.shutdown(ctx)
143 }
144 return nil
145 }