Eclipse Mosquitto与Grafana监控面板：可视化MQTT metrics

Eclipse Mosquitto与Grafana监控面板：可视化MQTT metrics

【免费下载链接】mosquitto Eclipse Mosquitto - An open source MQTT broker 项目地址: https://gitcode.com/gh_mirrors/mo/mosquitto

MQTT协议作为物联网通信的事实标准，其消息传输的稳定性与性能直接影响整个物联网系统的可靠性。Eclipse Mosquitto作为轻量级开源MQTT Broker（消息代理），被广泛应用于边缘设备和云端部署中。然而，默认配置下的Mosquitto缺乏直观的监控手段，难以实时掌握 broker 运行状态与消息流转情况。本文将详细介绍如何通过 Mosquitto 内置的 $SYS 系统主题收集关键指标，并结合 Grafana 构建可视化监控面板，帮助运维人员快速定位问题、优化系统性能。

Mosquitto监控指标来源

$SYS系统主题概述

Mosquitto 内置的 $SYS 主题树会自动发布 broker 运行状态信息，无需额外插件即可获取基础监控数据。通过订阅这些主题，可实时获取连接数、消息吞吐量、订阅数等关键指标。核心监控主题路径及说明如下：

主题路径	指标说明	数据类型
$SYS/broker/clients/connected	当前连接客户端数量	数值
$SYS/broker/messages/received	总接收消息数	累计值
$SYS/broker/messages/sent	总发送消息数	累计值
$SYS/broker/subscriptions/count	当前订阅总数	数值

配置文件 mosquitto.conf 中通过 sys_interval 参数控制指标更新频率，默认每10秒更新一次：

# Time in seconds between updates of the $SYS tree.
# Set to 0 to disable the publishing of the $SYS tree.
sys_interval 10

指标采集架构设计

典型的监控架构包含三个核心组件：

1. 数据采集层：通过 MQTT 客户端订阅 $SYS 主题，将指标转发至时序数据库（如 InfluxDB、Prometheus）
2. 数据存储层：时序数据库存储历史指标数据，支持高写入吞吐量与时间范围查询
3. 可视化层：Grafana 连接数据库，通过自定义面板展示实时与历史趋势

搭建监控数据 pipeline

配置Mosquitto启用指标发布

1. 编辑 Mosquitto 配置文件 mosquitto.conf，确保以下参数未被注释：

# 启用系统主题指标发布
sys_interval 10
# 允许匿名订阅（生产环境建议启用认证）
allow_anonymous true

2. 重启 Mosquitto 服务使配置生效：

systemctl restart mosquitto

3. 验证 $SYS 主题发布情况，使用内置客户端订阅测试：

mosquitto_sub -t '$SYS/#' -v

部署指标采集客户端

使用 Python 编写简易数据转发脚本，订阅 $SYS 主题并写入 InfluxDB。核心代码如下（完整实现可参考 examples/subscribe/basic-1.c 的订阅逻辑）：

import paho.mqtt.client as mqtt
from influxdb import InfluxDBClient

def on_message(client, userdata, msg):
    # 解析消息主题与 payload
    measurement = msg.topic.split('/')[-1]
    value = float(msg.payload)
    # 写入 InfluxDB
    json_body = [{
        "measurement": measurement,
        "fields": {"value": value}
    }]
    influx_client.write_points(json_body)

client = mqtt.Client()
client.on_message = on_message
client.connect("localhost", 1883, 60)
client.subscribe("$SYS/#")
client.loop_forever()

构建Grafana可视化面板

数据源头配置

1. 登录 Grafana 后，在 Configuration > Data Sources 中添加 InfluxDB 数据源
2. 配置数据库连接参数：
   • URL: http://influxdb:8086
   • Database: mosquitto_metrics
   • 认证信息（如已启用）

关键指标面板设计

1. 客户端连接监控

创建 Singlestat 面板展示当前连接数，设置阈值告警（如超过1000连接时变为红色）。查询语句：

SELECT last("value") FROM "connected" WHERE time > now() - 5m GROUP BY time(10s)

