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.

class opentelemetry.metrics.DefaultMetricHandle[source]¶

Bases: object

The default MetricHandle.

Used when no MetricHandle implementation is available.

add(value)[source]¶

No-op implementation of CounterHandle add.

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

set(value)[source]¶

No-op implementation of GaugeHandle set.

Parameters: value (~ValueT) – The value to set to the handle.
Return type: None

record(value)[source]¶

No-op implementation of MeasureHandle record.

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

class opentelemetry.metrics.CounterHandle[source]¶

Bases: object

add(value)[source]¶

Increases the value of the handle by value.

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

class opentelemetry.metrics.GaugeHandle[source]¶

Bases: object

set(value)[source]¶

Sets the current value of the handle to value.

Parameters: value (~ValueT) – The value to set to the handle.
Return type: None

class opentelemetry.metrics.MeasureHandle[source]¶

Bases: object

record(value)[source]¶

Records the given value to this handle.

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

class opentelemetry.metrics.LabelSet[source]¶

Bases: abc.ABC

A canonicalized set of labels useful for preaggregation

Re-usable LabelSet objects provide a potential optimization for scenarios where handles might not be effective. For example, if the LabelSet will be re-used but only used once per metrics, handles do not offer any optimization. It may best to pre-compute a canonicalized LabelSet once and re-use it with the direct calling convention. LabelSets are immutable and should be opaque in implementation.

class opentelemetry.metrics.DefaultLabelSet[source]¶

Bases: opentelemetry.metrics.LabelSet

The default LabelSet.

Used when no LabelSet implementation is available.

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 handle that the metric holds.

abstract get_handle(label_set)[source]¶

Gets a handle, used for repeated-use of metrics instruments.

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

Parameters: label_set (LabelSet) – LabelSet to associate with the returned handle.
Return type: object

class opentelemetry.metrics.DefaultMetric[source]¶

Bases: opentelemetry.metrics.Metric

The default Metric used when no Metric implementation is available.

get_handle(label_set)[source]¶

Gets a DefaultMetricHandle.

Parameters: label_set (LabelSet) – LabelSet to associate with the returned handle.
Return type: DefaultMetricHandle

add(value, label_set)[source]¶

No-op implementation of Counter add.

Parameters

value (~ValueT) – The value to add to the counter metric.
label_set (LabelSet) – LabelSet to associate with the returned handle.

Return type

None

set(value, label_set)[source]¶

No-op implementation of Gauge set.

Parameters

value (~ValueT) – The value to set the gauge metric to.
label_set (LabelSet) – LabelSet to associate with the returned handle.

Return type

None

record(value, label_set)[source]¶

No-op implementation of Measure record.

Parameters

value (~ValueT) – The value to record to this measure metric.
label_set (LabelSet) – LabelSet to associate with the returned handle.

Return type

None

class opentelemetry.metrics.Counter[source]¶

Bases: opentelemetry.metrics.Metric

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

get_handle(label_set)[source]¶

Gets a CounterHandle.

Return type: CounterHandle

add(value, label_set)[source]¶

Increases the value of the counter by value.

Parameters

value (~ValueT) – The value to add to the counter metric.
label_set (LabelSet) – LabelSet to associate with the returned handle.

Return type

None

class opentelemetry.metrics.Gauge[source]¶

Bases: opentelemetry.metrics.Metric

A gauge type metric that expresses a pre-calculated value.

Gauge metrics have a value that is either Set by explicit instrumentation or observed through a callback. This kind of metric should be used when the metric cannot be expressed as a sum or because the measurement interval is arbitrary.

get_handle(label_set)[source]¶

Gets a GaugeHandle.

Return type: GaugeHandle

set(value, label_set)[source]¶

Sets the value of the gauge to value.

Parameters

value (~ValueT) – The value to set the gauge metric to.
label_set (LabelSet) – LabelSet to associate with the returned handle.

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.

get_handle(label_set)[source]¶

Gets a MeasureHandle with a float value.

Return type: MeasureHandle

record(value, label_set)[source]¶

Records the value to the measure.

Parameters

value (~ValueT) – The value to record to this measure metric.
label_set (LabelSet) – LabelSet to associate with the returned handle.

Return type

None

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 (gauge and counter), or raw values (measure) in which the aggregation and labels for the exported metric are deferred.

abstract record_batch(label_set, 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 metric and handles that match the key-value pairs in the label tuples.

Parameters

label_set (LabelSet) – The LabelSet associated with all measurements in the batch. A measurement is a tuple, representing the Metric being recorded and the corresponding value to record.
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.
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 get_label_set(labels)[source]¶

Gets a LabelSet with the given labels.

Parameters: labels (Dict[str, str]) – A dictionary representing label key to label value pairs.

Returns: A LabelSet object canonicalized using the given input.

Return type: LabelSet

class opentelemetry.metrics.DefaultMeter[source]¶

Bases: opentelemetry.metrics.Meter

The default Meter used when no Meter implementation is available.

record_batch(label_set, 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 metric and handles that match the key-value pairs in the label tuples.

Parameters

label_set (LabelSet) – The LabelSet associated with all measurements in the batch. A measurement is a tuple, representing the Metric being recorded and the corresponding value to record.
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.
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

get_label_set(labels)[source]¶

Gets a LabelSet with the given labels.

Parameters: labels (Dict[str, str]) – A dictionary representing label key to label value pairs.

Returns: A LabelSet object canonicalized using the given input.

Return type: LabelSet

opentelemetry.metrics.meter()[source]¶

Gets the current global Meter object.

If there isn’t one set yet, a default will be loaded.

Return type: Meter

opentelemetry.metrics.set_preferred_meter_implementation(factory)[source]¶

Set the factory to be used to create the meter.

See opentelemetry.util.loader for details.

This function may not be called after a meter is already loaded.

Parameters: factory (Callable[[Type[Meter]], Optional[Meter]]) – Callback that should create a new Meter instance.
Return type: None