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 Pythonopen in new window.

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:

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:

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 examplesopen in new window at GitHub.

Counter

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

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.

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.

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.

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.

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.

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 alternativeopen in new window that supports distributed tracing, metrics, and logs. You can use it to monitor applications and troubleshoot issues.

Uptrace Overview

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 demoopen in new window (no login required) or running it locally with Dockeropen in new window. The source code is available on GitHubopen in new window.

What's next?

Last Updated: