Forward alerts from Grafana to a Matrix chat room.
This project provides a simple way to forward alerts generated by Grafana to a Matrix chat room.
Define a Grafana webhook alert channel that targets an instance of this application. This tool will convert the incoming webhook to a Matrix message and send it on to a specific chat room.
- 📦 Portable
- As a single binary the tool is easy to run in any environment
- 📎 Simple
- No config files, all required parameters provided on startup
- 🪁 Flexible
- Support multiple grafana alert channels to multiple matrix rooms
- 📈 Monitorable
- Export metrics to track successful and failed forwards
This applies to unified alerts, check the documentation for legacy alerts
Step 1
Run the forwarder by providing a matrix account to send messages from.
$ ./grafana-matrix-forwarder --user @userId:matrix.org --password xxx --homeserver matrix.org
Step 2
Add a new Contact Point in Grafana with the POST webhook type. Use the following URL:
http://<ip address>:6000/api/v1/unified?roomId=<roomId>
Replace with the server ID and matrix room ID.
Step 3
Add a new Notification Policy in Grafana to send alerts to the new contact point.
If you use the root policy, all alerts will be sent to that contact point
Step 4
Create alert rules in grafana and add text to the a "Summary" field to be displayed in the Matrix message.
An official docker image is available on the Gitlab container registry. Use it by pulling the following image:
registry.gitlab.com/hectorjsmith/grafana-matrix-forwarder:latest
Example run command:
docker run -d \
--name "grafana-matrix-forwarder" \
-e GMF_MATRIX_USER=@user:matrix.org \
-e GMF_MATRIX_PASSWORD=password \
-e GMF_MATRIX_HOMESERVER=matrix.org \
registry.gitlab.com/hectorjsmith/grafana-matrix-forwarder:latest
Read the documentation for more detail on using Docker.
Made possible by the maunium.net/go/mautrix library and all the contributors to the matrix.org protocol.