Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/weastur/pyexporter

Template for prometheus exporter written on Python
https://github.com/weastur/pyexporter

metrics-exporter prometheus-exporter

Last synced: 5 months ago
JSON representation

Template for prometheus exporter written on Python

Awesome Lists containing this project

README 

        
# pyexporter



![PyPI - License](https://img.shields.io/pypi/l/py_exporter_template?style=for-the-badge&link=https%3A%2F%2Fpyexporter.weastur.com%2FLICENSE%2F)

![Codecov](https://img.shields.io/codecov/c/github/weastur/pyexporter?style=for-the-badge&link=https%3A%2F%2Fcodecov.io%2Fgh%2Fweastur%2Fpyexporter)

![PyPI - Version](https://img.shields.io/pypi/v/py_exporter_template?style=for-the-badge&link=https%3A%2F%2Fpypi.org%2Fproject%2Fpy-exporter-template%2F%23history)

![PyPI - Python Version](https://img.shields.io/pypi/pyversions/py_exporter_template?style=for-the-badge&link=https%3A%2F%2Fpypi.org%2Fproject%2Fpy-exporter-template%2F)

![uv](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fastral-sh%2Fuv%2Fmain%2Fassets%2Fbadge%2Fv0.json&style=for-the-badge&link=https%3A%2F%2Fgithub.com%2Fastral-sh%2Fuv)

![ruff](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fastral-sh%2Fruff%2Fmain%2Fassets%2Fbadge%2Fv2.json&style=for-the-badge&link=https%3A%2F%2Fgithub.com%2Fastral-sh%2Fruff)



Template for a Prometheus exporter for various metrics.



- Create a repo from this template

- Change name of the package, Docker image, docs, examples, etc.

- Implement your own collectors

- Enjoy!



## Installation



The exporter is written in Python. The simplest way to run it is to use the Docker image.



```shell

docker run -d -p 9123:9123 weastur/py-exporter:latest

```



Additionally, as it's a standard Python package, you can install it with `pip` or `pipx`:



```shell

pip install py-exporter-template

```



An isolated installation using a virtual environment can be found in the [examples](https://github.com/weastur/pyexporter/blob/main/examples/ansible/roles/playbook.yml).



## Usage



### Configuring



There are several ways to configure the exporter (in a priority order):



- Defaults

- Command line arguments

- Environment variables

- `.env` file in the current directory

- Configuration file (`config.yaml` or `config.yml`) in the current directory



#### Defaults and command line arguments



The exporter can be run with or without arguments (using defaults). See the full list of parameters with defaults

[below](#full-list-of-command-line-arguments).



#### Environment variables



All parameters can be set with environment variables. The environment variables should be in the following format:

`PY_EXPORTER_` using `__` as a nested delimeter

(replacing `.` in command line arguments)

For example:



```shell

export PY_EXPORTER_LOG__LEVEL=debug

export PY_EXPORTER_COLLECTOR__DEFAULT__GC=false

```



#### `.env` file



The `.env` file should be in the current directory and follow this format:



```shell

PY_EXPORTER_LOG__LEVEL=debug

PY_EXPORTER_COLLECTOR__DEFAULT__GC=false

```



#### Configuration file



The configuration file should be in the current directory and follow this format:



```yaml

log:

  level: debug

web:

  port: 9123

  addr: "0.0.0.0"

```



See the full example [here](https://github.com/weastur/pyexporter/blob/main/examples/config.yml).



P. S. By the way, you can dump json schema for the configuration file with the following command:



```shell

py-exporter jsonschema config.schema.json

```



### [Full list of command line arguments](#full-list-of-command-line-arguments)



```shell

usage: py-exporter [-h]

                   [--log.level {trace,debug,info,success,warning,error,critical}]

                   [--web.port int] [--web.addr IPv4Address]

                   [--web.tls.cert Path] [--web.tls.key Path]

                   [--web.tls.protocol int]

                   [--web.tls.mtls.enabled | --no-web.tls.mtls.enabled]

                   [--web.tls.mtls.cafile Path] [--web.tls.mtls.capath Path]

                   [--collector.disable_created_series | --no-collector.disable_created_series]

                   [--collector.default.gc | --no-collector.default.gc]

                   [--collector.default.platform | --no-collector.default.platform]

                   [--collector.default.process | --no-collector.default.process]

                   {jsonschema} ...



optional arguments:

  -h, --help            show this help message and exit



subcommands:

  {jsonschema}

    jsonschema          Dump the JSON schema to a file.



log options:

  --log.level {trace,debug,info,success,warning,error,critical}

                        Log level (default: info)



web options:

  --web.port int        Port to listen on (default: 9123)

  --web.addr IPv4Address

                        Address to listen on (default: 0.0.0.0)



web.tls options:

  --web.tls.cert Path   Path to the TLS certificate (default: None)

  --web.tls.key Path    Path to the TLS key (default: None)

  --web.tls.protocol int

                        TLS protocol number, as described in the ssl python

                        module (default: 17)



web.tls.mtls options:

  --web.tls.mtls.enabled, --no-web.tls.mtls.enabled

                        Enable mTLS (default: False)

  --web.tls.mtls.cafile Path

                        Path to the client CA file (default: None)

  --web.tls.mtls.capath Path

                        Path to the client CA directory (default: None)



collector options:

  --collector.disable_created_series, --no-collector.disable_created_series

                        Disable created series (default: False)



collector.default options:

  --collector.default.gc, --no-collector.default.gc

                        Enable the GC collector (default: True)

  --collector.default.platform, --no-collector.default.platform

                        Enable the platform collector (default: True)

  --collector.default.process, --no-collector.default.process

                        Enable the process collector (default: True)

```



## Examples



In the [examples](https://github.com/weastur/pyexporter/tree/main/examples/) you can find some useful files to look at:



- Docker Compose [file](https://github.com/weastur/pyexporter/blob/main/examples/observability/docker-compose.yml) example

- Prometheus [config](https://github.com/weastur/pyexporter/blob/main/examples/observability/prometheus.yml) to scrape the exporter

- Grafana [dashboard](https://github.com/weastur/pyexporter/blob/main/examples/observability/dashboard.json)

- VRL [program](https://github.com/weastur/pyexporter/blob/main/examples/observability/vector.yaml) for Vector

- SystemD [service](https://github.com/weastur/pyexporter/blob/main/examples/ansible/service.j2) file for running the exporter outside the container

- Ansible [playbook](https://github.com/weastur/pyexporter/blob/main/examples/ansible/playbook.yml) to deploy it in an isolated environment outside the container

- Full [dump](https://github.com/weastur/pyexporter/blob/main/examples/metrics.txt) (one scrape) of all metrics exporter can generate.

  You can investigate it with [prom2json](https://github.com/prometheus/prom2json)



## Contributing



- Read the [contribution guide](https://github.com/weastur/pyexporter/blob/main/CONTRIBUTING.md)

- Don't forget to take a quick look at [code of conduct](https://github.com/weastur/pyexporter/blob/main/CODE_OF_CONDUCT.md)



## Credits



Although the license doesn’t require credits, I maintain a list of authors in the [CREDITS](https://github.com/weastur/pyexporter/blob/main/CREDITS.md)

file in the alphabetical order.



## License



MIT, see [LICENSE](https://github.com/weastur/pyexporter/blob/main/LICENSE.md)