Debian Codegraph @

sdk/metric/doc.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 // Package metric provides an implementation of the OpenTelemetry metrics SDK.
5 //
6 // See https://opentelemetry.io/docs/concepts/signals/metrics/ for information
7 // about the concept of OpenTelemetry metrics and
8 // https://opentelemetry.io/docs/concepts/components/ for more information
9 // about OpenTelemetry SDKs.
10 //
11 // The entry point for the metric package is the MeterProvider. It is the
12 // object that all API calls use to create Meters, instruments, and ultimately
13 // make metric measurements. Also, it is an object that should be used to
14 // control the life-cycle (start, flush, and shutdown) of the SDK.
15 //
16 // A MeterProvider needs to be configured to export the measured data, this is
17 // done by configuring it with a Reader implementation (using the WithReader
18 // MeterProviderOption). Readers take two forms: ones that push to an endpoint
19 // (NewPeriodicReader), and ones that an endpoint pulls from. See
20 // [go.opentelemetry.io/otel/exporters] for exporters that can be used as
21 // or with these Readers.
22 //
23 // Each Reader, when registered with the MeterProvider, can be augmented with a
24 // View. Views allow users that run OpenTelemetry instrumented code to modify
25 // the generated data of that instrumentation.
26 //
27 // The data generated by a MeterProvider needs to include information about its
28 // origin. A MeterProvider needs to be configured with a Resource, using the
29 // WithResource MeterProviderOption, to include this information. This Resource
30 // should be used to describe the unique runtime environment instrumented code
31 // is being run on. That way when multiple instances of the code are collected
32 // at a single endpoint their origin is decipherable.
33 //
34 // To avoid leaking memory, the SDK returns the same instrument for calls to
35 // create new instruments with the same Name, Unit, and Description.
36 // Importantly, callbacks provided using metric.WithFloat64Callback or
37 // metric.WithInt64Callback will only apply for the first instrument created
38 // with a given Name, Unit, and Description. Instead, use
39 // Meter.RegisterCallback and Registration.Unregister to add and remove
40 // callbacks without leaking memory.
41 //
42 // # Cardinality Limits
43 //
44 // Cardinality refers to the number of unique attributes collected. High cardinality can lead to
45 // excessive memory usage, increased storage costs, and backend performance issues.
46 //
47 // Currently, the OpenTelemetry Go Metric SDK does not enforce a cardinality limit by default
48 // (note that this may change in a future release). Use [WithCardinalityLimit] to set the
49 // cardinality limit as desired.
50 //
51 // New attribute sets are dropped when the cardinality limit is reached. The measurement of
52 // these sets are aggregated into
53 // a special attribute set containing attribute.Bool("otel.metric.overflow", true).
54 // This ensures total metric values (e.g., Sum, Count) remain correct for the
55 // collection cycle, but information about the specific dropped sets
56 // is not preserved.
57 //
58 // Recommendations:
59 //
60 // - Set the limit based on the theoretical maximum combinations or expected
61 // active combinations. The OpenTelemetry Specification recommends a default of 2000.
62 // - A too high of a limit increases worst-case memory overhead in the SDK and may cause downstream
63 // issues for databases that cannot handle high cardinality.
64 // - A too low of a limit causes loss of attribute detail as more data falls into overflow.
65 //
66 // # Ordering and Collection Guarantees
67 //
68 // For performance reasons, the SDK does not guarantee that the order in which
69 // synchronous measurements are made to the SDK is reflected in the collected
70 // metric data. This means that even when a single goroutine makes sequential
71 // synchronous measurements, it is possible for a later measurement to be
72 // included in the collected metric data when an earlier measurement is not.
73 // This applies to measurements made to different instruments, or to different
74 // attribute sets on the same instrument. Sequential measurements made to the
75 // same instrument and with the same attributes are guaranteed to preserve
76 // ordering with respect to collection.
77 //
78 // Additionally, the SDK does not guarantee that exemplars are always included
79 // in the same batch of metric data as the measurement they are associated
80 // with.
81 //
82 // See [go.opentelemetry.io/otel/metric] for more information about
83 // the metric API.
84 //
85 // See [go.opentelemetry.io/otel/sdk/metric/internal/x] for information about
86 // the experimental features.
87 package metric // import "go.opentelemetry.io/otel/sdk/metric"