kpetrem/mqtt-exporter

MQTT-exporter

源代码

GitHub仓库: https://github.com/kpetremann/mqtt-exporter

概述

简单通用的MQTT Prometheus导出器。已通过Mosquitto MQTT和小米传感器测试。开箱即可从MQTT消息中暴露指标，只需指定目标MQTT地址（如非本地）。MQTT-exporter期望主题和扁平JSON payload，值必须为数值型。还为每个MQTT主题提供消息计数器，例如：

mqtt_message_total{instance="mqtt-exporter:9000", job="mqtt-exporter", topic="zigbee2mqtt_0x00157d00032b1234"} 10

支持的设备

注意：此导出器旨在尽可能通用。如果您使用的传感器采用以下格式，则可正常工作：

主题 '<前缀>/<名称>', 负载 '{"temperature":26.24,"humidity":45.37}'

同时支持Shelly格式：

主题 '<前缀>/<名称>/sensor/temperature' '20.00'

已测试设备包括：

• Aqara/小米传感器（WSDCGQ11LM和VOCKQJK11LM）
• SONOFF传感器（SNZB-02）
• Shelly传感器（H&T wifi）
• Shelly电力传感器（3EM - 需启用KEEP_FULL_TOPIC）

指标转换示例

主题 'zigbee2mqtt/0x00157d00032b1234', 负载 '{"temperature":26.24,"humidity":45.37}'

将转换为：

mqtt_temperature{topic="zigbee2mqtt_0x00157d00032b1234"} 25.24
mqtt_humidity{topic="zigbee2mqtt_0x00157d00032b1234"} 45.37

功能特性

Zigbee2MQTT设备可用性支持

重要提示：不支持旧版可用性payload，必须禁用 - 参见设备可用性高级配置

当暴露设备可用性时，Zigbee2MQTT会在主题中添加/availability后缀，导致指标不一致：

mqtt_state{topic="zigbee2mqtt_garage_availability"} 1.0
mqtt_temperature{topic="zigbee2mqtt_garage"} 1.0

为避免同一设备出现不同主题，导出器提供默认禁用的规范化功能。可通过设置环境变量ZIGBEE2MQTT_AVAILABILITY="True"启用。

启用后将从主题中移除后缀并相应更改指标名称：

mqtt_zigbee_availability{topic="zigbee2mqtt_garage"} 1.0
mqtt_temperature{topic="zigbee2mqtt_garage"} 1.0

注意：不再保留mqtt_state指标名称，以减少冲突风险（因其过于通用）。

Zwavejs2Mqtt支持

此导出器还支持Zwavejs2Mqtt指标，建议使用"命名主题"（参见https://zwave-js.github.io/zwavejs2mqtt/#/usage/setup?id=gateway%EF%BC%89%E3%80%82

需通过环境变量ZWAVE_TOPIC_PREFIX指定Zwavejs2Mqtt使用的主题前缀（默认："zwave/"）。

ESPHome支持

仅当ESPHome使用默认state_topic：<TOPIC_PREFIX>/<COMPONENT_TYPE>/<COMPONENT_NAME>/state时支持（参见官方文档）。

需通过环境变量ESPHOME_TOPIC_PREFIXES指定ESPHome使用的主题前缀列表（默认：""，即禁用）。

这是一个列表，可设置一个或多个主题前缀，用逗号分隔。

示例：ESPHOME_TOPIC_PREFIXES="esphome-weather-indoor,esphome-weather-outdoor"

如果所有ESPHome主题共享同一前缀，可仅设置公共部分。例如，上述示例中使用"esphome"将匹配所有以"esphome"开头的主题。

Hubitat支持

支持Hubitat。默认情况下，所有以hubitat/开头的主题将被识别并解析为Hubitat消息。

主题格式如：hubitat/<hubname>/<device>/attributes/<attribute>/value。

与ESPHome类似，HUBITAT_TOPIC_PREFIXES是一个用,分隔的列表。

配置说明

参数通过环境变量传递。

参数列表：

