MQTT to Zabbix Bridge

MQTT to Zabbix Bridge — это легковесное Java-приложение, которое подписывается на MQTT-топики, обрабатывает входящие сообщения и отправляет данные в Zabbix через протокол Trapper (используя утилиту zabbix_sender). Программа поддерживает гибкий маппинг топиков на элементы данных Zabbix, автоматическое переподключение к MQTT-брокеру, мониторинг собственного состояния и может быть запущена как systemd-сервис.

Возможности

MQTT-подписка — подписка на один или несколько топиков (поддерживаются wildcard-шаблоны + и #).
Гибкий маппинг — сопоставление входящих топиков с хостами и ключами Zabbix с помощью регулярных выражений и подстановок ($1, $2…).
Извлечение значений — из JSON-полей (по имени поля) или использование всего payload как значения.
Подписка на конкретные топики — можно указать для каждого правила отдельный топик для подписки (если не указан, используется глобальный).
Автоматическое переподключение к MQTT — при потере соединения выполняется повторное подключение с экспоненциальной задержкой.
Повторные попытки отправки в Zabbix — при ошибках отправки данные повторяются до указанного числа раз с экспоненциальной задержкой.
Мониторинг работы программы — каждые N секунд в Zabbix отправляются метрики: количество обработанных сообщений, ошибок, повторных попыток и размер очереди.
Валидация конфигурации при старте — проверяются наличие zabbix_sender, обязательные параметры и корректность правил маппинга.
Блокировка двойного запуска — предотвращает одновременный запуск нескольких экземпляров.
Поддержка systemd — готовый unit-файл для запуска как сервиса с автоматическим перезапуском.
Внешняя конфигурация — файлы config.properties и mapping.json могут лежать рядом с JAR-файлом или внутри него (для удобства изменения без пересборки).

Требования

Java 11 или выше.
Maven (для сборки).
Утилита zabbix_sender должна быть установлена и доступна в PATH (обычно входит в пакет zabbix-sender). Используется для отправки данных.
MQTT-брокер (например, Mosquitto, EMQX и др.).
Zabbix-сервер (с настроенным trapper-портом, по умолчанию 10051).

Установка и сборка

1. Клонирование репозитория

git clone https://gitbucket.mfnd.ru/git/y.varenkov/MQTT-to-Zabbix-Bridge.git
cd mqtt-to-zabbix

2. Сборка проекта

mvn clean package

В каталоге target/ появится файл mqtt-to-zabbix-1.0-SNAPSHOT-jar-with-dependencies.jar — это самодостаточный JAR со всеми зависимостями.

3. Установка (опционально)

Скопируйте JAR и файлы конфигурации в рабочую директорию:

sudo mkdir -p /opt/mqtt-to-zabbix
sudo cp target/mqtt-to-zabbix-1.0-SNAPSHOT-jar-with-dependencies.jar /opt/mqtt-to-zabbix/
sudo cp src/main/resources/config.properties /opt/mqtt-to-zabbix/
sudo cp src/main/resources/mapping.json /opt/mqtt-to-zabbix/

Убедитесь, что zabbix_sender установлен:

sudo apt install zabbix-sender   # для Debian/Ubuntu
sudo yum install zabbix-sender   # для RHEL/CentOS

Настройка

Файл `config.properties`

Основные настройки приложения:

# MQTT Broker
mqtt.broker=tcp://localhost:1883
mqtt.topic=#                     # глобальный топик для подписки (используется, если не указан subscribeTopic в маппинге)
mqtt.user=
mqtt.password=

# Zabbix Trapper
zabbix.server=127.0.0.1
zabbix.port=10051

# Пул потоков
thread.pool.core=2
thread.pool.max=4
thread.pool.queue=1000

# Повторные попытки
retry.max.attempts=3
retry.initial.delay.ms=1000
retry.backoff.multiplier=2.0

# Мониторинг
metrics.host=MQTT-Bridge          # хост в Zabbix для метрик самой программы
metrics.interval=60               # интервал отправки метрик (секунд)

Файл `mapping.json`

Определяет правила преобразования топиков в элементы Zabbix. Формат:

[
  {
    "topicPattern": "sensors/temperature",
    "host": "Server1",
    "key": "temperature",
    "valueField": null,
    "subscribeTopic": "sensors/temperature"
  },
  {
    "topicPattern": "devices/([^/]+)/status",
    "host": "$1",
    "key": "status",
    "valueField": "state",
    "subscribeTopic": "devices/+/status"
  },
  {
    "topicPattern": "metrics/([^/]+)/([^/]+)",
    "host": "$1",
    "key": "$2",
    "valueField": "value"
  }
]

Поля:

topicPattern — регулярное выражение для сопоставления с входящим MQTT-топиком. Может содержать группы, которые затем используются в $1, $2...
host — имя хоста в Zabbix. Может содержать подстановки $1, $2 из групп регулярного выражения.
key — ключ элемента данных Zabbix. Аналогично поддерживает подстановки.
valueField — имя поля в JSON, из которого берётся значение. Если null или отсутствует, используется весь payload как строка.
subscribeTopic — (опционально) MQTT-топик для подписки. Если не указан, используется глобальный mqtt.topic из config.properties (или #). Можно указывать wildcard-символы + и #.

Настройка элементов данных в Zabbix

Для каждого ключа, указанного в маппинге, необходимо создать элемент данных типа Zabbix trapper на соответствующем хосте. В поле Разрешенные хосты укажите IP-адрес, с которого будут приходить данные (например, 127.0.0.1).

Для метрик мониторинга создайте хост MQTT-Bridge (или измените metrics.host) и элементы с ключами:

mqtt.bridge.processed — количество обработанных сообщений (целое)
mqtt.bridge.errors — количество ошибок обработки (целое)
mqtt.bridge.retries — количество повторных попыток отправки (целое)
mqtt.bridge.queue_size — текущий размер очереди задач (целое)

Запуск

Ручной запуск

java -jar /opt/mqtt-to-zabbix/mqtt-to-zabbix-1.0-SNAPSHOT-jar-with-dependencies.jar

Если файлы конфигурации лежат рядом с JAR, они будут загружены из файловой системы. Если нет — будут использованы встроенные (из classpath).

systemd (рекомендуется для продакшена)

Создайте unit-файл /etc/systemd/system/mqtt-to-zabbix.service:

[Unit]
Description=MQTT to Zabbix Bridge
After=network.target zabbix-server.service
Wants=zabbix-server.service

[Service]
Type=simple
User=zabbix
Group=zabbix
WorkingDirectory=/opt/mqtt-to-zabbix
ExecStart=/usr/bin/java -jar /opt/mqtt-to-zabbix/mqtt-to-zabbix-1.0-SNAPSHOT-jar-with-dependencies.jar
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=mqtt-to-zabbix

[Install]
WantedBy=multi-user.target

После создания выполните:

sudo systemctl daemon-reload
sudo systemctl enable mqtt-to-zabbix
sudo systemctl start mqtt-to-zabbix

Проверьте статус:

sudo systemctl status mqtt-to-zabbix

Логи можно просматривать через:

sudo journalctl -u mqtt-to-zabbix -f

Примеры работы

Пример MQTT-сообщения (JSON)

Топик: devices/room1/temperature
Payload: {"value":23.5, "timestamp":"2026-07-10T14:30:00Z"}

Правило:

{
  "topicPattern": "devices/([^/]+)/temperature",
  "host": "$1",
  "key": "temperature",
  "valueField": "value",
  "subscribeTopic": "devices/+/temperature"
}

Результат: В Zabbix для хоста room1 элемент с ключом temperature получит значение 23.5.

Пример MQTT-сообщения (просто число)

Топик: sensors/temperature
Payload: 20