11 Motor MQTT

El motor MQTT se suscribe a un broker MQTT y guarda el último mensaje recibido en cada topic. Los ítems de Zabbix leen esos valores o descubren los topics disponibles. A diferencia de los otros motores, no ejecuta ninguna operación cuando Zabbix pide un valor: los datos llegan continuamente desde el broker, a través de un hilo receptor.

11.1 Configuración: sección `[MQTT]`#

Parámetro	Defecto	Descripción
`Server`	obligatorio	Nombre o IP del broker.
`Port`	1883	Puerto del broker.
`Id`	obligatorio	Identificador de cliente MQTT. Debe ser único en el broker.
`UserName`	obligatorio	Usuario.
`Password`	obligatorio	Contraseña.
`Timeout`	20000	Tiempo máximo de conexión, en ms.
`Subscription`	`#`	Jerarquía de topics a la que se suscribe. Escríbase `\043` para `#`.
`DiscoveryDelay`	10000	Tras el arranque, espera en ms antes de responder a los descubrimientos, para dar tiempo a recibir todos los topics.
`AbsentDelay`	10000	Espera en ms antes de volver a intentar un ítem cuyo topic no tiene mensajes nuevos.

[General]
Name = PLANTA1
Engine = MQTT
QueryFile = /etc/databbix/query-mqtt.xml

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

[Data]
Module = MQTT

[MQTT]
Server = mqtt.empresa.com
Id = databbix-planta1
UserName = zabbix
Password = secreto
Subscription = planta1/\043       # planta1/#

11.2 Ficheros de consultas#

Las consultas MQTT no llevan elementos propios: la operación es siempre la misma (leer el último valor de un topic). El fichero query-mqtt.xml de la distribución contiene las dos consultas necesarias:

<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>

Atención. En este motor, los nombres de ítem son fijos: el motor solo responde a ts.mqtt.getvalue y ts.mqtt.discovery. Un <item> con otro nombre se carga sin error, pero sus valores son siempre no soportados.

Reglas de las consultas MQTT:

Los <parameter> solo llevan order (o value) y type. El parámetro es el topic o, en los descubrimientos, el patrón de topics.
Los <item> solo llevan name; no admiten atributos que indiquen de dónde sale el valor.
Un descubrimiento debe tener exactamente un <parameter> y un <field>. El <field> solo lleva name: la macro toma como valor el nombre completo del topic.

11.3 Lectura de valores#

La clave ts.mqtt.getvalue[topic] devuelve el contenido del último mensaje publicado en ese topic. Dados estos mensajes recibidos del broker:

Últimos mensajes recibidos

Topic	Contenido
planta1/linea1/temperatura	21.5
planta1/linea1/presion	1.02
planta1/linea2/temperatura	22.1
planta1/estado	`{"modo":"auto","alarmas":0}`

Valores obtenidos

Clave	Valor
ts.mqtt.getvalue[planta1/linea1/temperatura]	21.5
ts.mqtt.getvalue[planta1/estado]	`{"modo":"auto","alarmas":0}`
ts.mqtt.getvalue[planta1/linea3/temperatura]	no soportado: no se ha recibido

El contenido se envía tal cual. Si es un JSON, como en planta1/estado, se pueden extraer sus campos en Zabbix con un preprocesado JSONPath en el ítem.

Un valor solo se envía a Zabbix cuando ha llegado un mensaje nuevo desde la última vez. Si no ha llegado ninguno, el ítem se vuelve a intentar al cabo de AbsentDelay milisegundos, en lugar de repetir el valor anterior.

11.4 Descubrimiento de topics#

La clave ts.mqtt.discovery[patrón] devuelve todos los topics recibidos que encajan con el patrón. El patrón usa los comodines de MQTT:

Comodín	Significado
`+`	Exactamente un nivel cualquiera.
`#`	Cualquier número de niveles.

Con los mensajes de la sección anterior:

Patrones y topics descubiertos

Clave	Valores de {#TOPIC}
ts.mqtt.discovery[planta1/+/temperatura]	planta1/linea1/temperatura
	planta1/linea2/temperatura
ts.mqtt.discovery[planta1/linea1/#]	planta1/linea1/temperatura
	planta1/linea1/presion
ts.mqtt.discovery[planta1/+]	planta1/estado
	planta1/linea1/temperatura
	planta1/linea1/presion
	planta1/linea2/temperatura

Nota. A diferencia de MQTT estándar, en Databbix un patrón también encaja con los topics que tienen más niveles que él: funciona como un prefijo. Así, planta1/+ descubre de una vez todos los topics que cuelgan de cualquier subnivel de planta1. Para limitar el resultado a un nivel concreto, escriba el patrón con todos los niveles (planta1/+/temperatura).

El valor del primer ítem es:

{"data":[ {"{#TOPIC}":"planta1/linea1/temperatura"},
          {"{#TOPIC}":"planta1/linea2/temperatura"} ]}

En Zabbix se crea una regla de descubrimiento con esa clave y el prototipo de ítem ts.mqtt.getvalue[{#TOPIC}].

Solo se descubren los topics de los que ya se ha recibido algún mensaje. Por eso, durante los primeros DiscoveryDelay milisegundos tras el arranque, los descubrimientos se retrasan.

11.5 Datos de ejecución#

El motor MQTT ofrece estos datos de ejecución:

Nombre	Valor
`DATABBIX.PROGRAM_NAME`	`databbix`, o `queryexplorer` en esa utilidad.
`CONN.TYPE`	`MQTT`.

Como las consultas de este motor no tienen condiciones <when>, estos datos solo se consultan con getRuntimeValue en queryexplorer.

11 Motor MQTT

11.1 Configuración: sección [MQTT]#

11.2 Ficheros de consultas#

11.3 Lectura de valores#

11.4 Descubrimiento de topics#

11.5 Datos de ejecución#

11.1 Configuración: sección `[MQTT]`#