opentelemetry.sdk.metrics package — OpenTelemetry Python documentation (original) (raw)

Submodules

class opentelemetry.sdk.metrics.AlignedHistogramBucketExemplarReservoir(boundaries, **kwargs)[source]

Bases: FixedSizeExemplarReservoirABC

This Exemplar reservoir takes a configuration parameter that is the configuration of a Histogram. This implementation keeps the last seen measurement that falls within a histogram bucket.

Reference:

https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#alignedhistogrambucketexemplarreservoir

offer(value, time_unix_nano, attributes, context)[source]

Offers a measurement to be sampled.

Return type:

None

class opentelemetry.sdk.metrics.AlwaysOnExemplarFilter[source]

Bases: ExemplarFilter

An ExemplarFilter which makes all measurements eligible for being an Exemplar.

Reference:

https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#alwayson

should_sample(value, time_unix_nano, attributes, context)[source]

Returns whether or not a reservoir should attempt to filter a measurement.

Parameters:

Return type:

bool

class opentelemetry.sdk.metrics.AlwaysOffExemplarFilter[source]

Bases: ExemplarFilter

An ExemplarFilter which makes no measurements eligible for being an Exemplar.

Using this ExemplarFilter is as good as disabling Exemplar feature.

Reference:

https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#alwaysoff

should_sample(value, time_unix_nano, attributes, context)[source]

Returns whether or not a reservoir should attempt to filter a measurement.

Parameters:

Return type:

bool

class opentelemetry.sdk.metrics.Exemplar(filtered_attributes, value, time_unix_nano, span_id=None, trace_id=None)[source]

Bases: object

A representation of an exemplar, which is a sample input measurement.

Exemplars also hold information about the environment when the measurement was recorded, for example the span and trace ID of the active span when the exemplar was recorded.

Attributes

trace_id: (optional) The trace associated with a recording span_id: (optional) The span associated with a recording time_unix_nano: The time of the observation value: The recorded value filtered_attributes: A set of filtered attributes which provide additional insight into the Context when the observation was made.

References

https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/data-model.md#exemplars https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#exemplar

