Registry / observability / starlette-prometheus

starlette-prometheus

library0.10.0pypypiunverified

Starlette-prometheus is a Python library that provides seamless Prometheus integration for Starlette applications. It includes a middleware to automatically expose key metrics such as total requests, request duration, and concurrent requests. The library is currently at version 0.10.0, released on September 3, 2024, with a development cadence that includes periodic updates and feature enhancements.

observability web-framework

pip install starlette-prometheus uvicorn

github ↗package ↗

INSTALL

IMPORT

SIG · STARLETTE-PROMETHE

starlette-prometheus

observabilitypythonv0.10.0

Install

2.3s avg

Import

433ms

Disk

21MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.10.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.452s · 23.1MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.3s · import 0.414s · 24MB

21MB installed

● package 21MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PrometheusMiddleware

✓ from starlette_prometheus import PrometheusMiddleware

metrics

✓ from starlette_prometheus import metrics

✗ from starlette_prometheus.middleware import metrics

The `metrics` endpoint handler is exposed directly from the top-level package for convenience.

Starlette

✓ from starlette.applications import Starlette

✗ from starlette import Starlette

Starlette application class resides in `starlette.applications`.

This quickstart demonstrates how to integrate `starlette-prometheus` into a basic Starlette application. It sets up `PrometheusMiddleware` to automatically collect HTTP request metrics and exposes them at the `/metrics` endpoint. Run this file using `uvicorn quickstart:app --port 8000` and then access `http://localhost:8000/metrics` to see the collected metrics.

import uvicorn from starlette.applications import Starlette from starlette.responses import PlainTextResponse from starlette_prometheus import PrometheusMiddleware, metrics app = Starlette() app.add_middleware(PrometheusMiddleware, app_name='my_starlette_app', prefix='starlette_app_prefix') app.add_route('/metrics', metrics) @app.route('/') async def homepage(request): return PlainTextResponse('Hello, world!') @app.route('/items/{item_id}') async def read_item(request): item_id = request.path_params['item_id'] return PlainTextResponse(f'Item: {item_id}') if __name__ == '__main__': # Run with: uvicorn quickstart:app --port 8000 uvicorn.run(app, host='0.0.0.0', port=8000)

Debug

Known issues

gotchaFailing to filter unhandled paths (e.g., 404s) can lead to unbounded memory use and high cardinality metrics, potentially overwhelming your Prometheus server.

fix

Initialize PrometheusMiddleware with `filter_unhandled_paths=True`. Example: `app.add_middleware(PrometheusMiddleware, filter_unhandled_paths=True)`.

affects: All versions

breakingWhen deploying with multiple worker processes (e.g., Gunicorn or Uvicorn with `--workers`), Prometheus metrics will not aggregate correctly by default, leading to incomplete or incorrect data.

fix

Set the `PROMETHEUS_MULTIPROC_DIR` environment variable to a shared directory. `prometheus_client` will use this directory to store metric files, which Prometheus can then scrape and aggregate. For example: `export PROMETHEUS_MULTIPROC_DIR=/tmp/prometheus_metrics`.

affects: All versions

deprecatedOlder versions (pre-0.9.0) of `starlette-prometheus` contained a bug (`UnboundLocalError`) when handling certain requests.

fix

Upgrade `starlette-prometheus` to version `0.9.0` or higher to resolve the `UnboundLocalError: local variable 'status_code' referenced before assignment` bug.

affects: <0.9.0

Upgrade

Version history

0.10.0latest on PyPI · released Sep 3, 2024

Audit

Dependencies

starletterequiredCore ASGI framework for integration.

prometheus-clientrequiredPython client for Prometheus metric exposition.

pythonrequiredRuntime environment.

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/PeRDy/starlette-prometheus ↗

packagehttps://pypi.org/project/starlette-prometheus/ ↗