Loading... # EMQX 监控指标完整指南 # 一、概述 ## 1. 简介 ### A. 是什么 EMQX 监控指标是一套用于监控 EMQX 消息服务器运行状态的数据采集系统。通过调用 EMQX Dashboard API，可以获取节点状态、客户端连接、消息流量、订阅关系等关键指标，并以 Prometheus 格式输出，便于接入监控平台如 Grafana、Prometheus 等。 ### B. 为什么需要 EMQX 作为物联网消息中间件，承载着设备连接和数据转发的重要任务。通过监控指标可以： - 实时掌握集群健康状态 - 及时发现性能瓶颈 - 快速定位故障原因 - 评估系统容量规划 ### C. 学完能做什么 - 部署 EMQX 监控采集脚本 - 理解各项监控指标的含义 - 配置 Grafana 监控面板 - 建立告警规则保障系统稳定 ## 2. 前置知识 ### A. 必备技能 - 基本 Linux 命令操作 - 了解 MQTT 协议基础概念 - 熟悉 Prometheus 监控体系 ### B. 推荐知识 - Categraf 采集器使用 - Grafana 面板配置 - Shell 脚本基础 # 二、环境准备 ## 1. 系统要求 - EMQX 5.x 版本 - Linux 操作系统（Ubuntu、CentOS 等） - 具备访问 EMQX Dashboard API 的权限 - 已安装 Categraf 或其他 Prometheus 兼容的采集器 ## 2. 组件说明 监控脚本通过调用 EMQX RESTful API 获取数据，主要涉及以下端点： - /api/v5/nodes：获取节点基础信息 - /api/v5/metrics：获取详细指标数据 - /api/v5/clients：获取客户端统计 - /api/v5/subscriptions：获取订阅统计 - /api/v5/topics：获取 Topic 统计 ## 3. 认证配置 EMQX API 使用 HTTP Basic Authentication，需要提供 API Key 和 Secret： ```bash export EMQX_API_KEY="your_api_key" export EMQX_API_SECRET="your_api_secret" export EMQX_API_URL="http://emqx-server:18083/api/v5/nodes" ``` # 三、监控架构 ## 1. 数据采集流程 ```mermaid graph LR A[Categraf] -->|定时执行| B[监控脚本] B -->|HTTP请求| C[EMQX API] C -->|JSON响应| B B -->|Prometheus格式| D[采集器] D -->|推送| E[后端存储] ```  ## 2. 指标分类体系 EMQX 监控指标按功能划分为 8 大类： ```mermaid mindmap root((EMQX监控指标)) 节点基础 连接数 内存使用 系统负载 进程状态 客户端 连接统计 认证状态 授权记录 消息 收发统计 QoS分布 丢弃率 数据包 包类型统计 传输状态 会话 创建终止 状态管理 订阅 订阅数量 创建统计 Topic 活跃数量 分布统计 字节 流量统计 带宽使用 ```  # 四、指标详解 ## 1. 节点基础指标 节点基础指标反映 EMQX 集群中每个节点的运行状态，是监控系统最核心的部分。 ### A. 连接类指标 | 指标名称 | 指标类型 | 说明 | |---------|---------|------| | emqx_connections | gauge | 当前连接数，反映当前客户端连接总数 | | emqx_live_connections | gauge | 活跃连接数，排除空闲连接 | | emqx_cluster_sessions | gauge | 集群会话总数，跨节点的会话汇总 | ### B. 系统资源指标 | 指标名称 | 指标类型 | 说明 | |---------|---------|------| | emqx_load1 | gauge | 系统 1 分钟平均负载 | | emqx_load5 | gauge | 系统 5 分钟平均负载 | | emqx_load15 | gauge | 系统 15 分钟平均负载 | | emqx_memory_used | gauge | 已使用内存（字节）| | emqx_memory_total | gauge | 总内存（字节）| | emqx_process_used | gauge | Erlang 进程已使用数 | | emqx_process_available | gauge | Erlang 进程可用数 | ### C. 运行状态指标 | 指标名称 | 指标类型 | 说明 | |---------|---------|------| | emqx_uptime | gauge | 节点运行时长（秒）| | emqx_max_fds | gauge | 最大文件描述符数 | | emqx_node_status | gauge | 节点状态，1 表示运行，0 表示停止 | ## 2. 客户端指标 客户端指标用于监控连接到 EMQX 的设备状态和认证情况。 ### A. 连接统计 | 指标名称 | 指标类型 | 说明 | |---------|---------|------| | emqx_clients_count | gauge | 当前连接的客户端总数 | | emqx_clients_connected_total | counter | 累计连接的客户端数，自节点启动以来 | | emqx_clients_disconnected_total | counter | 累计断开的客户端数 | ### B. 认证授权 | 指标名称 | 指标类型 | 说明 | |---------|---------|------| | emqx_clients_authenticate_total | counter | 认证请求总数 | | emqx_clients_auth_success_total | counter | 认证成功总数 | | emqx_clients_auth_failure_total | counter | 认证失败总数，可用于安全审计 | ## 3. 订阅指标 订阅指标反映客户端对 Topic 的订阅情况。 | 指标名称 | 指标类型 | 说明 | |---------|---------|------| | emqx_subscriptions_count | gauge | 当前订阅总数 | | emqx_subscriptions_created_total | counter | 累计创建订阅数 | ## 4. Topic 指标 Topic 指标用于监控消息主题的使用情况。 | 指标名称 | 指标类型 | 说明 | |---------|---------|------| | emqx_topics_count | gauge | 当前活跃 Topic 总数 | ## 5. 消息指标 消息指标是监控 EMQX 消息流转的核心指标，反映系统的消息处理能力。 ### A. 消息总体统计 | 指标名称 | 指标类型 | 说明 | |---------|---------|------| | emqx_messages_received_total | counter | 接收消息总数 | | emqx_messages_sent_total | counter | 发送消息总数 | | emqx_messages_publish_total | counter | 发布消息总数 | | emqx_messages_acked_total | counter | 已确认消息总数 | | emqx_messages_delivered_total | counter | 已投递消息总数 | ### B. 消息丢弃统计 | 指标名称 | 指标类型 | 说明 | |---------|---------|------| | emqx_messages_dropped_total | counter | 丢弃消息总数，需重点关注 | | emqx_messages_dropped_no_subscribers_total | counter | 因无订阅者而丢弃的消息数 | ### C. QoS 级别消息统计 | 指标名称 | 指标类型 | 说明 | |---------|---------|------| | emqx_messages_qos0_received_total | counter | 接收的 QoS0 消息数，最多一次 | | emqx_messages_qos0_sent_total | counter | 发送的 QoS0 消息数 | | emqx_messages_qos1_received_total | counter | 接收的 QoS1 消息数，至少一次 | | emqx_messages_qos1_sent_total | counter | 发送的 QoS1 消息数 | ### D. 消息转发 | 指标名称 | 指标类型 | 说明 | |---------|---------|------| | emqx_messages_forward_total | counter | 转发消息总数，集群场景下重要 | ## 6. 数据包指标 数据包指标反映 MQTT 协议层的传输情况。 | 指标名称 | 指标类型 | 说明 | |---------|---------|------| | emqx_packets_received_total | counter | 接收数据包总数 | | emqx_packets_sent_total | counter | 发送数据包总数 | | emqx_packets_publish_received_total | counter | 接收的 PUBLISH 包数 | | emqx_packets_publish_sent_total | counter | 发送的 PUBLISH 包数 | ## 7. 会话指标 会话指标反映 MQTT 会话的生命周期管理。 | 指标名称 | 指标类型 | 说明 | |---------|---------|------| | emqx_sessions_created_total | counter | 创建会话总数 | | emqx_sessions_terminated_total | counter | 终止会话总数 | ## 8. 字节传输指标 字节指标反映网络带宽使用情况。 | 指标名称 | 指标类型 | 说明 | |---------|---------|------| | emqx_bytes_received_total | counter | 接收字节总数 | | emqx_bytes_sent_total | counter | 发送字节总数 | # 五、快速部署 ## 1. 部署监控脚本 ### A. 创建脚本目录 ```bash mkdir -p /opt/categraf/conf/input.exec cd /opt/categraf/conf/input.exec ``` ### B. 编写监控脚本 将 emqx_monitor.sh 脚本放置到指定目录，并赋予执行权限： ```bash chmod +x /opt/categraf/conf/input.exec/emqx_monitor.sh ``` ### C. 配置环境变量 编辑配置文件 /opt/categraf/conf/input.exec/emqx_monitor.conf： ```bash export EMQX_API_KEY="your_api_key" export EMQX_API_SECRET="your_api_secret" export EMQX_API_URL="http://10.10.74.101:18083/api/v5/nodes" export EMQX_MIDD_PROJECT="new-iot" export EMQX_MIDD_TYPE="emqx" ``` ## 2. 配置 Categraf 编辑 Categraf 配置文件 /opt/categraf/conf/input.exec/exec.toml： ```toml [[instances]] commands = [ "/opt/categraf/conf/input.exec/emqx_monitor.sh" ] data_format = "prometheus" prometheus_ignore_timestamp = true ``` ## 3. 测试验证 ### A. 手动执行脚本 ```bash /opt/categraf/conf/input.exec/emqx_monitor.sh ``` 预期输出：Prometheus 格式的指标数据 ### B. Categraf 测试 ```bash /opt/categraf/categraf -inputs exec -test -debug ``` 预期输出：解析后的指标数据 # 六、告警规则建议 ## 1. 核心告警指标 | 告警名称 | 指标 | 触发条件 | 严重级别 | |---------|------|---------|---------| | 节点宕机 | emqx_node_status | 值为 0 | 严重 | | 连接数过高 | emqx_connections | 超过阈值 | 警告 | | 消息丢弃率 | emqx_messages_dropped_total | 增长率异常 | 警告 | | 认证失败 | emqx_clients_auth_failure_total | 短时间大量失败 | 严重 | | 内存使用率 | emqx_memory_used | 超过 80% | 警告 | ## 2. 告警规则示例 ```yaml groups: - name: emqx_alerts rules: - alert: EMQXNodeDown expr: emqx_node_status == 0 for: 1m labels: severity: critical annotations: summary: "EMQX 节点宕机" - alert: EMQXHighConnectionCount expr: emqx_connections > 10000 for: 5m labels: severity: warning annotations: summary: "连接数超过阈值" ``` # 七、常见问题 ## 1. 脚本执行问题 ### A. 权限不足 现象：脚本无法执行 解决：检查脚本执行权限 `chmod +x emqx_monitor.sh` ### B. API 认证失败 现象：返回 401 或 403 错误 解决：检查 API Key 和 Secret 是否正确 ## 2. 指标采集问题 ### A. 指标缺失 现象：部分指标没有数据 解决：确认 EMQX 版本是否支持对应指标 ### B. 数据格式错误 现象：Categraf 无法解析 解决：检查 data_format 配置是否为 prometheus ## 3. 性能问题 ### A. 采集频率过高 现象：频繁调用 API 影响性能 解决：调整采集间隔，建议 15 秒以上 ### B. 超时问题 现象：脚本执行超时 解决：增加 CURL_TIMEOUT 参数值 # 八、最佳实践 ## 1. 监控体系设计 ```mermaid graph TB A[EMQX 集群] --> B[监控采集] B --> C[Prometheus] C --> D[Grafana] D --> E[可视化面板] C --> F[告警规则] F --> G[告警通知] ```  ## 2. 面板设计建议 - 概览面板：展示核心指标趋势 - 节点面板：分节点展示详细信息 - 业务面板：按业务维度统计消息量 ## 3. 告警分级 - 严重告警：立即处理，如节点宕机 - 警告告警：关注处理，如连接数偏高 - 提示告警：记录分析，如偶发认证失败 *** ## 参考资料 1. [EMQX 官方文档 - API](https://docs.emqx.com/) 2. [Categraf 使用指南](https://github.com/flashcatcloud/categraf) 3. [Prometheus 监控最佳实践](https://prometheus.io/docs/practices/) 最后修改：2026 年 04 月 15 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