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 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 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 examples 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 APM for OpenTelemetry with an intuitive query builder, rich dashboards, automatic alerts, and integrations for most languages and frameworks.
You can get started with Uptrace by downloading a DEB/RPM package or a pre-compiled Go binary.
What's next?
