Metadata-Version: 2.4
Name: prometheus-xmpp-alerts
Version: 0.6.0
Summary: Prometheus XMPP Alerts hook
Author-email: Jelmer Vernooij <jelmer@jelmer.uk>
License: Apachev2
Project-URL: Homepage, https://jelmer.uk/code/prometheus-xmpp-alerts
Project-URL: Bug Tracker, https://github.com/jelmer/prometheus-xmpp-alerts/issues
Project-URL: Repository, https://github.com/jelmer/prometheus-xmpp-alerts
Project-URL: GitHub, https://github.com/jelmer/prometheus-xmpp-alerts
Keywords: prometheus xmpp jabber
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: slixmpp
Requires-Dist: aiohttp
Requires-Dist: pytz
Requires-Dist: pyyaml
Requires-Dist: aiohttp_openmetrics
Requires-Dist: jinja2
Requires-Dist: bs4
Provides-Extra: testing
Requires-Dist: pytz; extra == "testing"
Provides-Extra: dev
Requires-Dist: ruff==0.12.12; extra == "dev"
Dynamic: license-file

prometheus-xmpp-alerts
======================

A simple web hook that forwards prometheus alerts over XMPP.

Usage
-----
#
To use, configure a web hook in alertmanager. E.g.:

```yaml
receivers:
- name: 'jelmer-xmpp'
  webhook_configs:
  - url: 'http://192.168.2.1:9199/alert'
```

Edit the configuration file (defaults to ``/etc/prometheus/xmpp-alerts.yml``):

```yaml
jid: 'alertmanager@example.com'
password: 'PASSWORD'
# Alternatively, set a 'password_command' that should write a password to
# stdout
# password_command: 'pass show xmpp-alertmanager'
to_jid: 'jelmer@example.com'
listen_address: '192.168.2.1'
listen_port: 9199

# Text message template as jinja2; defaults to html_template with tags stripped (optional)
text_template: |
 {{ status.upper() }}: *{{ labels.alertname }}* at {{ labels.host or labels.instance }}:\
 {{ annotations.message }}. {{ generatorURL }}
```

You can also set the following environment variables instead:

* ``XMPP_ID`` - XMPP JID
* ``XMPP_PASS`` - Password
* ``XMPP_RECIPIENTS`` - comma-separated list of recipients

* ``XMPP_AMTOOL_ALLOWED`` - comma-separated list of users (optional)

* ``WEBHOOK_HOST`` - Address to listen on (optional)
* ``WEBHOOK_PORT`` - Port to listen on (optional)

* ``TEXT_TEMPLATE`` - Template for text messages (see above, optional)
* ``HTML_TEMPALTE`` - Template for HTML messages (see above, optional)

And run the web hook::

```shell
$ python3 -m prometheus_xmpp --config=/etc/prometheus/xmpp-alerts.yaml
```

If you have [amtool](https://github.com/prometheus/alertmanager#amtool) set up,
then you can also allow users to see existing alerts and manage silences.
Set the ``amtool_allowed`` option to JIDs that are allowed to use amtool.

Docker file
-----------

You can build your own docker images using the Dockerfile in this directory, or
use ``ghcr.io/jelmer/prometheus-xmpp-alerts``. Provide your configuration in
``/config.yaml`` or through environment variables.

Message Format
--------------

The default message format looks something like this:

  > FIRING: *AlertName* at somehost: Alert Summary. https://prometheus.example.com/expr?...

The ``text_template`` option in the configuration can be used to customize the
format, using jinja2.

Testing
-------

The web hook can be accessed on three paths:

 * ``/alert``: used by Prometheus to deliver alerts, expects POST requests
   with JSON body
 * ``/test``: delivers a test message
 * ``/metrics``: exposes statistics about number of alerts received
