HomeInstrumentationsSemantic attrsUptrace DemoGitHub

OpenTelemetry Metrics API for Python

Introduction

This document teaches how to use OpenTelemetry Metrics Python 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 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"
    )

UpDownCounterOserver

UpDownCounterOserver 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 an open source APMopen in new window for OpenTelemetry with an intuitive query builder, rich dashboards, automatic alerts, and integrations for most languages and frameworks.

You can get startedopen in new window with Uptrace by downloading a DEB/RPM package or a pre-compiled Go binary.

What's next?

Next, you can installopen in new window OpenTelemetry Collector to monitor infrastructure metrics, for example, PostgreSQLopen in new window, MySQLopen in new window, Kafkaopen in new window, and more.

Popular instrumentations:

Last Updated: