Metadata-Version: 1.1
Name: pyprometheus
Version: 0.0.7
Summary: Prometheus python client and instrumentation library
Home-page: https://github.com/Lispython/pyprometheus
Author: Alexandr Lispython
Author-email: lispython@users.noreply.github.com
License: BSD
Description: Prometheus instrumentation library for Python applications
        ============================================================
        
        The unofficial Python 2 and 3 client for `Prometheus`_.
        
        .. image:: https://travis-ci.org/Lispython/pyprometheus.svg?branch=master
            :target: https://travis-ci.org/Lispython/pyprometheus
        
        
        
        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:
        
        :code:`pip install pyprometheus`
        
        or
        
        :code:`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``.
        
        
        
        .. _`example project`: http://github.com/Lispython/pyprometheus_demo
        .. _`text file collector`: https://github.com/prometheus/node_exporter#textfile-collector
        .. _`uwsgi sharedarea`: http://uwsgi-docs.readthedocs.io/en/latest/SharedArea.html
        .. _`Prometheus`: http://prometheus.io
        
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Networking :: Monitoring
