Using Prosody's mod_push_msg to send Grafana alerts to an XMPP chat room

Grafana doesn't have native xmpp alerting support, this describes how to configure it to use a Prosody module to send alerts to an XMPP chat room.

Introduction

Daniel Gultsch published an article on sending Jabber / XMPP Messages via HTTP. I have often wanted Grafana to be able to send alerts into our XMPP infrastructure so I thought I would try setting it up and seeing if Grafana is flexible enough to be able to send alerts to a Multi User Chatroom (MUC). TL;DR: it is.

Assumptions

• We use Bastille jails so this guide applies to that, but if you don't use Bastille it should be easy enough to set up outside of Bastille.
• I also assume a working Prosody installation: this details the changes to an existing set up.
• We support multiple domains for our XMPP service, so we're assuming a VirtualDomain is set up.
• You have already got MUCs configured for the VirtualDomain that you're hoping to send the alerts to.
• You are able to make sure that your Grafana service can talk to your Prosody service over port 5281 and you are able to provide suitable certificates to Prosody for this to work correctly. If you have a proxy in front of Prosody, or have the http service on any other port you should be able to adjust the instructions below to take account of that.

Prosody set up

It is worth noting at this stage that I had to change my authentication source as the method that I was using (mod_auth_imap) doesn't support HTTP Basic authentication. I am now using mod_auth_dovecot instead. This is out of scope of this guide.

You need a user set up for Grafana to post to the MUC from (I'm using grafana@<domain name>).

First you need to add the mod_post_msg and mod_muc_bot modules to your Prosody installation, here are my Bastillefile additions:

CMD prosodyctl install --server=https://modules.prosody.im/rocks/ mod_post_msg
CMD prosodyctl install --server=https://modules.prosody.im/rocks/ mod_muc_bot

Next, enable the mod_post_msg in prosody.cfg.lua:

    modules_enabled = {
        [...]
        "post_msg"; -- allows sending XMPP <message> stanzas via a simple HTTP API.
        [...]
    }

Now add the following to your VirtualHost configuration, changing <domain name> to whatever the domain name is for your VirtualHost:

VirtualHost "<domain name>"
    [...]
    modules_enabled = { "muc_mam", "muc_bot" }
    known_bots = { "grafana@<domain name>" }
    bots_get_messages = false
    ignore_bot_errors = true

Now restart Prosody and, if necessary, set up the MUC that you want to send alerts to and make sure the user that you intend to send alerts as is able to log in, and is part of the MUC.

Grafana

Go to Alerting -> Notification configuration and either edit an existing Contact Point, or create a new one.

When adding a Contact Point Integration, choose Webhook and set the URL to https://<domain name>:5281/msg/.

Expand the Optional webhook settings and set them as follows:

• HTTP Method: POST
• HTTP Basic Authentication - Username: username of the user you want to send alerts as
• HTTP Basic Authentication - Password: password of the user you want to send alerts as
• Extra Headers:
  • Name: Content-Type
  • Value: application/json
• Custom Payload:

  { "to": "<full address of the MUC>", "type": "groupchat", "body": "{{ template "default.message" . }}" }

Now run a test, and you should find the message is successfully delivered into the chat room.