• KEEP_FULL_TOPIC: 保留完整主题而非仅前两个元素。适用场景：Shelly 3EM（默认：False）
• LOG_LEVEL: 日志级别（默认：INFO）
• LOG_MQTT_MESSAGE: 记录MQTT原始消息，仅当LOG_LEVEL设为DEBUG时生效（默认：False）
• MQTT_IGNORED_TOPICS: 要忽略的主题列表，用逗号分隔，支持通配符（默认：无）
• MQTT_ADDRESS: MQTT代理的IP或主机名（默认：127.0.0.1）
• MQTT_PORT: MQTT代理的TCP端口（默认：1883）
• MQTT_TOPIC: 要订阅的主题（默认：#）
• MQTT_KEEPALIVE: MQTT连接的保活间隔（默认：60）
• MQTT_USERNAME: 用于MQTT代理认证的用户名（默认：无）
• MQTT_PASSWORD: 用于MQTT代理认证的密码（默认：无）
• MQTT_V5_PROTOCOL: 强制使用MQTT v5协议而非3.1.1
• MQTT_CLIENT_ID: 手动设置MQTT连接的客户端ID
• MQTT_EXPOSE_CLIENT_ID: 在Prometheus指标中暴露客户端ID作为标签
• PROMETHEUS_PORT: 暴露Prometheus指标的HTTP服务器端口（默认：9000）
• PROMETHEUS_PREFIX: 添加到指标名称的前缀，例如：mqtt_temperature（默认：mqtt_）
• TOPIC_LABEL: 定义Prometheus中主题的标签名，例如temperature{topic="device1"}（默认：topic）
• ZIGBEE2MQTT_AVAILABILITY: 规范化Zigbee2MQTT添加的设备可用性指标的传感器名称（默认：False）
• ZWAVE_TOPIC_PREFIX: Zwavejs2Mqtt消息使用的MQTT主题前缀（默认：zwave/）
• ESPHOME_TOPIC_PREFIXES: ESPHome消息使用的MQTT主题前缀列表（默认：""）
• HUBITAT_TOPIC_PREFIXES: Hubitat消息使用的MQTT主题前缀列表（默认："hubitat/"）

部署方法

使用Docker

交互式shell运行：

shell
docker run -it -p 9000:9000 -e "MQTT_ADDRESS=192.168.0.1" kpetrem/mqtt-exporter

如需容器在系统启动时自动启动（如服务器/树莓派）：

shell
docker run -d -p 9000:9000 --restart unless-stopped --name mqtt-exporter -e "MQTT_ADDRESS=192.168.0.1" kpetrem/mqtt-exporter

使用Docker Compose

yaml
version: "3"
services:
  mqtt-exporter:
    image: kpetrem/mqtt-exporter
    ports:
      - 9000:9000
    environment:
      - MQTT_ADDRESS=192.168.0.1
    restart: unless-stopped

在Prometheus中获取指标

以下是Prometheus配置示例，用于抓取指标：

scrape_configs:
  - job_name: mqtt-exporter
    static_configs:
      - targets: ["mqtt-exporter:9000"]

优化指标格式

如需更友好的指标名称，可在docker-compose.yml中如下配置：

yaml
version: "3"
services:
  mqtt-exporter:
    image: kpetrem/mqtt-exporter
    ports:
      - 9000:9000
    environment:
      - MQTT_ADDRESS=192.168.0.1
      - PROMETHEUS_PREFIX=sensor_
      - TOPIC_LABEL=sensor
    restart: unless-stopped

结果：

sensor_temperature{sensor="zigbee2mqtt_bedroom"} 22.3

通过Prometheus配置从sensor标签中移除zigbee2mqtt_前缀：

scrape_configs:
  - job_name: mqtt-exporter
    static_configs:
      - targets: ["mqtt-exporter:9000"]
    metric_relabel_configs:
      - source_labels: [sensor]
        regex: 'zigbee2mqtt_(.*)'
        replacement: '$1'
        target_label: sensor

优化后结果：

sensor_temperature{sensor="bedroom"} 22.3

完整部署示例

以下是典型监控栈的docker-compose示例，如需持久化指标，建议使用VictoriaMetrics等存储方案。

https://github.com/kpetremann/mqtt-exporter/blob/master/doc/example/docker-compose.yml

您还可添加其他工具，如Home-Assistant。