opentelemetry.metrics package¶

Module contents¶

The OpenTelemetry metrics API describes the classes used to report raw measurements, as well as metrics with known aggregation and labels.

The Meter class is used to construct Metric s to record raw statistics as well as metrics with predefined aggregation.

See the metrics api spec for terminology and context clarification.

New in version 0.1.0.

Changed in version 0.5.0: meter_provider was replaced by get_meter_provider, set_preferred_meter_provider_implementation was replaced by set_meter_provider.

class opentelemetry.metrics.DefaultBoundInstrument[source]¶

Bases: object

The default bound metric instrument.

Used when no bound instrument implementation is available.

add(value)[source]¶

No-op implementation of BoundCounter add.

Parameters: value (~ValueT) – The value to add to the bound metric instrument.
Return type: None

record(value)[source]¶

No-op implementation of BoundMeasure record.

Parameters: value (~ValueT) – The value to record to the bound metric instrument.
Return type: None

release()[source]¶

No-op implementation of release.

Return type: None

class opentelemetry.metrics.BoundCounter[source]¶

Bases: object

add(value)[source]¶

Increases the value of the bound counter by value.

Parameters: value (~ValueT) – The value to add to the bound counter.
Return type: None

class opentelemetry.metrics.BoundMeasure[source]¶

Bases: object

record(value)[source]¶

Records the given value to this bound measure.

Parameters: value (~ValueT) – The value to record to the bound measure.
Return type: None

class opentelemetry.metrics.Metric[source]¶

Bases: abc.ABC

Base class for various types of metrics.

Metric class that inherit from this class are specialized with the type of bound metric instrument that the metric holds.

abstract bind(labels)[source]¶

Gets a bound metric instrument.

Bound metric instruments are useful to reduce the cost of repeatedly recording a metric with a pre-defined set of label values. All metric kinds (counter, measure) support declaring a set of required label keys. The values corresponding to these keys should be specified in every bound metric instrument. “Unspecified” label values, in cases where a bound metric instrument is requested but a value was not provided are permitted.

Parameters: labels (Dict[str, str]) – Labels to associate with the bound instrument.
Return type: object

class opentelemetry.metrics.DefaultMetric[source]¶

Bases: opentelemetry.metrics.Metric

The default Metric used when no Metric implementation is available.

bind(labels)[source]¶

Gets a DefaultBoundInstrument.

Parameters: labels (Dict[str, str]) – Labels to associate with the bound instrument.
Return type: DefaultBoundInstrument

add(value, labels)[source]¶

No-op implementation of Counter add.

Parameters

value (~ValueT) – The value to add to the counter metric.
labels (Dict[str, str]) – Labels to associate with the bound instrument.

Return type

None

record(value, labels)[source]¶

No-op implementation of Measure record.

Parameters

value (~ValueT) – The value to record to this measure metric.
labels (Dict[str, str]) – Labels to associate with the bound instrument.

Return type

None

class opentelemetry.metrics.Counter[source]¶

Bases: opentelemetry.metrics.Metric

A counter type metric that expresses the computation of a sum.

bind(labels)[source]¶

Gets a BoundCounter.

Return type: BoundCounter

add(value, labels)[source]¶

Increases the value of the counter by value.

Parameters

value (~ValueT) – The value to add to the counter metric.
labels (Dict[str, str]) – Labels to associate with the bound instrument.

Return type

None

class opentelemetry.metrics.Measure[source]¶

Bases: opentelemetry.metrics.Metric

A measure type metric that represent raw stats that are recorded.

Measure metrics represent raw statistics that are recorded.

bind(labels)[source]¶

Gets a BoundMeasure.

Return type: BoundMeasure

record(value, labels)[source]¶

Records the value to the measure.

Parameters

value (~ValueT) – The value to record to this measure metric.
labels (Dict[str, str]) – Labels to associate with the bound instrument.

Return type

None

class opentelemetry.metrics.Observer[source]¶

Bases: abc.ABC

An observer type metric instrument used to capture a current set of values.

Observer instruments are asynchronous, a callback is invoked with the observer instrument as argument allowing the user to capture multiple values per collection interval.

abstract observe(value, labels)[source]¶

Captures value to the observer.

Parameters

value (~ValueT) – The value to capture to this observer metric.
labels (Dict[str, str]) – Labels associated to value.

Return type

None

class opentelemetry.metrics.DefaultObserver[source]¶

Bases: opentelemetry.metrics.Observer

No-op implementation of Observer.

observe(value, labels)[source]¶

Captures value to the observer.

Parameters

value (~ValueT) – The value to capture to this observer metric.
labels (Dict[str, str]) – Labels associated to value.

Return type

None

class opentelemetry.metrics.MeterProvider[source]¶

Bases: abc.ABC

abstract get_meter(instrumenting_module_name, stateful=True, instrumenting_library_version='')[source]¶

Returns a Meter for use by the given instrumentation library.

This function may return different Meter types (e.g. a no-op meter vs. a functional meter).

Parameters

instrumenting_module_name (str) –
The name of the instrumenting module (usually just __name__).

This should not be the name of the module that is instrumented but the name of the module doing the instrumentation. E.g., instead of "requests", use "opentelemetry.ext.http_requests".
stateful (bool) – True/False to indicate whether the meter will be stateful. True indicates the meter computes checkpoints from over the process lifetime. False indicates the meter computes checkpoints which describe the updates of a single collection period (deltas).
instrumenting_library_version (str) – Optional. The version string of the instrumenting library. Usually this should be the same as pkg_resources.get_distribution(instrumenting_library_name).version.

Return type

Meter

class opentelemetry.metrics.DefaultMeterProvider[source]¶

Bases: opentelemetry.metrics.MeterProvider

The default MeterProvider, used when no implementation is available.

