You've already forked opentelemetry-go
mirror of
https://github.com/open-telemetry/opentelemetry-go.git
synced 2025-11-29 23:07:45 +02:00
5f5f4af5e5
Forked from this discussion here: https://github.com/open-telemetry/opentelemetry-go/pull/7443#discussion_r2402481912 It seems like a good idea for us as a group to align on and document what we are comfortable with in terms of how ordered measurements are reflected in collected metric data. --------- Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com>
88 lines
4.5 KiB
Go
88 lines
4.5 KiB
Go
// Copyright The OpenTelemetry Authors
|
|
// SPDX-License-Identifier: Apache-2.0
|
|
|
|
// Package metric provides an implementation of the OpenTelemetry metrics SDK.
|
|
//
|
|
// See https://opentelemetry.io/docs/concepts/signals/metrics/ for information
|
|
// about the concept of OpenTelemetry metrics and
|
|
// https://opentelemetry.io/docs/concepts/components/ for more information
|
|
// about OpenTelemetry SDKs.
|
|
//
|
|
// The entry point for the metric package is the MeterProvider. It is the
|
|
// object that all API calls use to create Meters, instruments, and ultimately
|
|
// make metric measurements. Also, it is an object that should be used to
|
|
// control the life-cycle (start, flush, and shutdown) of the SDK.
|
|
//
|
|
// A MeterProvider needs to be configured to export the measured data, this is
|
|
// done by configuring it with a Reader implementation (using the WithReader
|
|
// MeterProviderOption). Readers take two forms: ones that push to an endpoint
|
|
// (NewPeriodicReader), and ones that an endpoint pulls from. See
|
|
// [go.opentelemetry.io/otel/exporters] for exporters that can be used as
|
|
// or with these Readers.
|
|
//
|
|
// Each Reader, when registered with the MeterProvider, can be augmented with a
|
|
// View. Views allow users that run OpenTelemetry instrumented code to modify
|
|
// the generated data of that instrumentation.
|
|
//
|
|
// The data generated by a MeterProvider needs to include information about its
|
|
// origin. A MeterProvider needs to be configured with a Resource, using the
|
|
// WithResource MeterProviderOption, to include this information. This Resource
|
|
// should be used to describe the unique runtime environment instrumented code
|
|
// is being run on. That way when multiple instances of the code are collected
|
|
// at a single endpoint their origin is decipherable.
|
|
//
|
|
// To avoid leaking memory, the SDK returns the same instrument for calls to
|
|
// create new instruments with the same Name, Unit, and Description.
|
|
// Importantly, callbacks provided using metric.WithFloat64Callback or
|
|
// metric.WithInt64Callback will only apply for the first instrument created
|
|
// with a given Name, Unit, and Description. Instead, use
|
|
// Meter.RegisterCallback and Registration.Unregister to add and remove
|
|
// callbacks without leaking memory.
|
|
//
|
|
// # Cardinality Limits
|
|
//
|
|
// Cardinality refers to the number of unique attributes collected. High cardinality can lead to
|
|
// excessive memory usage, increased storage costs, and backend performance issues.
|
|
//
|
|
// Currently, the OpenTelemetry Go Metric SDK does not enforce a cardinality limit by default
|
|
// (note that this may change in a future release). Use [WithCardinalityLimit] to set the
|
|
// cardinality limit as desired.
|
|
//
|
|
// New attribute sets are dropped when the cardinality limit is reached. The measurement of
|
|
// these sets are aggregated into
|
|
// a special attribute set containing attribute.Bool("otel.metric.overflow", true).
|
|
// This ensures total metric values (e.g., Sum, Count) remain correct for the
|
|
// collection cycle, but information about the specific dropped sets
|
|
// is not preserved.
|
|
//
|
|
// Recommendations:
|
|
//
|
|
// - Set the limit based on the theoretical maximum combinations or expected
|
|
// active combinations. The OpenTelemetry Specification recommends a default of 2000.
|
|
// - A too high of a limit increases worst-case memory overhead in the SDK and may cause downstream
|
|
// issues for databases that cannot handle high cardinality.
|
|
// - A too low of a limit causes loss of attribute detail as more data falls into overflow.
|
|
//
|
|
// # Ordering and Collection Guarantees
|
|
//
|
|
// For performance reasons, the SDK does not guarantee that the order in which
|
|
// synchronous measurements are made to the SDK is reflected in the collected
|
|
// metric data. This means that even when a single goroutine makes sequential
|
|
// synchronous measurements, it is possible for a later measurement to be
|
|
// included in the collected metric data when an earlier measurement is not.
|
|
// This applies to measurements made to different instruments, or to different
|
|
// attribute sets on the same instrument. Sequential measurements made to the
|
|
// same instrument and with the same attributes are guaranteed to preserve
|
|
// ordering with respect to collection.
|
|
//
|
|
// Additionally, the SDK does not guarantee that exemplars are always included
|
|
// in the same batch of metric data as the measurement they are associated
|
|
// with.
|
|
//
|
|
// See [go.opentelemetry.io/otel/metric] for more information about
|
|
// the metric API.
|
|
//
|
|
// See [go.opentelemetry.io/otel/sdk/metric/internal/x] for information about
|
|
// the experimental features.
|
|
package metric // import "go.opentelemetry.io/otel/sdk/metric"
|