Module opentelemetry::api::metrics

OpenTelemetry Metrics API

The user-facing metrics API supports producing diagnostic measurements using three basic kinds of instrument. "Metrics" are the thing being produced--mathematical, statistical summaries of certain observable behavior in the program. Instruments are the devices used by the program to record observations about their behavior. Therefore, we use "metric instrument" to refer to a program object, allocated through the API, used for recording metrics. There are three distinct instruments in the Metrics API, commonly known as Counters, Gauges, and Measures.

Monitoring and alerting are the common use-case for the data provided through metric instruments, after various collection and aggregation strategies are applied to the data. We find there are many other uses for the metric events that stream into these instruments. We imagine metric data being aggregated and recorded as events in tracing and logging systems too, and for this reason OpenTelemetry requires a separation of the API from the SDK.

To capture measurements using an Instrument, you need an SDK that implements the Meter API.

Metric kinds and inputs

The API distinguishes metric instruments by semantic meaning, not by the type of value produced in an exporter. This is a departure from convention, compared with a number of common metric libraries, and stems from the separation of the API and the SDK. The SDK ultimately determines how to handle metric events and could potentially implement non-standard behavior.

This explains why the metric API does not have metric instrument kinds for exporting "Histogram" and "Summary" distribution explicitly, for example. These are both semantically Measure instruments and an SDK can be configured to produce histograms or distribution summaries from Measure events. It is out of scope for the Metrics API to specify how these alternatives are configured in a particular SDK.

We believe the three metric kinds Counter, Gauge, and Measure form a sufficient basis for expression of a wide variety of metric data. Programmers write and read these as add(), set(), and record() method calls, signifying the semantics and standard interpretation, and we believe these three methods are all that are needed.

Nevertheless, it is common to apply restrictions on metric values, the inputs to add(), set(), and record(), in order to refine their standard interpretation. Generally, there is a question of whether the instrument can be used to compute a rate, because that is usually a desirable analysis. Each metric instrument offers an optional declaration, specifying restrictions on values input to the metric. For example, Measures are declared as non-negative by default, appropriate for reporting sizes and durations; a Measure option is provided to record positive or negative values, but it does not change the kind of instrument or the method name used, as the semantics are unchanged.

Modules

counter	Metrics Counter Interface
gauge	Metrics Gauge Interface
measure	Metrics Measure Interface
noop	No-op OpenTelemetry Metrics Implementation
value	OpenTelemetry Metrics Measurement Values

Structs

Measurement	Used to record MeasurementValues for a given Instrument for use in batch recording by a Meter.
MetricOptions	MetricOptions contains some options for metrics of any kind.

Traits

Instrument	The implementation-level interface to Set/Add/Record individual metrics without precomputed labels.
InstrumentHandle	The implementation-level interface to Set/Add/Record individual metrics with precomputed labels.
LabelSet	LabelSet is an implementation-level interface that represents a set of KeyValue for use as pre-defined labels in the metrics API.
Meter	Meter is an interface to the metrics portion of the OpenTelemetry SDK.