databbix User manual Español

11 MQTT engine

The MQTT engine subscribes to an MQTT broker and keeps the last message received on each topic. Zabbix items read those values or discover the available topics. Unlike the other engines, it runs no operation when Zabbix asks for a value: data arrives continuously from the broker, through a receiver thread.

11.1 Configuration: the [MQTT] section#

Parameter Default Description
Server mandatory Broker name or IP.
Port 1883 Broker port.
Id mandatory MQTT client identifier. Must be unique on the broker.
UserName mandatory User.
Password mandatory Password.
Timeout 20000 Maximum connection time, in ms.
Subscription # Topic hierarchy to subscribe to. Write \043 for #.
DiscoveryDelay 10000 After startup, time in ms to wait before answering discoveries, to allow all topics to be received.
AbsentDelay 10000 Time in ms before retrying an item whose topic has no new messages. 
[General]
Name = PLANT1
Engine = MQTT
QueryFile = /etc/databbix/query-mqtt.xml

[Zabbix]
Server = zabbix.example.com
Port = 10051

[Data]
Module = MQTT

[MQTT]
Server = mqtt.example.com
Id = databbix-plant1
UserName = zabbix
Password = secret
Subscription = plant1/\043       # plant1/#

11.2 Query files#

MQTT queries have no elements of their own: the operation is always the same (read the last value of a topic). The distribution’s query-mqtt.xml file contains the two queries needed:

<Queries engine="MQTT" databbix="2.5.0" query="2.3.0">

<query name="ItemValue" module="MQTT">
    <parameter order="1" type="STRING"/>
    <item name="ts.mqtt.getvalue"/>
</query>

<query name="ItemDiscover" module="MQTT" discovery="yes">
    <parameter order="1" type="STRING"/>
    <item name="ts.mqtt.discovery"/>
    <field name="TOPIC"/>
</query>

</Queries>

Warning.  In this engine, item names are fixed: the engine only answers ts.mqtt.getvalue and ts.mqtt.discovery. An <item> with any other name loads without error, but its values are always not supported.

Rules for MQTT queries:

  • <parameter> elements only have order (or value) and type. The parameter is the topic or, in discoveries, the topic pattern.

  • <item> elements only have name; they accept no attributes saying where the value comes from.

  • A discovery must have exactly one <parameter> and one <field>. The <field> only has name: the macro takes the full topic name as its value.

11.3 Reading values#

The key ts.mqtt.getvalue[topic] returns the content of the last message published on that topic. Given these messages received from the broker:

Last messages received

Topic Content
plant1/line1/temperature 21.5
plant1/line1/pressure 1.02
plant1/line2/temperature 22.1
plant1/status {"mode":"auto","alarms":0}

Values obtained

Key Value
ts.mqtt.getvalue[plant1/line1/temperature] 21.5
ts.mqtt.getvalue[plant1/status] {"mode":"auto","alarms":0}
ts.mqtt.getvalue[plant1/line3/temperature] not supported: never received

The content is sent as is. If it is JSON, as in plant1/status, its fields can be extracted in Zabbix with JSONPath preprocessing on the item.

A value is only sent to Zabbix when a new message has arrived since the last time. If none has arrived, the item is retried after AbsentDelay milliseconds, instead of repeating the previous value.

11.4 Topic discovery#

The key ts.mqtt.discovery[pattern] returns all the received topics that match the pattern. The pattern uses MQTT wildcards:

Wildcard Meaning
+ Exactly one level, any value.
# Any number of levels.

With the messages of the previous section:

Patterns and discovered topics

Key Values of {#TOPIC}
ts.mqtt.discovery[plant1/+/temperature] plant1/line1/temperature
plant1/line2/temperature
ts.mqtt.discovery[plant1/line1/#] plant1/line1/temperature
plant1/line1/pressure
ts.mqtt.discovery[plant1/+] plant1/status
plant1/line1/temperature
plant1/line1/pressure
plant1/line2/temperature

Note.  Unlike standard MQTT, in Databbix a pattern also matches topics with more levels than itself: it works as a prefix. This way, plant1/+ discovers in one go all the topics under any sublevel of plant1. To narrow the result to a specific level, write the pattern with all its levels (plant1/+/temperature).

The value of the first item is:

{"data":[ {"{#TOPIC}":"plant1/line1/temperature"},
          {"{#TOPIC}":"plant1/line2/temperature"} ]}

In Zabbix, create a discovery rule with that key and this item prototype:
ts.mqtt.getvalue[{#TOPIC}]

Only topics for which some message has already been received are discovered. That is why discoveries are delayed during the first DiscoveryDelay milliseconds after startup.

11.5 Runtime data#

The MQTT engine offers this runtime data:

Name Value
DATABBIX.PROGRAM_NAME databbix, or queryexplorer in that utility.
CONN.TYPE MQTT.

Since queries in this engine have no <when> conditions, this data can only be read with getRuntimeValue in queryexplorer.