All operations are no-op.

get_meter(instrumenting_module_name, stateful=True, instrumenting_library_version='')[source]¶

Returns a Meter for use by the given instrumentation library.

This function may return different Meter types (e.g. a no-op meter vs. a functional meter).

Parameters

instrumenting_module_name (str) –
The name of the instrumenting module (usually just __name__).

This should not be the name of the module that is instrumented but the name of the module doing the instrumentation. E.g., instead of "requests", use "opentelemetry.ext.http_requests".
stateful (bool) – True/False to indicate whether the meter will be stateful. True indicates the meter computes checkpoints from over the process lifetime. False indicates the meter computes checkpoints which describe the updates of a single collection period (deltas).
instrumenting_library_version (str) – Optional. The version string of the instrumenting library. Usually this should be the same as pkg_resources.get_distribution(instrumenting_library_name).version.

Return type

Meter

class opentelemetry.metrics.Meter[source]¶

Bases: abc.ABC

An interface to allow the recording of metrics.

Metric s are used for recording pre-defined aggregation (counter), or raw values (measure) in which the aggregation and labels for the exported metric are deferred.

abstract record_batch(labels, record_tuples)[source]¶

Atomically records a batch of Metric and value pairs.

Allows the functionality of acting upon multiple metrics with a single API call. Implementations should find bound metric instruments that match the key-value pairs in the labels.

Parameters

labels (Dict[str, str]) – Labels associated with all measurements in the batch.
record_tuples (Sequence[Tuple[Metric, ~ValueT]]) – A sequence of pairs of Metric s and the corresponding value to record for that metric.

Return type

None

abstract create_metric(name, description, unit, value_type, metric_type, label_keys=(), enabled=True)[source]¶

Creates a metric_kind metric with type value_type.

Parameters

name (str) – The name of the metric.
description (str) – Human-readable description of the metric.
unit (str) – Unit of the metric values following the UCUM convention (https://unitsofmeasure.org/ucum.html).
value_type (Type[~ValueT]) – The type of values being recorded by the metric.
metric_type (Type[~MetricT]) – The type of metric being created.
label_keys (Sequence[str]) – The keys for the labels with dynamic values.
enabled (bool) – Whether to report the metric by default.

Returns: A new metric_type metric with values of value_type.

Return type: Metric

abstract register_observer(callback, name, description, unit, value_type, label_keys=(), enabled=True)[source]¶

Registers an Observer metric instrument.

Parameters

callback (Callable[[Observer], None]) – Callback invoked each collection interval with the observer as argument.
name (str) – The name of the metric.
description (str) – Human-readable description of the metric.
unit (str) – Unit of the metric values following the UCUM convention (https://unitsofmeasure.org/ucum.html).
value_type (Type[~ValueT]) – The type of values being recorded by the metric.
label_keys (Sequence[str]) – The keys for the labels with dynamic values.
enabled (bool) – Whether to report the metric by default.

Returns: A new Observer metric instrument.

Return type: Observer

abstract unregister_observer(observer)[source]¶

Unregisters an Observer metric instrument.

Parameters: observer (Observer) – The observer to unregister.
Return type: None

class opentelemetry.metrics.DefaultMeter[source]¶

Bases: opentelemetry.metrics.Meter

The default Meter used when no Meter implementation is available.

record_batch(labels, record_tuples)[source]¶

Atomically records a batch of Metric and value pairs.

Allows the functionality of acting upon multiple metrics with a single API call. Implementations should find bound metric instruments that match the key-value pairs in the labels.

Parameters

labels (Dict[str, str]) – Labels associated with all measurements in the batch.
record_tuples (Sequence[Tuple[Metric, ~ValueT]]) – A sequence of pairs of Metric s and the corresponding value to record for that metric.

Return type

None

create_metric(name, description, unit, value_type, metric_type, label_keys=(), enabled=True)[source]¶

Creates a metric_kind metric with type value_type.

Parameters

name (str) – The name of the metric.
description (str) – Human-readable description of the metric.
unit (str) – Unit of the metric values following the UCUM convention (https://unitsofmeasure.org/ucum.html).
value_type (Type[~ValueT]) – The type of values being recorded by the metric.
metric_type (Type[~MetricT]) – The type of metric being created.
label_keys (Sequence[str]) – The keys for the labels with dynamic values.
enabled (bool) – Whether to report the metric by default.

Returns: A new metric_type metric with values of value_type.

Return type: Metric

register_observer(callback, name, description, unit, value_type, label_keys=(), enabled=True)[source]¶

Registers an Observer metric instrument.

Parameters

callback (Callable[[Observer], None]) – Callback invoked each collection interval with the observer as argument.
name (str) – The name of the metric.
description (str) – Human-readable description of the metric.
unit (str) – Unit of the metric values following the UCUM convention (https://unitsofmeasure.org/ucum.html).
value_type (Type[~ValueT]) – The type of values being recorded by the metric.
label_keys (Sequence[str]) – The keys for the labels with dynamic values.
enabled (bool) – Whether to report the metric by default.

Returns: A new Observer metric instrument.

Return type: Observer

unregister_observer(observer)[source]¶

Unregisters an Observer metric instrument.

Parameters: observer (Observer) – The observer to unregister.
Return type: None

opentelemetry.metrics.get_meter(instrumenting_module_name, stateful=True, instrumenting_library_version='')[source]¶

Returns a Meter for use by the given instrumentation library. This function is a convenience wrapper for opentelemetry.metrics.get_meter_provider().get_meter

Return type: Meter

opentelemetry.metrics.set_meter_provider(meter_provider)[source]¶

Sets the current global MeterProvider object.

Return type: None

opentelemetry.metrics.get_meter_provider()[source]¶

Gets the current global MeterProvider object.

Return type: MeterProvider