Debian Codegraph @

sdk/metric/periodic_reader.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 "errors"
9 "fmt"
10 "sync"
11 "sync/atomic"
12 "time"
13
14 "go.opentelemetry.io/otel"
15 "go.opentelemetry.io/otel/internal/global"
16 "go.opentelemetry.io/otel/sdk/metric/internal/observ"
17 "go.opentelemetry.io/otel/sdk/metric/metricdata"
18 semconv "go.opentelemetry.io/otel/semconv/v1.40.0"
19 )
20
21 // Default periodic reader timing.
22 const (
23 defaultTimeout = time.Millisecond * 30000
24 defaultInterval = time.Millisecond * 60000
25 )
26
27 // periodicReaderConfig contains configuration options for a PeriodicReader.
28 type periodicReaderConfig struct {
29 interval time.Duration
30 timeout time.Duration
31 producers []Producer
32 cardinalityLimitSelector CardinalityLimitSelector
33 }
34
35 // newPeriodicReaderConfig returns a periodicReaderConfig configured with
36 // options.
37 func newPeriodicReaderConfig(options []PeriodicReaderOption) periodicReaderConfig {
38 c := periodicReaderConfig{
39 interval: envDuration(envInterval, defaultInterval),
40 timeout: envDuration(envTimeout, defaultTimeout),
41 cardinalityLimitSelector: defaultCardinalityLimitSelector,
42 }
43 for _, o := range options {
44 c = o.applyPeriodic(c)
45 }
46 return c
47 }
48
49 // PeriodicReaderOption applies a configuration option value to a PeriodicReader.
50 type PeriodicReaderOption interface {
51 applyPeriodic(periodicReaderConfig) periodicReaderConfig
52 }
53
54 // periodicReaderOptionFunc applies a set of options to a periodicReaderConfig.
55 type periodicReaderOptionFunc func(periodicReaderConfig) periodicReaderConfig
56
57 // applyPeriodic returns a periodicReaderConfig with option(s) applied.
58 func (o periodicReaderOptionFunc) applyPeriodic(conf periodicReaderConfig) periodicReaderConfig {
59 return o(conf)
60 }
61
62 // WithTimeout configures the time a PeriodicReader waits for an export to
63 // complete before canceling it. This includes an export which occurs as part
64 // of Shutdown or ForceFlush if the user passed context does not have a
65 // deadline. If the user passed context does have a deadline, it will be used
66 // instead.
67 //
68 // This option overrides any value set for the
69 // OTEL_METRIC_EXPORT_TIMEOUT environment variable.
70 //
71 // If this option is not used or d is less than or equal to zero, 30 seconds
72 // is used as the default.
73 func WithTimeout(d time.Duration) PeriodicReaderOption {
74 return periodicReaderOptionFunc(func(conf periodicReaderConfig) periodicReaderConfig {
75 if d <= 0 {
76 return conf
77 }
78 conf.timeout = d
79 return conf
80 })
81 }
82
83 // WithInterval configures the intervening time between exports for a
84 // PeriodicReader.
85 //
86 // This option overrides any value set for the
87 // OTEL_METRIC_EXPORT_INTERVAL environment variable.
88 //
89 // If this option is not used or d is less than or equal to zero, 60 seconds
90 // is used as the default.
91 func WithInterval(d time.Duration) PeriodicReaderOption {
92 return periodicReaderOptionFunc(func(conf periodicReaderConfig) periodicReaderConfig {
93 if d <= 0 {
94 return conf
95 }
96 conf.interval = d
97 return conf
98 })
99 }
100
101 // NewPeriodicReader returns a Reader that collects and exports metric data to
102 // the exporter at a defined interval. By default, the returned Reader will
103 // collect and export data every 60 seconds, and will cancel any attempts that
104 // exceed 30 seconds, collect and export combined. The collect and export time
105 // are not counted towards the interval between attempts.
106 //
107 // The Collect method of the returned Reader continues to gather and return
108 // metric data to the user. It will not automatically send that data to the
109 // exporter. That is left to the user to accomplish.
110 func NewPeriodicReader(exporter Exporter, options ...PeriodicReaderOption) *PeriodicReader {
111 conf := newPeriodicReaderConfig(options)
112 ctx, cancel := context.WithCancel( //nolint:gosec // cancel called during PeriodicReader shutdown.
113 context.Background(),
114 )
115 r := &PeriodicReader{
116 interval: conf.interval,
117 timeout: conf.timeout,
118 exporter: exporter,
119 flushCh: make(chan chan error),
120 cancel: cancel,
121 done: make(chan struct{}),
122 cardinalityLimitSelector: conf.cardinalityLimitSelector,
123 rmPool: sync.Pool{
124 New: func() any {
125 return &metricdata.ResourceMetrics{}
126 },
127 },
128 }
129 r.externalProducers.Store(conf.producers)
130
131 go func() {
132 defer func() { close(r.done) }()
133 r.run(ctx, conf.interval)
134 }()
135
136 var err error
137 r.inst, err = observ.NewInstrumentation(
138 semconv.OTelComponentTypePeriodicMetricReader.Value.AsString(),
139 nextPeriodicReaderID(),
140 )
141 if err != nil {
142 otel.Handle(err)
143 }
144
145 return r
146 }
147
148 var periodicReaderIDCounter atomic.Int64
149
150 // nextPeriodicReaderID returns an identifier for this periodic reader,
151 // starting with 0 and incrementing by 1 each time it is called.
152 func nextPeriodicReaderID() int64 {
153 return periodicReaderIDCounter.Add(1) - 1
154 }
155
156 // PeriodicReader is a Reader that continuously collects and exports metric
157 // data at a set interval.
158 type PeriodicReader struct {
159 sdkProducer atomic.Value
160
161 mu sync.Mutex
162 isShutdown bool
163 externalProducers atomic.Value
164
165 interval time.Duration
166 timeout time.Duration
167 exporter Exporter
168 flushCh chan chan error
169
170 done chan struct{}
171 cancel context.CancelFunc
172 shutdownOnce sync.Once
173
174 rmPool sync.Pool
175
176 cardinalityLimitSelector CardinalityLimitSelector
177
178 inst *observ.Instrumentation
179 }
180
181 // Compile time check the periodicReader implements Reader and is comparable.
182 var _ = map[Reader]struct{}{&PeriodicReader{}: {}}
183
184 // newTicker allows testing override.
185 var newTicker = time.NewTicker
186
187 // run continuously collects and exports metric data at the specified
188 // interval. This will run until ctx is canceled or times out.
189 func (r *PeriodicReader) run(ctx context.Context, interval time.Duration) {
190 ticker := newTicker(interval)
191 defer ticker.Stop()
192
193 for {
194 select {
195 case <-ticker.C:
196 err := r.collectAndExport(ctx)
197 if err != nil {
198 otel.Handle(err)
199 }
200 case errCh := <-r.flushCh:
201 errCh <- r.collectAndExport(ctx)
202 ticker.Reset(interval)
203 case <-ctx.Done():
204 return
205 }
206 }
207 }
208
209 // register registers p as the producer of this reader.
210 func (r *PeriodicReader) register(p sdkProducer) {
211 // Only register once. If producer is already set, do nothing.
212 if !r.sdkProducer.CompareAndSwap(nil, produceHolder{produce: p.produce}) {
213 msg := "did not register periodic reader"
214 global.Error(errDuplicateRegister, msg)
215 }
216 }
217
218 // temporality reports the Temporality for the instrument kind provided.
219 func (r *PeriodicReader) temporality(kind InstrumentKind) metricdata.Temporality {
220 return r.exporter.Temporality(kind)
221 }
222
223 // aggregation returns what Aggregation to use for kind.
224 func (r *PeriodicReader) aggregation(
225 kind InstrumentKind,
226 ) Aggregation { // nolint:revive // import-shadow for method scoped by type.
227 return r.exporter.Aggregation(kind)
228 }
229
230 // cardinalityLimit returns the cardinality limit for kind.
231 func (r *PeriodicReader) cardinalityLimit(kind InstrumentKind) (int, bool) {
232 return r.cardinalityLimitSelector(kind)
233 }
234
235 // collectAndExport gather all metric data related to the periodicReader r from
236 // the SDK and exports it with r's exporter.
237 func (r *PeriodicReader) collectAndExport(ctx context.Context) error {
238 ctx, cancel := context.WithTimeoutCause(ctx, r.timeout, errors.New("reader collect and export timeout"))
239 defer cancel()
240
241 // TODO (#3047): Use a sync.Pool or persistent pointer instead of allocating rm every Collect.
242 rm := r.rmPool.Get().(*metricdata.ResourceMetrics)
243 err := r.Collect(ctx, rm)
244 if err == nil {
245 err = r.export(ctx, rm)
246 }
247 r.rmPool.Put(rm)
248 return err
249 }
250
251 // Collect gathers all metric data related to the Reader from
252 // the SDK and other Producers and stores the result in rm. The metric
253 // data is not exported to the configured exporter, it is left to the caller to
254 // handle that if desired.
255 //
256 // Collect will return an error if called after shutdown.
257 // Collect will return an error if rm is a nil ResourceMetrics.
258 // Collect will return an error if the context's Done channel is closed.
259 //
260 // This method is safe to call concurrently.
261 func (r *PeriodicReader) Collect(ctx context.Context, rm *metricdata.ResourceMetrics) error {
262 if rm == nil {
263 return errors.New("periodic reader: *metricdata.ResourceMetrics is nil")
264 }
265 // TODO (#3047): When collect is updated to accept output as param, pass rm.
266 return r.collect(ctx, r.sdkProducer.Load(), rm)
267 }
268
269 // collect unwraps p as a produceHolder and returns its produce results.
270 func (r *PeriodicReader) collect(ctx context.Context, p any, rm *metricdata.ResourceMetrics) error {
271 var err error
272 if r.inst != nil {
273 cp := r.inst.CollectMetrics(ctx)
274 defer func() { cp.End(err) }()
275 }
276
277 if p == nil {
278 err = ErrReaderNotRegistered
279 return err
280 }
281
282 ph, ok := p.(produceHolder)
283 if !ok {
284 // The atomic.Value is entirely in the periodicReader's control so
285 // this should never happen. In the unforeseen case that this does
286 // happen, return an error instead of panicking so a users code does
287 // not halt in the processes.
288 err = fmt.Errorf("periodic reader: invalid producer: %T", p)
289 return err
290 }
291
292 err = ph.produce(ctx, rm)
293 if err != nil {
294 return err
295 }
296 for _, producer := range r.externalProducers.Load().([]Producer) {
297 externalMetrics, e := producer.Produce(ctx)
298 if e != nil {
299 err = errors.Join(err, e)
300 }
301 rm.ScopeMetrics = append(rm.ScopeMetrics, externalMetrics...)
302 }
303
304 global.Debug("PeriodicReader collection", "Data", rm)
305
306 return err
307 }
308
309 // export exports metric data m using r's exporter.
310 func (r *PeriodicReader) export(ctx context.Context, m *metricdata.ResourceMetrics) error {
311 return r.exporter.Export(ctx, m)
312 }
313
314 // ForceFlush flushes pending telemetry.
315 //
316 // This method is safe to call concurrently.
317 func (r *PeriodicReader) ForceFlush(ctx context.Context) error {
318 // Prioritize the ctx timeout if it is set.
319 if _, ok := ctx.Deadline(); !ok {
320 var cancel context.CancelFunc
321 ctx, cancel = context.WithTimeoutCause(ctx, r.timeout, errors.New("reader force flush timeout"))
322 defer cancel()
323 }
324
325 errCh := make(chan error, 1)
326 select {
327 case r.flushCh <- errCh:
328 select {
329 case err := <-errCh:
330 if err != nil {
331 return err
332 }
333 close(errCh)
334 case <-ctx.Done():
335 return ctx.Err()
336 }
337 case <-r.done:
338 return ErrReaderShutdown
339 case <-ctx.Done():
340 return ctx.Err()
341 }
342 return r.exporter.ForceFlush(ctx)
343 }
344
345 // Shutdown flushes pending telemetry and then stops the export pipeline.
346 //
347 // This method is safe to call concurrently.
348 func (r *PeriodicReader) Shutdown(ctx context.Context) error {
349 err := ErrReaderShutdown
350 r.shutdownOnce.Do(func() {
351 // Prioritize the ctx timeout if it is set.
352 if _, ok := ctx.Deadline(); !ok {
353 var cancel context.CancelFunc
354 ctx, cancel = context.WithTimeoutCause(ctx, r.timeout, errors.New("reader shutdown timeout"))
355 defer cancel()
356 }
357
358 // Stop the run loop.
359 r.cancel()
360 <-r.done
361
362 // Any future call to Collect will now return ErrReaderShutdown.
363 ph := r.sdkProducer.Swap(produceHolder{
364 produce: shutdownProducer{}.produce,
365 })
366
367 if ph != nil { // Reader was registered.
368 // Flush pending telemetry.
369 m := r.rmPool.Get().(*metricdata.ResourceMetrics)
370 err = r.collect(ctx, ph, m)
371 if err == nil {
372 err = r.export(ctx, m)
373 }
374 r.rmPool.Put(m)
375 }
376
377 sErr := r.exporter.Shutdown(ctx)
378 if err == nil || errors.Is(err, ErrReaderShutdown) {
379 err = sErr
380 }
381
382 r.mu.Lock()
383 defer r.mu.Unlock()
384 r.isShutdown = true
385 // release references to Producer(s)
386 r.externalProducers.Store([]Producer{})
387 })
388 return err
389 }
390
391 // MarshalLog returns logging data about the PeriodicReader.
392 func (r *PeriodicReader) MarshalLog() any {
393 r.mu.Lock()
394 down := r.isShutdown
395 r.mu.Unlock()
396 return struct {
397 Type string
398 Exporter Exporter
399 Registered bool
400 Shutdown bool
401 Interval time.Duration
402 Timeout time.Duration
403 }{
404 Type: "PeriodicReader",
405 Exporter: r.exporter,
406 Registered: r.sdkProducer.Load() != nil,
407 Shutdown: down,
408 Interval: r.interval,
409 Timeout: r.timeout,
410 }
411 }