[−][src]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. Instrument
s 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 Counter
s, Gauge
s, and
Measure
s.
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 |
MetricOptions |
|
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 |
|
Meter | Meter is an interface to the metrics portion of the OpenTelemetry SDK. |