prometheus-aioexporter 2.0.0

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 [HOST ...]
                        host addresses to bind (default: ['localhost'])
  -p PORT, --port PORT  port to run the webserver on (default: 9090)
  --metrics-path METRICS_PATH
                        path under which metrics are exposed (default: /metrics)
  -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)
  --ssl-private-key     full path to the ssl private key
  --ssl-public-key      full path to the ssl public key
  --ssl-ca              full path to the ssl certificate authority (CA)

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 pyproject.toml to generate the script, like

[project.scripts]
my-exporter = "path.to.script:script"

The description of the exporter can be customized by setting the docstring in the script class.

In order to serve metrics on the HTTPS endpoint both ssl-private-key and ssl-public-key need to be define. The ssl certificate authority (i.e. ssl-ca) is optional.

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: argparse.Namespace) -> None:
    # ...
    self.create_metrics(
        [
            MetricConfig("metric1", "a metric", "gauge"),
            MetricConfig("metric2", "another metric", "counter", labels=("l1", "l2")),
        ]
    )

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: aiohttp.web.Application) -> None:
    # ...
    application["exporter"].set_metric_update_handler(self._update_handler)

async def _update_handler(self, metrics: dict[str, prometheus_client.metrics.MetricWrapperBase]):
    for name, metric in metrics.items():
        metric.set(...)

See prometheus_aioexporter.sample for a complete example (the script can be run as prometheus-aioexporter-sample).