| single |
# Prometheus Python Client
The official Python client for [Prometheus].
## Three Step Demo
**One**: Install the client:
```
pip install prometheus-client
```
**Two**: Paste the following into a Python interpreter:
```python
from prometheus_client import start_http_server, Summary
import random
import time
# Create a metric to track time spent and requests made.
REQUEST_TIME = Summary('request_processing_seconds', 'Time spent processing
request')
# Decorate function with metric.
@REQUEST_TIME.time()
def process_request(t):
"""A dummy function that takes some time."""
time.sleep(t)
if __name__ == '__main__':
# Start up the server to expose the metrics.
start_http_server(8000)
# Generate some requests.
while True:
process_request(random.random())
```
**Three**: Visit [http://localhost:8000/] to view the metrics.
From one easy to use decorator you get:
* `request_processing_seconds_count`: Number of times this function was
called.
* `request_processing_seconds_sum`: Total amount of time spent in this
function.
Prometheus's `rate` function allows calculation of both requests per
second,
and latency over time from this data.
In addition if you're on Linux the `process` metrics expose CPU, memory and
other information about the process for free!
## Installation
```
pip install prometheus-client
```
This package can be found on
[PyPI].
## Instrumenting
Four types of metric are offered: Counter, Gauge, Summary and Histogram.
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.
```python
from prometheus_client import Counter
c = Counter('my_failures', 'Description of counter')
c.inc() # Increment by 1
c.inc(1.6) # Increment by given value
```
If there is a suffix of `_total` on the metric name, it will be removed.
When
exposing the time series for counter, a `_total` suffix will be added. This
is
for compatibility between OpenMetrics and the Prometheus text format, as
OpenMetrics
requires the `_total` suffix.
There are utilities to count exceptions raised:
```python
@c.count_exceptions()
def f():
pass
with c.count_exceptions():
pass
# Count only one type of exception
with c.count_exceptions(ValueError):
pass
```
|