filtered_attributes_: Optional[Mapping[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]_

value_: Union[int, float]_

time_unix_nano_: int_

span_id_: Optional[int]_ = None

trace_id_: Optional[int]_ = None

class opentelemetry.sdk.metrics.ExemplarFilter[source]

Bases: ABC

ExemplarFilter determines which measurements are eligible for becoming anExemplar.

Exemplar filters are used to filter measurements before attempting to store them in a reservoir.

Reference:

https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#exemplarfilter

abstract should_sample(value, time_unix_nano, attributes, context)[source]

Returns whether or not a reservoir should attempt to filter a measurement.

Parameters:

Return type:

bool

class opentelemetry.sdk.metrics.ExemplarReservoir[source]

Bases: ABC

ExemplarReservoir provide a method to offer measurements to the reservoir and another to collect accumulated Exemplars.

Note

The constructor MUST accept **kwargs that may be set from aggregation parameters.

Reference:

https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#exemplarreservoir

abstract offer(value, time_unix_nano, attributes, context)[source]

Offers a measurement to be sampled.

Parameters:

Return type:

None

abstract collect(point_attributes)[source]

Returns accumulated Exemplars and also resets the reservoir for the next sampling period

Parameters:

point_attributes (Optional[Mapping[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]) – The attributes associated with metric point.

Return type:

List[Exemplar]

Returns:

a list of opentelemetry.sdk.metrics._internal.exemplar.exemplar.Exemplar s. Returned exemplars contain the attributes that were filtered out by the aggregator, but recorded alongside the original measurement.

class opentelemetry.sdk.metrics.Meter(instrumentation_scope, measurement_consumer)[source]

Bases: Meter

See opentelemetry.metrics.Meter.

create_counter(name, unit='', description='')[source]

Creates a Counter instrument

Parameters:

Return type:

Counter

create_up_down_counter(name, unit='', description='')[source]

Creates an UpDownCounter instrument

Parameters:

Return type:

UpDownCounter

create_observable_counter(name, callbacks=None, unit='', description='')[source]

Creates an ObservableCounter instrument

An observable counter observes a monotonically increasing count by calling provided callbacks which accept a CallbackOptions and return multiple Observation.

For example, an observable counter could be used to report system CPU time periodically. Here is a basic implementation:

def cpu_time_callback(options: CallbackOptions) -> Iterable[Observation]: observations = [] with open("/proc/stat") as procstat: procstat.readline() # skip the first line for line in procstat: if not line.startswith("cpu"): break cpu, *states = line.split() observations.append(Observation(int(states[0]) // 100, {"cpu": cpu, "state": "user"})) observations.append(Observation(int(states[1]) // 100, {"cpu": cpu, "state": "nice"})) observations.append(Observation(int(states[2]) // 100, {"cpu": cpu, "state": "system"})) # ... other states return observations

meter.create_observable_counter( "system.cpu.time", callbacks=[cpu_time_callback], unit="s", description="CPU time" )

To reduce memory usage, you can use generator callbacks instead of building the full list:

def cpu_time_callback(options: CallbackOptions) -> Iterable[Observation]: with open("/proc/stat") as procstat: procstat.readline() # skip the first line for line in procstat: if not line.startswith("cpu"): break cpu, *states = line.split() yield Observation(int(states[0]) // 100, {"cpu": cpu, "state": "user"}) yield Observation(int(states[1]) // 100, {"cpu": cpu, "state": "nice"}) # ... other states

Alternatively, you can pass a sequence of generators directly instead of a sequence of callbacks, which each should return iterables of Observation:

def cpu_time_callback(states_to_include: set[str]) -> Iterable[Iterable[Observation]]: # accept options sent in from OpenTelemetry options = yield while True: observations = [] with open("/proc/stat") as procstat: procstat.readline() # skip the first line for line in procstat: if not line.startswith("cpu"): break cpu, *states = line.split() if "user" in states_to_include: observations.append(Observation(int(states[0]) // 100, {"cpu": cpu, "state": "user"})) if "nice" in states_to_include: observations.append(Observation(int(states[1]) // 100, {"cpu": cpu, "state": "nice"})) # ... other states # yield the observations and receive the options for next iteration options = yield observations

meter.create_observable_counter( "system.cpu.time", callbacks=[cpu_time_callback({"user", "system"})], unit="s", description="CPU time" )

The CallbackOptions contain a timeout which the callback should respect. For example if the callback does asynchronous work, like making HTTP requests, it should respect the timeout:

def scrape_http_callback(options: CallbackOptions) -> Iterable[Observation]: r = requests.get('http://scrapethis.com', timeout=options.timeout_millis / 10**3) for value in r.json(): yield Observation(value)

Parameters:

Return type:

ObservableCounter

create_histogram(name, unit='', description='', *, explicit_bucket_boundaries_advisory=None)[source]

Creates a Histogram instrument

Parameters:

Return type:

Histogram

create_gauge(name, unit='', description='')[source]

Creates a Gauge instrument

Parameters:

Return type:

Gauge

create_observable_gauge(name, callbacks=None, unit='', description='')[source]

Creates an ObservableGauge instrument

Parameters:

Return type:

ObservableGauge

create_observable_up_down_counter(name, callbacks=None, unit='', description='')[source]

Creates an ObservableUpDownCounter instrument

Parameters:

Return type:

ObservableUpDownCounter

class opentelemetry.sdk.metrics.MeterProvider(metric_readers=(), resource=None, exemplar_filter=None, shutdown_on_exit=True, views=())[source]

Bases: MeterProvider

See opentelemetry.metrics.MeterProvider.

Parameters:

By default, instruments which do not match any opentelemetry.sdk.metrics.view.View (or if no opentelemetry.sdk.metrics.view.Views are provided) will report metrics with the default aggregation for the instrument’s kind. To disable instruments by default, configure a match-allopentelemetry.sdk.metrics.view.View with DropAggregation and then create opentelemetry.sdk.metrics.view.Views to re-enable individual instruments:

Disable default views

MeterProvider( views=[ View(instrument_name="*", aggregation=DropAggregation()), View(instrument_name="mycounter"), ], # ... )

force_flush(timeout_millis=10000)[source]

Return type:

bool

shutdown(timeout_millis=30000)[source]

get_meter(name, version=None, schema_url=None, attributes=None)[source]

Returns a Meter for use by the given instrumentation library.

For any two calls it is undefined whether the same or differentMeter instances are returned, even for different library names.

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

Parameters:

Return type:

Meter

exception opentelemetry.sdk.metrics.MetricsTimeoutError[source]

Bases: Exception

Raised when a metrics function times out

class opentelemetry.sdk.metrics.Counter(name, instrumentation_scope, measurement_consumer, unit='', description='')[source]

Bases: _Synchronous, Counter

add(amount, attributes=None, context=None)[source]

class opentelemetry.sdk.metrics.Histogram(name, instrumentation_scope, measurement_consumer, unit='', description='', explicit_bucket_boundaries_advisory=None)[source]

Bases: _Synchronous, Histogram

record(amount, attributes=None, context=None)[source]

class opentelemetry.sdk.metrics.ObservableCounter(name, instrumentation_scope, measurement_consumer, callbacks=None, unit='', description='')[source]

Bases: _Asynchronous, ObservableCounter

class opentelemetry.sdk.metrics.ObservableGauge(name, instrumentation_scope, measurement_consumer, callbacks=None, unit='', description='')[source]

Bases: _Asynchronous, ObservableGauge

class opentelemetry.sdk.metrics.ObservableUpDownCounter(name, instrumentation_scope, measurement_consumer, callbacks=None, unit='', description='')[source]

Bases: _Asynchronous, ObservableUpDownCounter

class opentelemetry.sdk.metrics.SimpleFixedSizeExemplarReservoir(size=1, **kwargs)[source]

Bases: FixedSizeExemplarReservoirABC

This reservoir uses an uniformly-weighted sampling algorithm based on the number of samples the reservoir has seen so far to determine if the offered measurements should be sampled.

Reference:

https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#simplefixedsizeexemplarreservoir

class opentelemetry.sdk.metrics.UpDownCounter(name, instrumentation_scope, measurement_consumer, unit='', description='')[source]

Bases: _Synchronous, UpDownCounter

add(amount, attributes=None, context=None)[source]

class opentelemetry.sdk.metrics.TraceBasedExemplarFilter[source]

Bases: ExemplarFilter

An ExemplarFilter which makes those measurements eligible for being an Exemplar, which are recorded in the context of a sampled parent span.

Reference:

https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#tracebased

should_sample(value, time_unix_nano, attributes, context)[source]

Returns whether or not a reservoir should attempt to filter a measurement.

Parameters:

Return type:

bool