MQTT Integration

MQTT is a lightweight, publish-subscribe, machine to machine network protocol for message queue/message queuing service. It is designed for connections with remote locations that have devices with resource constraints or limited network bandwidth, such as in the Internet of Things. While we dont directly support an MQTT broker to accept publishing of messages, we do support integrations specificly meant to connect MQTT topics to ilert events and provide the ilagent tool to connect your MQTT brokers to ilert without actually writing the code yourself.

In ilert: Create a MQTT alert source

1. Go to Alert sources -> Alert sources and click on Create new alert source

   
2. Search for MQTT in the search field, click on the MQTT tile, and click on Next.

   
3. Give your alert source a name, optionally assign teams, and click Next.

4. Select an escalation policy by creating a new one or assigning an existing one.

   
5. Select your Alert grouping preference and click Continue setup. You may click Do not group alerts for now and change it later.

   
6. The next page shows additional settings such as customer alert templates or notification prioritiy. Click on Finish setup for now.

7. On the final page, an API key and / or webhook URL will be generated that you will need later in this guide.

   

In your environment

Foreword: you are free to use any MQTT client to subscribe to your topics and wire them into an API call to POST api.ilert.com/api/v1/mqtt/{your-key-here} (the endpoint accepts the payload of our generic event API https://api.ilert.com/api-docs/#tag/events/post/events | see also this eventing guide)

However if you dont wish to write your own software to wire subscriber and POST request, you may use our swiss-army-knife tool ilagent which supports an mqtt mode where it subscribes to a specific MQTT topic to delivery events or heartbeats to ilert; it automatically buffers the messages in a local database to support retries as well. It is open source and can be found on Github: https://github.com/iLert/ilagent

While you may compile the binary locally, we also support an official Docker image ilert/ilagent which can be used to get started quickly.

Consume a topic and turn messages into events

For this to work, your messages need to be in the format of the ilert event API schema; at least: {apiKey, eventType, summary}

docker run -p 8977:8977 ilert/ilagent daemon -p 8977 -v -v \
    -m mqtt-broker-host -q 1883 -n ilagentsub -e 'ilert/e'

You can always check docker run ilert/ilagent --help for a full list of arguments. e.g. username and password for the MQTT broker.

If you dont want to provide the apiKey in every message, you can overwrite with the --event_key 'il1api123...' argument.

Transform any kind of message into events

For this to work, your messages need to be JSON

The ilagent also supports basic event key overwrites so that you can map any message top level keys into an event payload.

docker run -p 8977:8977 ilert/ilagent daemon -v -v \
    -m mqtt-broker-host -q 1883 -n ilagent -e '#' \
    --event_key 'il1api123...' \
    --map_key_alert_key 'mCode' \
    --map_key_summary 'comment' \
    --map_key_etype 'state' \
    --map_val_etype_alert 'SET' \
    --map_val_etype_accept 'ACK' \
    --map_val_etype_resolve 'CLR' \
    --filter_key 'type' \
    --filter_val 'ALARM'

The top sample code will subscribe to ALL mqtt topics and filter every message for message.type == 'ALERT' it will then map the field message.state: SET => ALERT, ACK => ACCEPT and CLR => RESOLVE to the event.eventType additionally message.mCode will be used as event.alertKey and message.comment as event.summary.

With these flexible arguments you may quickly prototype or start your alert management without the need to write and deploy a custom mapper.

If you are using this subscriber bridge for critical scenarios, make sure to read the section on MQTT at least once delivery guarantee in the ilagent readme.

FAQ

My local docker ilert/ilagent does not connect to my broker

In case your broker is running in docker as well, you cannot simply use localhost to connect, you will need to link your broker to your ilagent container with --link broker-container-name:broker-container-name then provide -m broker-container-name so that your ilagent actually connects to your broker