{"id":19851589,"url":"https://github.com/albertodonato/prometheus-aioexporter","last_synced_at":"2025-06-20T05:34:42.047Z","repository":{"id":57455049,"uuid":"83226508","full_name":"albertodonato/prometheus-aioexporter","owner":"albertodonato","description":"Asyncio library for creating Prometheus exporters","archived":false,"fork":false,"pushed_at":"2025-06-08T07:26:49.000Z","size":203,"stargazers_count":16,"open_issues_count":0,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-08T08:19:26.822Z","etag":null,"topics":["asyncio","library","metrics","prometheus","prometheus-exporter","python-library"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/albertodonato.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-02-26T17:17:58.000Z","updated_at":"2025-06-08T07:25:48.000Z","dependencies_parsed_at":"2023-10-23T21:33:08.711Z","dependency_job_id":"42e51b2c-7291-4405-bb19-01d45b3aab8d","html_url":"https://github.com/albertodonato/prometheus-aioexporter","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/albertodonato/prometheus-aioexporter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertodonato%2Fprometheus-aioexporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertodonato%2Fprometheus-aioexporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertodonato%2Fprometheus-aioexporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertodonato%2Fprometheus-aioexporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/albertodonato","download_url":"https://codeload.github.com/albertodonato/prometheus-aioexporter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertodonato%2Fprometheus-aioexporter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260889959,"owners_count":23077857,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","library","metrics","prometheus","prometheus-exporter","python-library"],"created_at":"2024-11-12T13:30:14.209Z","updated_at":"2025-06-20T05:34:37.034Z","avatar_url":"https://github.com/albertodonato.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Asyncio library for creating Prometheus exporters\n=================================================\n\n|Latest Version| |Build Status|\n\n``prometheus-aioexporter`` is an aysncio-based library to simplify writing\nPrometheus_ exporters in Python.\n\nExporters are usually implemented as small daemons that expose metrics\nin text format through a web endpoint (usually ``/metrics``).\n\n\nUsage\n-----\n\nThe library provides a ``PrometheusExporterScript`` class that serves as an\nentry point to create services that export Prometheus metrics via an HTTP(s)\nendpoint.\n\nCreating a new exporter is just a matter of subclassing\n``PrometheusExporterScript`` and implementing a few methods as needed.\n\nAn example usage is the following:\n\n.. code:: python\n\n    import click\n    from prometheus_aioexporter import Arguments, PrometheusExporterScript\n\n\n    class MyExporter(PrometheusExporterScript):\n        \"\"\"My Prometheus exporter.\"\"\"\n\n        name = \"my-exporter\"\n        default_port = 9091\n        envvar_prefix = \"MYEXP\"\n\n        def command_line_parameters(self) -\u003e list[click.Parameter]:\n            # Additional options for the script\n            return [\n                click.Option([\"--custom-option\"], help=\"a custom option\"),\n                ...\n            ]\n\n        def configure(self, args: Arguments) -\u003e None:\n            # Save attributes that are needed for later\n            self.data = do_stuff()\n            # ...\n\n        async def on_application_startup(\n            self, application: aiohttp.web.Application\n        ) -\u003e None:\n            # Start other asyncio tasks at application startup\n            do_something_with(self.data)\n            # ...\n\n        async def on_application_shutdown(\n            self, application: aiohttp.web.Application\n        ) -\u003e None:\n            # Stop other asyncio tasks at application shutdown\n            do_more_with(self.data)\n            # ...\n\n\n    script = MyExporter()\n\n\nAlso see the `sample script`_ for a complete example.\n\nThe ``script`` variable from the example above can be referenced in\n``pyproject.toml`` to generate the script, like\n\n.. code:: toml\n\n    [project.scripts]\n    my-exporter = \"path.to.script:script\"\n\n\nThe ``description`` of the exporter can be customized by setting the docstring\nin the script class.\n\n\nExporter command-line\n~~~~~~~~~~~~~~~~~~~~~\n\n``PrometheusExporterScript`` provides a few command-line arguments by default:\n\n.. code::\n\n    Options:\n      -H, --host TEXT                 host addresses to bind  [env var: EXP_HOST;\n                                      default: localhost]\n      -p, --port INTEGER              port to run the webserver on  [env var:\n                                      EXP_PORT; default: 9091]\n      --metrics-path TEXT             path under which metrics are exposed  [env\n                                      var: EXP_METRICS_PATH; default: /metrics]\n      -L, --log-level [critical|error|warning|info|debug]\n                                      minimum level for log messages  [env var:\n                                      EXP_LOG_LEVEL; default: info]\n      --log-format [plain|json]       log output format  [env var: EXP_LOG_FORMAT;\n                                      default: plain]\n      --process-stats                 include process stats in metrics  [env var:\n                                      EXP_PROCESS_STATS]\n      --ssl-private-key FILE          full path to the ssl private key  [env var:\n                                      EXP_SSL_PRIVATE_KEY]\n      --ssl-public-key FILE           full path to the ssl public key  [env var:\n                                      EXP_SSL_PUBLIC_KEY]\n      --ssl-ca FILE                   full path to the ssl certificate authority\n                                      (CA)  [env var: EXP_SSL_CA]\n      --version                       Show the version and exit.\n      --help                          Show this message and exit.\n\n\nFurther options can be added by implementing ``command_line_parameters()`` to\nreturn additional ``click.Argument`` and ``click.Option`` items to add to the\ncommand line.\n\nSee the Click_ manual for more details on available parameter types.\n\nIn order to serve metrics on the HTTPS endpoint both ``ssl-private-key`` and\n``ssl-public-key`` need to be define. The ssl certificate authority\n(i.e. ``ssl-ca``) is optional.\n\n\nEnvironment variables\n~~~~~~~~~~~~~~~~~~~~~\n\nValues from default arguments can also be supplied via environment variables.\nVariables names match the ``\u003cenvvar_prefix\u003e_\u003coption_with_underscores`` format,\nso, for instance, the ``--port`` option can be provided as ``MYEXP_PORT=9091``\n(assuming the ``PrometheusExporterScript.envvar_prefix`` is set to ``MYEXP``).\n\nProvided command-line options take precedence over environment variables.\n\nIt's also possible to provide environment variables via dotenv file. By default\n``.env`` is looked up in the current working directory. The file to load can be\noverridden by setting the file path via the ``\u003cenvvar_prefix\u003e_DOTENV``\nvariable.\n\nExplicitly provided environment variables take precedence over the ones defined\nin the dotenv file.\n\n\nStartup configuration\n~~~~~~~~~~~~~~~~~~~~~\n\nAdditional initial setup (e.g. config file parsing) can be performed by the\nscript by implementing the ``configure()``. This is called at startup with the\nparsed arguments (an ``Arguments`` instance).\n\n\nMetrics configuration\n~~~~~~~~~~~~~~~~~~~~~\n\nThe metrics exported by the script can be set up by calling ``create_metrics``\nwith a list of ``MetricConfig``\\s. This is typically done in ``configure()``:\n\n.. code:: python\n\n    def configure(self, args: Arguments) -\u003e None:\n        # ...\n        self.create_metrics(\n            [\n                MetricConfig(\"metric1\", \"a metric\", \"gauge\"),\n                MetricConfig(\"metric2\", \"another metric\", \"counter\", labels=(\"l1\", \"l2\")),\n            ]\n        )\n\n\nWeb application setup\n~~~~~~~~~~~~~~~~~~~~~\n\nOn startup, ``PrometheusExporterScript`` creates a ``PrometheusExporter`` which\nincludes a web application that exposes metrics.\n\nIt's possible to customize and perform additional startup/shutdown tasks by\nimplementing the ``on_application_startup`` and ``on_application_shutdown``\ncoroutine methods, which are called with the application as parameter.\n\nThe ``PrometheusExporter`` instance is accessible via\n``application[\"exporter\"]``), and provides a ``set_metric_update_handler``\nmethod to register a hook to update metrics on each request, before the\nresponse is returned to the client.  The registered function must return a\ncoroutine and is called with a dict mapping metric names to metric objects:\n\n.. code:: python\n\n    async def on_application_startup(self, application: aiohttp.web.Application) -\u003e None:\n        # ...\n        application[\"exporter\"].set_metric_update_handler(self._update_handler)\n\n    async def _update_handler(self, metrics: dict[str, prometheus_client.metrics.MetricWrapperBase]):\n        for name, metric in metrics.items():\n            metric.set(...)\n\n\nSee ``prometheus_aioexporter.sample`` for a complete example (the script can be\nrun as ``prometheus-aioexporter-sample``).\n\n\n.. _Prometheus: https://prometheus.io/\n.. _Click: https://click.palletsprojects.com/en/stable/\n.. _sample script: ./prometheus_aioexporter/sample.py\n\n.. |Latest Version| image:: https://img.shields.io/pypi/v/prometheus-aioexporter.svg\n   :alt: Latest Version\n   :target: https://pypi.python.org/pypi/prometheus-aioexporter\n.. |Build Status| image:: https://github.com/albertodonato/prometheus-aioexporter/workflows/CI/badge.svg\n   :alt: Build Status\n   :target: https://github.com/albertodonato/prometheus-aioexporter/actions?query=workflow%3ACI\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbertodonato%2Fprometheus-aioexporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falbertodonato%2Fprometheus-aioexporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbertodonato%2Fprometheus-aioexporter/lists"}