2. 消息吞吐量趋势

使用 Graph 面板展示每分钟消息收发量，配置双Y轴分别显示接收/发送消息数：

SELECT derivative(last("value"), 1m) FROM "received" WHERE $timeFilter GROUP BY time(1m)
SELECT derivative(last("value"), 1m) FROM "sent" WHERE $timeFilter GROUP BY time(1m)

3. 订阅分布热力图

通过 Heatmap 面板展示不同主题前缀的订阅数量分布，帮助识别热门主题：

SELECT count("value") FROM "subscriptions" GROUP BY "topic_prefix"

完整监控面板导入

Grafana 支持 JSON 格式的面板配置导入，以下是针对 Mosquitto 监控优化的面板结构（可导出为 JSON 文件保存）：

{
  "annotations": {
    "list": [
      {
        "builtIn": 1,
        "datasource": "-- Grafana --",
        "enable": true,
        "hide": true,
        "iconColor": "rgba(0, 211, 255, 1)",
        "name": "Annotations & Alerts",
        "type": "dashboard"
      }
    ]
  },
  "editable": true,
  "gnetId": null,
  "graphTooltip": 0,
  "id": 1,
  "iteration": 1629260173826,
  "links": [],
  "panels": [],
  "refresh": "10s",
  "schemaVersion": 27,
  "style": "dark",
  "tags": [],
  "templating": {
    "list": []
  },
  "time": {
    "from": "now-6h",
    "to": "now"
  },
  "timepicker": {
    "refresh_intervals": [
      "5s",
      "10s",
      "30s",
      "1m",
      "5m",
      "15m",
      "30m",
      "1h",
      "2h",
      "1d"
    ]
  },
  "timezone": "",
  "title": "Mosquitto MQTT监控",
  "uid": "mosquitto-dashboard",
  "version": 1
}

高级监控与性能优化

指标采集优化

1. 采样频率调整：根据业务需求修改 mosquitto.conf 中的 sys_interval 参数，平衡监控精度与系统开销：

# 生产环境建议设置为30秒
sys_interval 30

2. 主题过滤：通过客户端订阅时指定具体主题路径（而非通配符 #），减少不必要的网络传输：

mosquitto_sub -t '$SYS/broker/clients/connected' -t '$SYS/broker/messages/#'

常见问题排查

指标缺失问题

若 Grafana 面板显示无数据，可按以下步骤排查：

1. 检查 Mosquitto 运行状态：systemctl status mosquitto
2. 验证 $SYS 主题发布：使用 mosquitto_sub 直接订阅测试
3. 查看数据转发脚本日志，确认是否成功写入数据库
4. 检查数据库连接参数，使用 Grafana 的 "Test" 功能验证数据源连通性

性能瓶颈定位

当出现消息延迟或连接不稳定时，重点关注以下指标：

• $SYS/broker/messages/publish/dropped：消息丢弃数（非零表示系统过载）
• $SYS/broker/clients/disconnected：客户端断开连接数（突增可能暗示网络问题）
• $SYS/broker/load/messages/received/1min：每分钟接收消息量（峰值需与服务器性能匹配）

总结与扩展方向

通过本文介绍的方法，可快速搭建 Mosquitto 基础监控系统，实现客户端连接、消息吞吐量等核心指标的可视化。对于大规模部署场景，建议进一步扩展以下功能：

1. 告警机制：在 Grafana 中配置阈值告警，通过邮件、钉钉等渠道推送异常通知
2. 历史数据分析：结合 Prometheus + Alertmanager 实现长期指标存储与高级告警规则
3. 自定义指标：开发 Mosquitto 插件（参考 plugins/examples 目录）采集应用层自定义指标

完整的监控方案不仅能提升系统可靠性，还可为容量规划、性能优化提供数据支持，是物联网平台运维不可或缺的组成部分。

【免费下载链接】mosquitto Eclipse Mosquitto - An open source MQTT broker 项目地址: https://gitcode.com/gh_mirrors/mo/mosquitto