Skip to main content

Prometheus python client and instrumentation library

Project description

The unofficial Python 2 and 3 client for Prometheus.

https://travis-ci.org/Lispython/pyprometheus.svg?branch=master

Features

  • Four types of metric are supported: Counter, Gauge, Summary(without quantiles) and Histogram.

  • InMemoryStorage (do not use it for multiprocessing apps)

  • UWSGI storage - share metrics between processes

  • UWAGI flush storage - sync metrics with uwsgi sharedarea by flush call

  • time decorator

  • time context manager

INSTALLATION

To use pyprometheus use pip or easy_install:

pip install pyprometheus

or

easy_install pyprometheus

HOW TO INSTRUMENTING CODE

Gauge

A gauge is a metric that represents a single numerical value that can arbitrarily go up and down.:

from pyprometheus import Gauge
from pyprometheus import BaseRegistry, LocalMemoryStorage

storage = LocalMemoryStorage()
registry = CollectorRegistry(storage=storage)
gauge = Gauge("job_in_progress", "Description", registry=registry)

gauge.inc(10)
gauge.dec(5)
gauge.set(21.1)

utilities:

gauge.set_to_current_time()   # Set to current unixtime

# Increment when entered, decrement when exited.
@gauge.track_in_progress()
def f():
    pass

with gauge.track_in_progress():
    pass


with gauge.time():
    time.sleep(10)

Counter

A counter is a cumulative metric that represents a single numerical value that only ever goes up.:

from pyprometheus import Counter
from pyprometheus import BaseRegistry, LocalMemoryStorage

storage = LocalMemoryStorage()
registry = CollectorRegistry(storage=storage)
counter = Counter("requests_total", "Description", registry=registry)

counter.inc(10)

Summary

Similar to a histogram, a summary samples observations (usually things like request durations and response sizes).:

from pyprometheus import Summary
from pyprometheus import BaseRegistry, LocalMemoryStorage

storage = LocalMemoryStorage()
registry = CollectorRegistry(storage=storage)
s = Summary("requests_duration_seconds", "Description", registry=registry)

s.observe(0.100)

utilities for timing code:

@gauge.time()
def func():
   time.sleep(10)

with gauge.time():
   time.sleep(10)

Histogram

A histogram samples observations (usually things like request durations or response sizes) and counts them in configurable buckets. It also provides a sum of all observed values.:

from pyprometheus import Summary
 from pyprometheus import BaseRegistry, LocalMemoryStorage

 storage = LocalMemoryStorage()
 registry = CollectorRegistry(storage=storage)
 histogram = Histogram("requests_duration_seconds", "Description", registry=registry)

 histogram.observe(1.1)

utilities for timing code:

@histogram.time()
def func():
   time.sleep(10)

with histogram.time():
   time.sleep(10)

Labels

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

Example:

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

or labels as keyword arguments:

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

STORAGES

Currently library support 2 storages: LocalMemoryStorage and UWSGIStorage

Every registry MUST have link to storage:

from pyprometheus import BaseRegistry, LocalMemoryStorage

storage = LocalMemoryStorage()
registry = CollectorRegistry(storage=storage)

Use LocalMemoryStorage

Simple storage that store samples to application memory. It can be used with threads.:

from pyprometheus import BaseRegistry, LocalMemoryStorage

storage = LocalMemoryStorag()

Use UWSGIStorage

UWSGIStorage allow to use uwsgi sharedarea to sync metrics between processes.:

from pyprometheus.contrib.uwsgi_features import UWSGICollector, UWSGIStorage

SHAREDAREA_ID = 0
storage = UWSGIStorage(SHAREDAREA_ID)

also need to configure UWSGI sharedaread pages.

EXPORTING

Library have some helpers to export metrics

To text format

You can convert registry to text format:

from pyprometheus import BaseRegistry, LocalMemoryStorage
from pyprometheus.utils.exposition import registry_to_text
from pyprometheus import Gauge

storage = LocalMemoryStorage()
registry = CollectorRegistry(storage=storage)
g = Gauge('raid_status', '1 if raid array is okay', registry=registry)
g.set(1)
print(registry_to_text(registry))

Text file export

This is useful for monitoring cronjobs, or for writing cronjobs to expose metrics about a machine system.:

from pyprometheus import BaseRegistry, LocalMemoryStorage
from pyprometheus.utils.exposition import registry_to_text, write_to_textfile
from pyprometheus import Gauge

storage = LocalMemoryStorage()
registry = CollectorRegistry(storage=storage)
g = Gauge('raid_status', '1 if raid array is okay', registry=registry)
g.set(1)
write_to_textfile(registry, "/path/to/file/metrics.prom")

You can configure text file collector to use generated file.

TODO

Some features that we plan to do:

  • [ ] Add mmap storage

  • [ ] Add features for async frameworks

  • [ ] Optimize UWSGI storage byte pad

  • [ ] Add quantiles

EXAMPLE PROJECT

We create example project to show hot to use pyprometheus in real project.

CONTRIBUTE

Fork https://github.com/Lispython/pyprometheus/ , create commit and pull request to develop.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyprometheus-0.0.9.tar.gz (21.1 kB view details)

Uploaded Source

Built Distribution

pyprometheus-0.0.9-py2.py3-none-any.whl (22.9 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file pyprometheus-0.0.9.tar.gz.

File metadata

File hashes

Hashes for pyprometheus-0.0.9.tar.gz
Algorithm Hash digest
SHA256 ec94ebf5bc079a94a1e8fe45e859c340da2da967573344b52387b0bbd48e5edc
MD5 55196b3dd17a59f50d17601389c14173
BLAKE2b-256 272dc8755ef50cebd5290e2d3cb89e9869a0718382956f95a60bff66924780ff

See more details on using hashes here.

File details

Details for the file pyprometheus-0.0.9-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for pyprometheus-0.0.9-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 4dbdc654e7389bbd60c6d975c6b8bca148bb6dcb2691832221c9cf2a1431d0e1
MD5 3cf33ba01f9a5828985e092c20e35c30
BLAKE2b-256 39bfe26eb1d8fbd99240813675120c40e09a79cf3b14020cee3a5854d460940f

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page