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:
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 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?
