OpenTelemetry Python Metrics approaching General Availability

The OpenTelemetry project has been making a ton of progress towards stabilizing the support for its second signal: metrics. Stability for the tracing signal was declareddeclared in February of 2021. Since then, the community has invested significantly in supporting metrics and logging. As the specification started to solidify around the metric signal, various languages have released experimental packages to allow users to start producing metrics. In March 2022, the OpenTelemetry Python Special Interest Group (SIG) released experimental support for the metrics signal in the 1.10.0 releaserelease.

\

What does "experimental" mean?

You can generate metrics using the 1.10.0 version of the opentelemetry-api opentelemetry-api and opentelemetry-sdkopentelemetry-sdk packages TODAY. ExperimentalExperimental means that the API or SDK are still subject to changes. At this point there are no planned changes, but the community is gathering feedback before marking it stable. The Python SIG placed all of the metrics API and SDK components in modules prefixed with an underscore (_metrics). The plan is to remove that underscore once stability is achieved. The experimental release comes with exporters that support emitting metrics to:

• backends that support the OpenTelemetry protocol (OTLP)

• Prometheus

• the console

This allows users to produce metrics that can be scraped by existing Prometheus deployments or send data to the OpenTelemetry Collector.

\

OK! I want in, how does it work?

The OpenTelemetry metrics implementation consists of two components. The metrics pipeline, which configures where and how metrics are emitted and the instruments used to record measurements.

The following code sets up a metrics pipeline to periodically export metrics using the console metrics exporter:

from typing import Iterable

\

from opentelemetry._metrics import get_meter_provider, set_meter_provider
from opentelemetry._metrics.measurement import Measurement
from opentelemetry.sdk._metrics import MeterProvider
from opentelemetry.sdk._metrics.export import (
    ConsoleMetricExporter,
    PeriodicExportingMetricReader,
)

exporter = ConsoleMetricExporter()
reader = PeriodicExportingMetricReader(exporter)
provider = MeterProvider(metric_readers=[reader])
set_meter_provider(provider)

\

Then instruments can be created and measurements recorded. Each instrument can be used to record different things. To get more familiar with the instruments supported by OpenTelemetry, check out the specificationspecification.

The following shows how each instrument can be used in OpenTelemetry Python:

def observable_counter_func() -> Iterable[Measurement]:
    yield Measurement(1, {})

def observable_up_down_counter_func() -> Iterable[Measurement]:
    yield Measurement(-10, {})

def observable_gauge_func() -> Iterable[Measurement]:
    yield Measurement(9, {})

meter = get_meter_provider().get_meter("getting-started", "0.1.2")

# Counter
counter = meter.create_counter("counter")
counter.add(1)

# Async Counter
observable_counter = meter.create_observable_counter(
    "observable_counter", observable_counter_func
)

# UpDownCounter
updown_counter = meter.create_up_down_counter("updown_counter")
updown_counter.add(1)
updown_counter.add(-5)

# Async UpDownCounter
observable_updown_counter = meter.create_observable_up_down_counter(
    "observable_updown_counter", observable_up_down_counter_func
)

# Histogram
histogram = meter.create_histogram("histogram")
histogram.record(99.9)

# Async Gauge
gauge = meter.create_observable_gauge("gauge", observable_gauge_func)

\

How can you help?

We'd love to hear from users about any bugs or challenges they come across before releasing the API and SDK packages as stable. A list of known issues that are still actively being addressed or need help is available on our SIG's project boardproject board. We intend to mark the metrics API and SDK stable in the next release or two. The current version includes all the components necessary to produce metrics. Some of the features not implemented yet are exemplars and support for exponential histograms. The rest is all there, give it a spin!