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.

Meter s can be obtained via the MeterProvider, corresponding to the name of the instrumenting library and (optionally) a version.

See the metrics api spec for terminology and context clarification.

class opentelemetry.metrics.BoundCounter[source]¶

Bases: abc.ABC

abstract add(value)[source]¶

Increases the value of the bound counter by value.

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

class opentelemetry.metrics.DefaultBoundCounter[source]¶

Bases: opentelemetry.metrics.BoundCounter

The default bound counter instrument.

Used when no bound counter implementation is available.

add(value)[source]¶

Increases the value of the bound counter by value.

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

class opentelemetry.metrics.BoundUpDownCounter[source]¶

Bases: abc.ABC

abstract add(value)[source]¶

Increases the value of the bound updowncounter by value.

Parameters: value (~ValueT) – The value to add to the bound updowncounter. Can be positive or negative.
Return type: None

class opentelemetry.metrics.DefaultBoundUpDownCounter[source]¶

Bases: opentelemetry.metrics.BoundUpDownCounter

The default bound updowncounter instrument.

Used when no bound updowncounter implementation is available.

add(value)[source]¶

Increases the value of the bound updowncounter by value.

Parameters: value (~ValueT) – The value to add to the bound updowncounter. Can be positive or negative.
Return type: None

class opentelemetry.metrics.BoundValueRecorder[source]¶

Bases: abc.ABC

abstract record(value)[source]¶

Records the given value to this bound valuerecorder.

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

class opentelemetry.metrics.DefaultBoundValueRecorder[source]¶

Bases: opentelemetry.metrics.BoundValueRecorder

The default bound valuerecorder instrument.

Used when no bound valuerecorder implementation is available.

record(value)[source]¶

Records the given value to this bound valuerecorder.

Parameters: value (~ValueT) – The value to record to the bound valuerecorder.
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.

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

class opentelemetry.metrics.Counter[source]¶

Bases: opentelemetry.metrics.Metric

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

abstract add(value, labels)[source]¶

Increases the value of the counter by value.

Parameters

value (~ValueT) – The value to add to the counter metric. Should be positive or zero. For a Counter that can decrease, use UpDownCounter.
labels (Dict[str, str]) – Labels to associate with the bound instrument.

Return type

None

class opentelemetry.metrics.DefaultCounter[source]¶

Bases: opentelemetry.metrics.Counter

The default counter instrument.

Used when no Counter implementation is available.

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.

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

add(value, labels)[source]¶

Increases the value of the counter by value.

Parameters

value (~ValueT) – The value to add to the counter metric. Should be positive or zero. For a Counter that can decrease, use UpDownCounter.
labels (Dict[str, str]) – Labels to associate with the bound instrument.

Return type

None

class opentelemetry.metrics.UpDownCounter[source]¶

Bases: opentelemetry.metrics.Metric

A counter type metric that expresses the computation of a sum, allowing negative increments.

abstract add(value, labels)[source]¶

Increases the value of the counter by value.

Parameters

value (~ValueT) – The value to add to the counter metric. Can be positive or negative. For a Counter that is never decreasing, use Counter.
labels (Dict[str, str]) – Labels to associate with the bound instrument.

Return type

None

class opentelemetry.metrics.DefaultUpDownCounter[source]¶

Bases: opentelemetry.metrics.UpDownCounter

The default updowncounter instrument.

Used when no UpDownCounter implementation is available.

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.

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

add(value, labels)[source]¶

Increases the value of the counter by value.

Parameters

value (~ValueT) – The value to add to the counter metric. Can be positive or negative. For a Counter that is never decreasing, use Counter.
labels (Dict[str, str]) – Labels to associate with the bound instrument.

Return type

None

class opentelemetry.metrics.ValueRecorder[source]¶

Bases: opentelemetry.metrics.Metric

A valuerecorder type metric that represent raw stats.

abstract record(value, labels)[source]¶

Records the value to the valuerecorder.

Parameters

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

Return type

None

class opentelemetry.metrics.DefaultValueRecorder[source]¶

Bases: opentelemetry.metrics.ValueRecorder

The default valuerecorder instrument.

Used when no ValueRecorder implementation is available.

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.

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

record(value, labels)[source]¶

Records the value to the valuerecorder.

Parameters

value (~ValueT) – The value to record to this valuerecorder 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.SumObserver[source]¶

Bases: opentelemetry.metrics.Observer

Asynchronous instrument used to capture a monotonic sum.

class opentelemetry.metrics.DefaultSumObserver[source]¶

Bases: opentelemetry.metrics.SumObserver

No-op implementation of SumObserver.

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.UpDownSumObserver[source]¶

Bases: opentelemetry.metrics.Observer

Asynchronous instrument used to capture a non-monotonic count.

class opentelemetry.metrics.DefaultUpDownSumObserver[source]¶

Bases: opentelemetry.metrics.UpDownSumObserver

No-op implementation of UpDownSumObserver.

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.ValueObserver[source]¶

Bases: opentelemetry.metrics.Observer

Asynchronous instrument used to capture grouping measurements.

class opentelemetry.metrics.DefaultValueObserver[source]¶

Bases: opentelemetry.metrics.ValueObserver

No-op implementation of ValueObserver.

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, 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.instrumentation.requests".
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, 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.instrumentation.requests".
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 or metric instruments, are devices used for capturing raw measurements. Each metric instrument supports a single method, each with fixed interpretation to capture measurements.

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_counter(name, description, unit, value_type, enabled=True)[source]¶

Creates a Counter 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.
enabled (bool) – Whether to report the metric by default.

Return type

Counter

abstract create_updowncounter(name, description, unit, value_type, enabled=True)[source]¶

Creates a UpDownCounter 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.
enabled (bool) – Whether to report the metric by default.

Return type

UpDownCounter

abstract create_valuerecorder(name, description, unit, value_type, enabled=True)[source]¶

Creates a ValueRecorder 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.
enabled (bool) – Whether to report the metric by default.

Return type

ValueRecorder

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

Registers an SumObserver 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 SumObserver metric instrument.

Return type: SumObserver

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

Registers an UpDownSumObserver 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 UpDownSumObserver metric instrument.

Return type: UpDownSumObserver

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

Registers an ValueObserver 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 ValueObserver metric instrument.

Return type: ValueObserver

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_counter(name, description, unit, value_type, enabled=True)[source]¶

Creates a Counter 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.
enabled (bool) – Whether to report the metric by default.

Return type

Counter

create_updowncounter(name, description, unit, value_type, enabled=True)[source]¶

Creates a UpDownCounter 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.
enabled (bool) – Whether to report the metric by default.

Return type

UpDownCounter

create_valuerecorder(name, description, unit, value_type, enabled=True)[source]¶

Creates a ValueRecorder 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.
enabled (bool) – Whether to report the metric by default.

Return type

ValueRecorder

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

Registers an SumObserver 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 SumObserver metric instrument.

Return type: DefaultSumObserver

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

Registers an UpDownSumObserver 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 UpDownSumObserver metric instrument.

Return type: DefaultUpDownSumObserver

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

Registers an ValueObserver 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 ValueObserver metric instrument.

Return type: DefaultValueObserver

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, instrumenting_library_version='', meter_provider=None)[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

If meter_provider is omitted the current configured one is used.

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