OpenTelemetry Metrics API for Python

This document teaches how to use OpenTelemetry Python Metrics API. To learn how to install and configure OpenTelemetry Python SDK, see Getting started with OpenTelemetry Python.

If you are not familiar with metrics terminology like timeseries or additive/synchronous/asynchronous instruments, read the introduction to OpenTelemetry Metrics first.

Getting started

To get started with metrics, you need to create a meter:

python

from opentelemetry import metrics

meter = metrics.get_meter("app_or_package_name")

Using the meter, you can create instruments to measure performance. The simplest Counter instrument looks like this:

python

counter = meter.create_counter(
    name="first_counter", description="TODO", unit="1",
)

counter.add(1, attributes={"foo": "bar"})
counter.add(10, attributes={"hello": "world"})

You can find more examples at GitHub.

Counter

Counter is a synchronous instrument that measures additive non-decreasing values.

python

def counter():
    counter = meter.create_counter(name="some.prefix.counter", description="TODO")

    while True:
        counter.add(1)
        time.sleep(1)

UpDownCounter

UpDownCounter is a synchronous instrument which measures additive values that increase or decrease with time.

python

def up_down_counter():
    counter = meter.create_up_down_counter(
        name="some.prefix.up_down_counter", description="TODO"
    )

    while True:
        if random.random() >= 0.5:
            counter.add(+1)
        else:
            counter.add(-1)
        time.sleep(1)

Histogram

Histogram is a synchronous instrument that produces a histogram from recorded values.

python

def histogram():
    histogram = meter.create_histogram(
        name="some.prefix.histogram",
        description="TODO",
        unit="microseconds",
    )

    while True:
        histogram.record(random.randint(1, 5000000), attributes={"attr1": "value1"})
        time.sleep(1)

CounterObserver

CounterObserver is an asynchronous instrument that measures additive non-decreasing values.

python

def counter_observer():
    number = 0

    def callback():
        nonlocal number
        number += 1
        return [Measurement(int(number))]

    counter = meter.create_observable_counter(
        name="some.prefix.counter_observer", callback=callback, description="TODO"
    )

UpDownCounterObserver

UpDownCounterObserver is an asynchronous instrument that measures additive values that can increase or decrease with time.

python

def up_down_counter_observer():
    def callback():
        return [Measurement(random.random())]

    counter = meter.create_observable_up_down_counter(
        name="some.prefix.up_down_counter_observer",
        callback=callback,
        description="TODO",
    )

GaugeObserver

GaugeObserver is an asynchronous instrument that measures non-additive values for which sum does not produce a meaningful correct result.

python

def gauge_observer():
    def callback():
        return [Measurement(random.random())]

    gauge = meter.create_observable_gauge(
        name="some.prefix.gauge_observer",
        callback=callback,
        description="TODO",
    )

Uptrace

Uptrace is a DataDog alternative that supports distributed tracing, metrics, and logs. You can use it to monitor applications and troubleshoot issues.

Uptrace comes with an intuitive query builder, rich dashboards, alerting rules with notifications, and integrations for most languages and frameworks.

Uptrace can process billions of spans and metrics on a single server and allows you to monitor your applications at 10x lower cost.

In just a few minutes, you can try Uptrace by visiting the cloud demo (no login required) or running it locally with Docker. The source code is available on GitHub.

What's next?

Tracing API

Get started