tangledgroup Prometheus Python Client 0.25.0
Overview
The official Prometheus client library for Python. Instrument applications with metrics that Prometheus scrapes via HTTP. Six metric types cover counting, gauging, distribution tracking, and metadata exposition. The library provides built-in HTTP servers, WSGI/ASGI adapters, and framework-specific integrations for serving metrics at /metrics.
When to Use
- Adding Prometheus metrics to a Python application
- Exposing metrics endpoints in Flask, Django, FastAPI, AIOHTTP, or Twisted
- Instrumenting request latency, error rates, queue depths, or custom business metrics
- Running batch jobs that push metrics via Pushgateway
- Multiprocess deployments with Gunicorn workers
- Building custom collectors for external data sources
Core Concepts
Metric types — Choose based on what the value does:
| Type | Update model | Use for |
|---|---|---|
| Counter | only up | requests served, errors, bytes sent |
| Gauge | up and down | queue depth, active connections, temperature |
| Histogram | observations in buckets | latency/size distributions with quantile queries |
| Summary | observations (count + sum) | latency/size when average is enough |
| Info | static key-value pairs | build version, environment metadata |
| Enum | one of N states | task state, lifecycle phase |
Naming — namespace, subsystem, and name join with underscores: myapp_http_requests_total. Full metric names must match [a-zA-Z_:][a-zA-Z0-9_:]*.
Labels — Dimensions for grouping related time series. Declared via labelnames=['method', 'status'], applied via .labels(method='GET', status='200').
Registry — REGISTRY is the global default. All metric constructors register with it automatically. Pass registry=None to skip registration (useful in tests).
Installation / Setup
pip install prometheus-client
Usage Examples
Quick start with Summary decorator
from prometheus_client import start_http_server, Summary
import random, time
REQUEST_TIME = Summary('request_processing_seconds', 'Time spent processing request')
@REQUEST_TIME.time()
def process_request(t):
time.sleep(t)
if __name__ == '__main__':
start_http_server(8000)
while True:
process_request(random.random())
Visit http://localhost:8000/metrics to view metrics. Prometheus rate() function computes both requests per second and latency from the _count and _sum series.
Counter with labels
from prometheus_client import Counter, start_http_server
REQUESTS = Counter(
'requests_total',
'Total HTTP requests received',
labelnames=['method', 'status'],
namespace='myapp',
)
def handle_request(method, status):
REQUESTS.labels(method=method, status=status).inc()
if __name__ == '__main__':
start_http_server(8000)
Gauge tracking in-progress requests
from prometheus_client import Gauge, start_http_server
ACTIVE = Gauge('inprogress_requests', 'Number of requests being processed', namespace='myapp')
@ACTIVE.track_inprogress()
def process():
# ... work ...
pass
if __name__ == '__main__':
start_http_server(8000)
Histogram with custom buckets
from prometheus_client import Histogram, start_http_server
LATENCY = Histogram(
'request_duration_seconds',
'HTTP request latency',
labelnames=['method', 'endpoint'],
namespace='myapp',
buckets=[.01, .05, .1, .25, .5, 1, 2.5, 5],
)
def handle_request(method, endpoint):
with LATENCY.labels(method=method, endpoint=endpoint).time():
# ... handle request ...
pass
if __name__ == '__main__':
start_http_server(8000)
Advanced Topics
Metric Types: Complete reference for all 6 metric types with constructors, methods, and real-world examples → Metric Types
Labels and Exemplars: Label declaration, initialization, management, and trace-context exemplars → Labels and Exemplars
Exporting: HTTP servers, WSGI/ASGI adapters, framework integrations (Flask, Django, FastAPI, AIOHTTP, Twisted), Pushgateway, textfile collector, Graphite bridge → Exporting
Advanced Patterns: Registry management, custom collectors, multiprocess mode for Gunicorn, metrics parser, restricted registries → Advanced Patterns