prometheus-client

prometheus-client is the official Python client for the Prometheus monitoring system, providing Counter, Gauge, Histogram, Summary, and Info metric types along with a registry that Prometheus scrapes over HTTP in its native exposition format (and OpenMetrics). It ships built-in WSGI and ASGI HTTP servers for exposing a /metrics endpoint, plus integrations for Twisted, aiohttp, and Django.

Beyond straightforward metric instrumentation, it handles the harder operational cases: multiprocess mode for aggregating metrics across pre-forked worker processes (gunicorn, uWSGI), a process collector exposing memory/CPU/fd counts, a platform collector, and a Graphite bridge for pushing metrics to systems that don’t scrape Prometheus natively. It is the de facto standard for instrumenting any Python service intended to be observed by Prometheus.

What You Get

• Counter, Gauge, Histogram, Summary, and Info metric types with label support
• Built-in WSGI and ASGI servers (start_http_server, make_asgi_app) for exposing a /metrics endpoint
• Multiprocess mode for correctly aggregating metrics across pre-forked workers (gunicorn, uWSGI)
• Framework integrations for Twisted, aiohttp, and Django, plus a process collector for CPU/memory/fd stats
• OpenMetrics exposition format support alongside the classic Prometheus text format, and a Graphite bridge for push-based systems

Common Use Cases

• Instrumenting a Python web service (Flask, Django, FastAPI) with request counters, latency histograms, and in-flight gauges for Prometheus to scrape
• Exposing correct aggregate metrics from a multiprocess WSGI deployment (gunicorn workers) using the library’s multiprocess mode
• Building custom collectors that pull metrics from an external system (a queue depth, a cache hit ratio) and expose them in Prometheus format
• Bridging existing Prometheus metrics into a Graphite-based monitoring stack via the built-in push bridge

Under The Hood

Architecture The library centers on a CollectorRegistry that holds registered Collector objects; the four metric types (Counter, Gauge, Histogram, Summary in metrics.py) are themselves collectors that know how to serialize their internal state into Sample objects (samples.py), which exposition.py then renders into the Prometheus text or OpenMetrics wire format for scraping — multiprocess.py and values.py implement an alternate value-storage backend (memory-mapped files via mmap_dict.py) so metrics recorded in separate forked processes can be correctly summed at scrape time, a nontrivial problem this library solves that naive instrumentation code cannot.

Tech Stack Pure Python (3.9+, tested through 3.14 and PyPy) with zero required runtime dependencies for core functionality, using setuptools for packaging; optional integrations (prometheus_client/django, /aiohttp, /twisted, /bridge) are submodules activated only when those frameworks are present, keeping the base install lightweight while covering the major Python web/async ecosystems.

Code Quality The tests/ directory mirrors the source layout closely (test_core, test_multiprocess, test_exposition, test_parser, per-framework test files, and a dedicated tests/openmetrics/ and tests/proc/ for parser and process-collector fixtures), giving broad coverage of both the common path and the trickier multiprocess/OpenMetrics edge cases; the project ships py.typed for type-checker support and has been under continuous maintenance by the Prometheus organization for a decade.

API Design The core API is famously low-friction — Counter('name', 'help').inc() — and this simplicity, replicated across every Prometheus client library regardless of language, is a deliberate design constraint of the Prometheus project so metrics code looks the same whether you’re in Go, Java, or Python; the tradeoff surfaces in multiprocess mode, where correct usage requires understanding an extra environment variable (PROMETHEUS_MULTIPROC_DIR) and registry wiring that isn’t obvious from the basic API alone.