Prometheus Python Client

This is a first pass at a Python client for Prometheus.

Installation

pip install prometheus_client

This package can be found on PyPI.

Instrumenting

Three types of metric are offered: Counter, Gauge, and Summary. See the documentation on metric types and instrumentation best practices on how to use them.

Counter

Counters go up, and reset when the process restarts.

from prometheus_client import Counter
c = Counter('my_failures_total', 'Description of counter')
c.inc()     # Increment by 1
c.inc(1.6)  # Increment by given value

There are utilities to count exceptions raised:

@c.countExceptions()
def f():
  pass

with c.countExceptions():
  pass

# Count only one type of exception
with c.countExceptions(ValueError):
  pass

Gauge

Gauges can go up and down.

from prometheus_client import Gauge
g = Gauge('my_inprogress_requests', 'Description of gauge')
g.inc()      # Increment by 1
g.dev(10)    # Decrement by given value
g.set(4.2)   # Set to a given value

There are utilities for common use cases:

g.setToCurrentTime()   # Set to current unixtime

# Increment when entered, decrement when exited.
@g.trackInprogress()
def f():
  pass

with g.trackInprogress():
  pass

Summaries

Summaries track the size and number of events.

from prometheus_client import Summary
s = Summary('request_latency_seconds', 'Description of summary')
s.observe(4.7)    # Observe 4.7 (seconds in this case)

There are utilities for timing code:

@s.time()
def f():
  pass

with s.time():
  pass

Labels

All metrics can have labels, allowing grouping of related time series.

See the best practices on naming and labels.

Taking a counter as an example:

from prometheus_client import Counter
c = Counter('my_requests_total', 'HTTP Failures', ['method', 'endpoint'])
c.labels('get', '/').inc()
c.labels('post', '/submit').inc()

Exporting

Metrics are exposed over HTTP, to be read by the Prometheus server. For example:

from prometheus_client import MetricsHandler
from BaseHTTPServer import HTTPServer
server_address = ('', 8000)
httpd = HTTPServer(server_address, MetricsHandler)
httpd.serve_forever()

Visit http://localhost:8000/ to view the metrics.