Prometheus python client
Python 3 client library for Prometheus that can serve data to prometheus (in text and protobuf formats) and also push data to a pushgateway.
Table of Contents
Status
Under heavy development
Install
$ pip install prometheus
Why Python 3 and not python 2?
I think that everyone should start adopting the "new" Python version and let python2 be the old man that every one likes talking to but don't want live be with him.
And the only way doing this is by "forcing people" to use py3.
Also Maintaining code for one version is hard, imagine 2... error prone, slower updates...
So, don't use Python 2 and start using Python 3!
Usage
Serve data
from http.server import HTTPServer
from prometheus.exporter import PrometheusMetricHandler
from prometheus.registry import Registry
registry = Registry()
def handler(*args, **kwargs):
PrometheusMetricHandler(registry, *args, **kwargs)
server = HTTPServer(('', 8888), handler)
server.serve_forever()
Push data (to pushgateway)
TODO
Metrics/Collectors
Counter
from prometheus.collectors import Counter
uploads_metric = Counter("file_uploads_total", "File total uploads.")
uploads_metric.inc({'type': "png", })
Gauge
from prometheus.collectors import Gauge
ram_metric = Gauge("memory_usage_bytes", "Memory usage in bytes.", {'host': host})
ram_metric.set({'type': "virtual", }, 100)
Summary
from prometheus.collectors import Summary
http_access = Summary("http_access_time", "HTTP access time", {'time': 'ms'})
values = [3, 5.2, 13, 4]
for i in values:
http_access.add({'time': '/static'}, i)
Labels
Labels define the multidimensional magic in prometheus. To add a metric to a collector you identify with a label for example we have this collector that stores the cosumed memory:
ram_metric = Gauge("memory_usage_bytes", "Memory usage in bytes.")
And then we add our RAM user MBs:
ram_metric.set({'type': "virtual", }, 100)
aplying mutidimensional capacity we can store in the same metric the memory consumed by the swap of our system too:
ram_metric.set({'type': "swap", }, 100)
Const labels
When you create a collector
you can put to than collector constant labels,
these constant labels will apply to all the metrics gathered by that collector
apart from the ones that we put. For example this example without const labels
ram_metric = Gauge("memory_usage_bytes", "Memory usage in bytes.")
ram_metric.set({'type': "virtual", 'host': host}, 100)
ram_metric.set({'type': "swap", 'host': host}, 100)
is the same as this one with const labels:
ram_metric = Gauge("memory_usage_bytes", "Memory usage in bytes.", {'host': host})
ram_metric.set({'type': "virtual", }, 100)
ram_metric.set({'type': "swap", }, 100)
Examples
Serve examples
Gauges
- Memory and cpu usage (Requires psutil)
- Trigonometry samples
Summaries
How to use the examples
First some examples need requirements, install them:
pip install requirements_test.txt
Now run an example, for example timing_write_io_example.py
python ./examples/timing_write_io_example.py
All examples run on port 4444
. You can point prometheus conf like this to
point to one of the examples:
job: {
name: "python-client-test"
scrape_interval: "1s"
target_group: {
target: "http://xxx.xxx.xxx.xxx:4444/metrics"
}
}
Or you can test the different formats available with curl:
Default (Text 0.0.4):
curl 'http://127.0.0.1:4444/metrics'
Text (0.0.4):
curl 'http://127.0.0.1:4444/metrics' -H 'Accept: text/plain; version=0.0.4'
Protobuf debug (0.0.4):
curl 'http://127.0.0.1:4444/metrics' -H 'Accept: application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=text'
Protobuf (0.0.4):
curl 'http://127.0.0.1:4444/metrics' -H 'Accept: application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited'
PushGateway examples
Gauges
How to use the examples
First you need to run a gateway, for example with docker:
docker run --rm -p 9091:9091 prom/pushgateway
Now configure prometheus to grab the metrics from the push gateway example
job: {
name: "pushgateway"
scrape_interval: "1s"
target_group: {
target: "http://172.17.42.1:9091/metrics"
}
}
Ready to launch the example:
python ./examples/input_example.py
As the serve explanation, you can debug de pushgateway serving data by
accessing its URL (in the example: http://localhost:9091/metrics
) with Curl
Tests
$ pip install -r requirements_test.txt
$ ./run_tests.sh
TODO
- Moaaaar examples
- implement handy utils