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