aioprometheus is a Prometheus Python client library for asyncio-based applications.

It provides asyncio based applications with a metrics collection and serving capability for use with the Prometheus monitoring and alerting system.

It supports text and binary data formats as well as the ability to push metrics to a gateway.

The project source code can be found here.


The example below shows a single Counter metric collector being created and exposed via a HTTP endpoint.

#!/usr/bin/env python
This example demonstrates how aioprometheus can be used to expose metrics on
a HTTP endpoint that is provided by the aioprometheus.Service object.

.. code-block:: console

    (env) $ python
    Serving prometheus metrics on:

In another terminal fetch the metrics using the ``curl`` command line tool
to verify they can be retrieved by Prometheus server.

import asyncio
import socket
from aioprometheus import Counter, Service

if __name__ == "__main__":

    async def main(svr: Service) -> None:

        events_counter = Counter(
            "events", "Number of events.", const_labels={"host": socket.gethostname()}
        await svr.start(addr="", port=5000)
        print(f"Serving prometheus metrics on: {svr.metrics_url}")

        # Now start another coroutine to periodically update a metric to
        # simulate the application making some progress.
        async def updater(c: Counter):
            while True:
      {"kind": "timer_expiry"})
                await asyncio.sleep(1.0)

        await updater(events_counter)

    loop = asyncio.get_event_loop()
    svr = Service()
    except KeyboardInterrupt:

In this simple example the counter metric is tracking the number of while loop iterations executed by the updater coroutine. In a realistic application a metric might track the number of requests, etc.

Following typical asyncio usage, an event loop is instantiated first then a metrics service is instantiated. The metrics service is responsible for managing metric collectors and responding to metrics requests.

The service accepts various arguments such as the interface and port to bind to. A collector registry is used within the service to hold metrics collectors that will be exposed by the service. The service will create a new collector registry if one is not passed in.

A counter metric is created and registered with the service. The service is started and then a coroutine is started to periodically update the metric to simulate progress.

The example script can be run using:

(venv) $ cd examples
(venv) $ python
Serving prometheus metrics on:

In another terminal fetch the metrics using the curl command line tool to verify they can be retrieved by Prometheus server.

By default metrics will be returned in plan text format.

$ curl
# HELP events Number of events.
# TYPE events counter
events{host="alpha",kind="timer_expiry"} 33

$ curl -H 'Accept: text/plain; version=0.0.4'
# HELP events Number of events.
# TYPE events counter
events{host="alpha",kind="timer_expiry"} 36

Similarly, you can request metrics in binary format, though this will be hard to read on the command line.

$ curl -H "ACCEPT: application/; proto=io.prometheus.client.MetricFamily; encoding=delimited"

The metrics service also responds to requests sent to its / route. The response is simple HTML. This route can be useful as a Kubernetes health indicator as it does not incur any overhead within the service to serialize a full metrics response.

$ curl
<html><body><a href='/metrics'>metrics</a></body></html>

The aioprometheus package provides a number of convenience decorator functions that can assist with updating metrics.

There examples directory contains many examples showing how to use the aioprometheus package. The file will likely be of interest as it provides a more representative application example that the simple example shown above.

Examples in the examples/frameworks directory show how aioprometheus can be used within existing aiohttp, quart and vibora applications instead of creating a separate aioprometheus.Service endpoint to handle metrics. The vibora example is shown below.

#!/usr/bin/env python
Sometimes you want to expose Prometheus metrics from within an existing web
service and don't want to start a separate Prometheus metrics server.

This example uses the aioprometheus package to add Prometheus instrumentation
to a Vibora application. In this example a registry and a counter metric is
instantiated. A '/metrics' route is added to the application and the render
function from aioprometheus is called to format the metrics into the
appropriate format.

from aioprometheus import render, Counter, Registry
from vibora import Vibora, Request, Response

app = Vibora(__name__)
app.registry = Registry()
app.events_counter = Counter("events", "Number of events.")

async def hello(request: Request):{"path": "/"})
    return Response(b"hello")

async def handle_metrics(request: Request):
    Negotiate a response format by inspecting the ACCEPTS headers and selecting
    the most efficient format. Render metrics in the registry into the chosen
    format and return a response.
    content, http_headers = render(app.registry, [request.headers.get("accept")])
    return Response(content, headers=http_headers)


aioprometheus is released under the MIT license.

aioprometheus originates from the (now deprecated) prometheus python package which was released under the MIT license. aioprometheus continues to use the MIT license and contains a copy of the orignal MIT license from the prometheus-python project as instructed by the original license.


aioprometheus originates from the (now deprecated) prometheus python package. Many thanks to slok for developing prometheus-python. I have taken the original work and modified it to meet the needs of my asyncio-based applications, added the histogram metric, integrated support for binary format, updated and extended tests, added docs, decorators, etc.