tg44/mqtt-prometheus-message-exporter

MQTT Prometheus Message Exporter

镜像概述和主要用途

MQTT Prometheus Message Exporter是一个轻量级服务，用于将MQTT消息转换为Prometheus可识别的监控指标。它能够订阅MQTT主题，解析JSON格式的消息内容，通过自定义模式语法提取数值型数据，并生成符合Prometheus规范的指标，便于用户对物联网设备、传感器等产生的MQTT数据进行统一监控和分析。

核心功能和特性

路径生成

• 订阅指定MQTT主题，解析JSON格式消息
• 对JSON对象进行展平处理，生成"路径+值"的键值对
• 支持数据类型转换：
  • JSON数字：直接保留原值
  • JSON布尔值：转换为0（false）或1（true）
  • JSON字符串：若符合https://yaml.org/type/bool.html%EF%BC%8C%E8%BD%AC%E6%8D%A2%E4%B8%BA0/1
• 自动丢弃以下数据：
  • JSON null值
  • 无法转换为布尔值的字符串
  • JSON数组

示例：
主题为my/thermostat，消息内容为：

json
{
  "num": 10,
  "inner": {
    "num": 5,
    "bool": false
  },
  "so": {
    "deep": {
      "really": {
        "really": 8
      }
    }
  }
}

生成路径：

"my/thermostat/num" -> 10, 
"my/thermostat/inner/num" -> 5, 
"my/thermostat/inner/bool" -> 0, 
"my/thermostat/so/deep/really/really" -> 8

模式到Prometheus指标的转换

通过以下操作符将路径匹配并转换为Prometheus指标：

• [[prefix]]：将匹配的路径段用作指标名称
• [[prefixes]]：仅用于尾部，将所有剩余路径段用作指标名称
• [[any]]：匹配任意路径段并忽略
• <<label>>：创建标签，标签名为label，值为路径段内容

示例：
针对路径my/thermostat/so/deep/really/really：

• 模式my/[[prefix]]/so/deep/really/really → 指标名thermostat
• 模式my/<<device>>/[[prefix]]/deep/really/[[prefix]] → 指标名so_really，标签{device=thermostat}
• 模式my/<<device>>/[[prefix]]/deep/[[prefixes]] → 指标名so_really_really，标签{device=thermostat}

订阅优化语法

通过|符号优化MQTT订阅范围：

• 模式my/<<device>>/[[prefix]]/deep/[[prefixes]] → 订阅my/#
• 模式my/<<device>>/[[prefix]]/|/deep/[[prefixes]] → 订阅my/+/+（限制路径段数量）

使用场景和适用范围

• 物联网设备监控：将传感器（温度、湿度、压力等）通过MQTT发送的数据转换为Prometheus指标
• MQTT消息数据可视化：结合Grafana等工具实现MQTT数据的实时监控面板
• 设备状态追踪：通过转换布尔型状态消息（如设备在线/离线）实现设备状态监控

使用方法和配置说明

配置文件

需提供配置文件定义MQTT连接参数、指标转换模式等。配置示例可参考项目的example.conf。

核心配置项：

• mqtt.broker：MQTT broker地址（必填）
• mqtt.port：MQTT端口（必填）
• mqtt.username/mqtt.password：MQTT认证信息（可选，不填则***连接）
• mqtt.useTls：是否启用TLS（可选，默认false）
• mqtt.maxPacketSize：最大数据包大小（可选，默认4096）
• patterns：指标转换模式列表（必填，每个模式需包含pattern和namePrefix）
• selfMetrics：是否启用服务自身监控指标（可选，用于监控服务 uptime 等）

Docker部署示例

Docker Compose配置

yaml
mqtt-prom-exp:
  restart: unless-stopped
  image: tg44/mqtt-prometheus-message-exporter
  volumes:
    - /path/to/your/exporter.conf:/app/exporter.conf
  ports:
    - "9324:9000"  # 宿主机端口:容器内端口（容器内默认9000）
  environment:
    - CONF_PATH=/app/exporter.conf  # 配置文件路径

直接运行Docker命令

bash
docker run -p 9324:9000 \
  -v ${PWD}/exporter.conf:/app/exporter.conf \
  -e CONF_PATH=/app/exporter.conf \
  tg44/mqtt-prometheus-message-exporter

指标访问

部署后，Prometheus指标可通过 http://<主机IP>:9324/metrics 访问。

其他注意事项

• 所有模式需配置namePrefix，确保指标名称唯一（如iot_pressure而非pressure）
• 特殊字符会从主题名或JSON键中移除，空路径段会被丢弃
• 空格会转换为下划线（_）
• 主题名和JSON键在指标名称和标签中会自动转为小写
• 避免在主题名或JSON键中使用/、|以及<<、>>、[[prefix]]、[[prefixes]]等特殊字符串
• JSON键或主题名中的[[prefix]]和[[prefixes]]会被直接用作指标名的一部分

贡献

若对功能、配置或模式语法有改进建议，可通过GitHub提交issue或PR进行讨论。

Prometheus exporter实现

本项目使用自定义的Prometheus exporter库，详情可参考 https://github.com/tg44/prometheus-scala-exporter%E3%80%82