garriga
An AlertManager webhook used to allow posting alert messages to a Matrix channel.
Features
- Post AlertManager alerts to a Matrix channel.
- Works with Prometheus.
- Works with Grafana Mimir.
- OSGi-ready
- JPMS-ready
- ISC license.
OCI
OCI images are available at quay.io.
Usage
Provide a configuration file providing the various required details. For
example, assume the following content in a file named config.json:
{
"%schema": "urn:com.io7m.garriga:configuration:1",
"HTTPServer": {
"ListenAddress": "::",
"ListenPort": 6000,
"AuthenticationToken": "some-random-token-value"
},
"MatrixClient": {
"BaseURI": "https://matrix.example.com",
"User": "@alerts:matrix.example.com",
"Password": "changeit",
"Channel": "#alerts:matrix.example.com"
}
}
Run garriga server --configuration-file config.json. The server will
bind to all addresses, listening on port 6000, and will attempt to connect
to the given Matrix server using the provided credentials. Anyone talking
to the server will be required to supply an
Authorization: Bearer some-random-token-value header.
WebHook
The server exposes an endpoint at /4/send that expects POST requests
supplying data in the version 4 AlertManager
format.
An example of a real-life message is as follows:
{
"receiver": "matrix-webhook",
"status": "firing",
"alerts": [
{
"status": "firing",
"labels": {
"alertname": "HostFilesystemDeviceError",
"device": "srv/grafana01/matrix_forwarder/etc",
"fstype": "zfs",
"instance": "srv.example.com:9100",
"job": "dns-discovery",
"mountpoint": "/srv/grafana01/matrix_forwarder/etc",
"severity": "critical"
},
"annotations": {
"description": "srv.example.com:9100: Device error with the /srv/grafana01/matrix_forwarder/etc filesystem\n VALUE = 1\n LABELS = map[__name__:node_filesystem_device_error device:srv/grafana01/matrix_forwarder/etc fstype:zfs instance:srv.example.com:9100 job:dns-discovery mountpoint:/srv/grafana01/matrix_forwarder/etc]",
"summary": "Host filesystem device error (instance srv.example.com:9100)"
},
"startsAt": "2024-06-13T17:06:10.763Z",
"endsAt": "0001-01-01T00:00:00Z",
"generatorURL": "/graph?g0.expr=node_filesystem_device_error%7Bfstype%3D~%22ext2%7Cext4%7Czfs%7Cxfs%7Cvfat%22%7D+%3D%3D+1\u0026g0.tab=1",
"fingerprint": "530731b28264424f"
},
{
"status": "resolved",
"labels": {
"alertname": "HostSwapIsFillingUp",
"instance": "w01.example.com:9100",
"job": "dns-discovery",
"nodename": "w01",
"severity": "warning"
},
"annotations": {
"description": "Swap is filling up (\u003e80%)\n VALUE = 98.72484146349024\n LABELS = map[instance:w01.example.com:9100 job:dns-discovery nodename:workstation01]",
"summary": "Host swap is filling up (instance w01.example.com:9100)"
},
"startsAt": "2024-06-13T11:53:10.763Z",
"endsAt": "0001-01-01T00:00:00Z",
"generatorURL": "/graph?g0.expr=%28%281+-+%28node_memory_SwapFree_bytes+%2F+node_memory_SwapTotal_bytes%29%29+%2A+100+%3E+80%29+%2A+on+%28instance%29+group_left+%28nodename%29+node_uname_info%7Bnodename%3D~%22.%2B%22%7D\u0026g0.tab=1",
"fingerprint": "983929006a0177d3"
}
],
"groupLabels": {},
"commonLabels": {
"job": "dns-discovery"
},
"commonAnnotations": {},
"externalURL": "http://localhost:8080/alertmanager",
"version": "4",
"groupKey": "{}/{}:{}",
"truncatedAlerts": 0
}
Releases & Development Snapshots
Releases
You can subscribe to the atom feed to be notified of project releases.
The most recently released version of the package is 1.0.0.
1.0.0 Release (2024-06-13Z)
The compiled artifacts for the release (and all previous releases) are available on Maven Central.
Maven Modules
<dependency> <group>com.io7m.garriga</group> <artifactId>com.io7m.garriga.main</artifactId> <version>1.0.0</version> </dependency><dependency> <group>com.io7m.garriga</group> <artifactId>com.io7m.garriga.oci</artifactId> <version>1.0.0</version> </dependency><dependency> <group>com.io7m.garriga</group> <artifactId>com.io7m.garriga.tests</artifactId> <version>1.0.0</version> </dependency>
Development Snapshots
At the time of writing, the current unstable development version of the package is 1.0.1-SNAPSHOT.
Development snapshots may be available in the Central Portal Snapshots repository. Snapshots are published to this repository every time the project is built by the project's continuous integration system, but snapshots do expire after around ninety days and so may or may not be available depending on when a build of the package was last triggered.
Manual
This project does not have any user manuals or other documentation beyond what might be present on the page above.
Sources
This project uses Git to manage source code.
Repository: https://www.github.com/io7m-com/garriga
$ git clone --recursive https://www.github.com/io7m-com/garriga
Issues
This project uses GitHub Issues to track issues.
License
Copyright © 2024 Mark Raynsford <code@io7m.com> https://www.io7m.com Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.