Skip to main content

Asyncio library for creating Prometheus exporters.

Project description

Latest Version Build Status Coverage Status

prometheus-aioexporter is an aysncio-powered library to simplify writing Prometheus exporters.

Exporters are usually implemented as small daemons that expose metrics in text format through a web endpoint (usually /metrics).

Usage

The library provides a PrometheusExporterScript class that serves as an entry point to create services that export Prometheus metrics via an HTTP endpoint.

Creating a new exporter is just a matter of subclassing PrometheusExporterScript and implementing a few methods as needed.

An example usage is the following:

from prometheus_aioexporter.script import PrometheusExporterScript


class MyExporter(PrometheusExporterScript):
    """My Prometheus exporter."""

    def configure_argument_parser(self, parser):
        # Additional arguments to the script
        parser.add_argument('an-option', help='an option')
        # ...

    def configure(self, args):
        # Save attributes that are needed for later
        self.data = do_stuff()
        # ...

    async def on_application_startup(self, application):
        # Start other asyncio tasks at application startup
        use(self.data)
        # ...

    async def on_application_shutdown(self, application):
        # Stop other asyncio tasks at application shutdown
        use(self.data)
        # ...


script = MyExporter()

Exporter command-line

PrometheusExporterScript provides a few command-line arguments by default:

optional arguments:
  -h, --help            show this help message and exit
  -H HOST, --host HOST  host address to bind (default: localhost)
  -p PORT, --port PORT  port to run the webserver on (default: 9090)
  -L {CRITICAL,ERROR,WARNING,INFO,DEBUG}, --log-level {CRITICAL,ERROR,WARNING,INFO,DEBUG}
                        minimum level for log messages (default: WARNING)
  --process-stats       include process stats in metrics (default: False)

Further options can be added by implementing configure_argument_parser(), which receives the argparse.ArgumentParser instance used by the script.

The script variable from the example above can be referenced in setup.py to generate the script, like

setup(
    ...,
    entry_points={'console_scripts': ['script = path.to.script:script']},
    ...)

The name and description of the exporter can be customized by setting the respective attributes in the script class.

Startup configuration

Additional initial setup (e.g. config file parsing) can be performed by the script by implementing the configure(). This is called at startup with the parsed argument (an argparse.Namespace instance).

Metrics configuration

The metrics exported by the script can be set up by calling create_metrics with a list of MetricConfigs. This is typically done in configure():

def configure(self, args):
    # ...
    self.create_metrics(
        [MetricConfig('metric1', 'a metric', 'gauge', {}),
         MetricConfig('metric2', 'another metric', 'counter', {})])

Web application setup

On startup, PrometheusExporterScript creates a PrometheusExporter which includes a web application that exposes metrics.

It’s possible to customize and perform additional startup/shutdown tasks by implementing the on_application_startup and on_application_shutdown coroutine methods, which are called with the application as parameter.

The PrometheusExporter instance is accessible via application['exporter']), and provides a set_metric_update_handler method to register a hook to update metrics on each request, before the response is returned to the client. The registered function must return a coroutine and is called with a dict mapping metric names to metric objects:

async def on_application_startup(self, application):
    # ...
    application.set_metric_update_handler(self._update_handler)

async def _update_handler(self, metrics):
    for name, metric in metrics.items():
        metric.set(...)

Project details


Release history Release notifications

This version
History Node

1.4.0

History Node

1.3.0

History Node

1.2.0

History Node

1.1.0

History Node

1.0.2

History Node

1.0.1

History Node

1.0.0

History Node

0.2.2

History Node

0.2.1

History Node

0.2.0

History Node

0.1.0

Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
prometheus_aioexporter-1.4.0-py3-none-any.whl (13.9 kB) Copy SHA256 hash SHA256 Wheel py3 Feb 19, 2018
prometheus-aioexporter-1.4.0.tar.gz (11.4 kB) Copy SHA256 hash SHA256 Source None Feb 19, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page