# Broker 健康指标

本页精选了用于监控 EMQX broker 的最常用 Prometheus 指标。请配合 [集成 Prometheus](./prometheus.md) 一起使用，后者介绍了如何暴露和抓取这些指标。

本页将健康指标分为四个领域：

1. **系统（System）**：操作系统和 Erlang 虚拟机资源。
2. **Broker**：连接与消息流量，以及 broker 状态。
3. **认证与授权（Authentication and Authorization）**：连接时的身份校验和每条消息的 ACL 决策。
4. **数据集成（Data Integration）**：规则、动作、连接器和桥接。

所有指标都通过 EMQX 的 Prometheus 端点（`/api/v5/prometheus/stats`、`/api/v5/prometheus/auth` 与 `/api/v5/prometheus/data_integration`）暴露。端点详情以及 `mode` 查询参数请参见 [集成 Prometheus](./prometheus.md#配置-pull-模式集成)。

::: tip 关于采集器默认值

带 `emqx_` 前缀的指标始终启用。带 `erlang_vm_` 前缀的、更丰富的 Erlang VM 指标来自上游 Prometheus Erlang exporter，在 EMQX 6.0 及更新版本中**默认关闭**。如需进程数、按分配器拆分的内存或 GC 和调度器统计等指标，可将 `prometheus.collectors.vm_system_info`、`vm_memory`、`vm_statistics` 设置为 `enabled`。

:::

## 系统

最贴近硬件层的信号。broker 出现异常时，这一类指标通常最先发生变化。

### CPU

| 指标 | 说明 |
|------|------|
| `emqx_vm_cpu_use` | CPU 使用率（百分比）。 |
| `emqx_vm_cpu_idle` | CPU 空闲率（百分比）。 |

### 内存

| 指标 | 说明 |
|------|------|
| `emqx_vm_total_memory` | 系统总内存（字节）。 |
| `emqx_vm_used_memory` | 系统已用内存（字节）。 |
| `erlang_vm_memory_processes` | 按分配器拆分的内存：进程（需启用 `vm_memory` 采集器）。 |
| `erlang_vm_memory_atom` | 按分配器拆分的内存：原子。 |
| `erlang_vm_memory_binary` | 按分配器拆分的内存：二进制数据。 |
| `erlang_vm_memory_ets` | 按分配器拆分的内存：ETS 表。 |
| `erlang_vm_memory_code` | 按分配器拆分的内存：已加载代码。 |
| `erlang_vm_memory_system` | 按分配器拆分的内存：系统开销。 |

### 文件描述符

| 指标 | 说明 |
|------|------|
| `emqx_vm_max_fds` | broker 进程的软 FD 上限（ulimit）。 |

### Erlang 进程与调度器负载

| 指标 | 说明 |
|------|------|
| `emqx_vm_run_queue` | 当前调度器运行队列长度。长期不为零表示 CPU 饱和。 |
| `emqx_vm_process_messages_in_queues` | 所有 Erlang 进程邮箱长度之和。数值持续偏大或增长，表明某个进程处理不过来。 |
| `erlang_vm_process_count` | 当前 Erlang 进程数（需启用 `vm_system_info` 采集器）。 |
| `erlang_vm_process_limit` | 配置的 Erlang 进程数上限。 |

### 内部邮箱看门狗

| 指标 | 说明 |
|------|------|
| `emqx_vm_mnesia_tm_mailbox_size` | Mnesia 事务管理器邮箱深度。偏大表示事务竞争。 |
| `emqx_vm_broker_pool_max_mailbox_size` | broker 派发进程池中最大的邮箱长度。偏大表示订阅侧出现背压。 |

### 运行时长

| 指标 | 说明 |
|------|------|
| `emqx_vm_uptime_ms` | broker 已运行时间（毫秒）。突然降到很小的值意味着节点重启。 |

### 集群复制健康（Mria）

| 指标 | 说明 |
|------|------|
| `emqx_mria_lag` | 每个 replicant 节点的复制延迟。 |
| `emqx_mria_replicants` | replicant 节点数量。 |
| `emqx_mria_bootstrap_time` | 最近一次引导所用时间。 |
| `emqx_mria_message_queue_len` | Mria 邮箱长度。 |

### 过载保护

| 指标 | 说明 |
|------|------|
| `emqx_overload_protection_new_conn` | 因过载而被拒绝的连接数。 |
| `emqx_overload_protection_gc` | 过载保护强制触发的 GC 次数。 |
| `emqx_overload_protection_hibernation` | 触发的进程休眠次数。 |
| `emqx_overload_protection_delay_ok` | 成功施加延迟的次数。 |
| `emqx_overload_protection_delay_timeout` | 延迟尝试超时的次数。 |

## Broker

核心运行指标。重点关注消息相关计数器的速率，尤其注意各 `dropped` 序列。

### 集群拓扑

| 指标 | 说明 |
|------|------|
| `emqx_cluster_nodes_running` | 集群中正在运行的节点数。 |
| `emqx_cluster_nodes_stopped` | 集群中已停止的节点数。大于零时应报警。 |
| `emqx_conf_sync_txid` | 最近一次应用的集群配置事务 ID。各节点之间不一致表示同步异常。 |

### License（企业版）

| 指标 | 说明 |
|------|------|
| `emqx_license_expiry_at` | License 过期时间（UNIX epoch 秒）。 |
| `emqx_license_issued_at` | License 签发时间。 |
| `emqx_license_max_sessions` | License 允许的最大会话数。 |
| `emqx_cert_expiry_at` | 监听器证书过期时间。 |

### 连接、会话与 Channel

| 指标 | 说明 |
|------|------|
| `emqx_connections_count` | 当前连接数。 |
| `emqx_connections_max` | 启动以来连接数峰值。 |
| `emqx_live_connections_count` | 当前已建立（TCP 在线）的客户端数量。 |
| `emqx_live_connections_max` | 在线连接峰值。 |
| `emqx_sessions_count` | 活跃会话数（包含客户端当前已断开的持久会话）。 |
| `emqx_sessions_max` | 会话峰值。 |
| `emqx_cluster_sessions_count` | 集群范围内的会话数。 |
| `emqx_cluster_sessions_max` | 集群范围内会话峰值。 |
| `emqx_channels_count` | Channel 进程数（每个已连接客户端对应一个）。 |
| `emqx_channels_max` | Channel 数量峰值。 |

### 订阅与主题

| 指标 | 说明 |
|------|------|
| `emqx_subscriptions_count` | 订阅数。 |
| `emqx_subscriptions_max` | 订阅数峰值。 |
| `emqx_subscriptions_shared_count` | 共享订阅数。 |
| `emqx_subscriptions_shared_max` | 共享订阅数峰值。 |
| `emqx_subscribers_count` | 订阅者进程数。 |
| `emqx_topics_count` | 不同主题数。 |
| `emqx_topics_max` | 主题数峰值。 |
| `emqx_routes_count` | 路由表大小。 |
| `emqx_routes_max` | 路由表大小峰值。 |
| `emqx_durable_subscriptions_count` | 持久会话订阅数。 |
| `emqx_durable_subscriptions_max` | 持久会话订阅数峰值。 |

### 保留、延迟与禁用列表

| 指标 | 说明 |
|------|------|
| `emqx_retained_count` | 保留消息数。 |
| `emqx_retained_max` | 保留消息数峰值。 |
| `emqx_delayed_count` | 延迟发布队列长度。 |
| `emqx_delayed_max` | 延迟队列长度峰值。 |
| `emqx_banned_count` | 被禁用的客户端 / 用户名 / IP 条目数。 |

### 消息

| 指标 | 说明 |
|------|------|
| `emqx_messages_received` | 从客户端收到的应用层消息数。 |
| `emqx_messages_sent` | 发送给客户端的应用层消息数。 |
| `emqx_messages_publish` | 已分发的 PUBLISH 报文数。 |
| `emqx_messages_delivered` | 投递给订阅者的次数（一条消息可能产生多次投递）。 |
| `emqx_messages_acked` | 收到的订阅者确认数。 |
| `emqx_messages_forward` | 跨节点转发的消息数。 |
| `emqx_messages_retained` | 保留消息事件数。 |
| `emqx_messages_delayed` | 延迟发布入队次数。 |

### 消息丢弃（最早出现的异常信号）

| 指标 | 说明 |
|------|------|
| `emqx_messages_dropped` | 丢弃消息总数。 |
| `emqx_messages_dropped_expired` | 因超过消息过期时间被丢弃。 |
| `emqx_messages_dropped_no_subscribers` | 因没有匹配订阅者被丢弃。 |
| `emqx_messages_dropped_quota_exceeded` | 因触发每客户端配额被丢弃。 |
| `emqx_messages_dropped_receive_maximum` | 因订阅者 MQTT v5 的 receive-maximum 配额被丢弃。 |

### 单订阅者投递丢弃

| 指标 | 说明 |
|------|------|
| `emqx_delivery_dropped` | 投递丢弃总数。 |
| `emqx_delivery_dropped_expired` | 投递前消息已过期。 |
| `emqx_delivery_dropped_no_local` | MQTT v5 No-Local 规则。 |
| `emqx_delivery_dropped_qos` | 不支持的 QoS。 |
| `emqx_delivery_dropped_queue_full` | 订阅者的消息队列已满。 |
| `emqx_delivery_dropped_too_large` | 超出订阅者允许的最大报文大小。 |

### 字节

| 指标 | 说明 |
|------|------|
| `emqx_bytes_received` | 累计接收字节数。 |
| `emqx_bytes_sent` | 累计发送字节数。 |

### 报文层（适用于协议级排查仪表盘）

| 指标 | 说明 |
|------|------|
| `emqx_packets_received` | 累计收到报文数。 |
| `emqx_packets_sent` | 累计发送报文数。 |
| `emqx_packets_connect` | 收到的 CONNECT 报文数。 |
| `emqx_packets_connack_sent` | 发送的 CONNACK 报文数。 |
| `emqx_packets_connack_error` | 带非零 Reason Code 的 CONNACK 数（大多数单客户端 AUTHN 失败会在此体现）。 |
| `emqx_packets_disconnect_received` | 收到的 DISCONNECT 报文数。 |
| `emqx_packets_disconnect_sent` | 发送的 DISCONNECT 报文数。 |
| `emqx_packets_publish_received` | 收到的 PUBLISH 报文数。 |
| `emqx_packets_publish_sent` | 发送的 PUBLISH 报文数。 |
| `emqx_packets_publish_error` | 未能被接收的 PUBLISH 数。 |
| `emqx_packets_publish_auth_error` | 被授权拒绝的 PUBLISH 数。 |
| `emqx_packets_puback_received` | 收到的 PUBACK 报文数（QoS 1）。 |
| `emqx_packets_puback_sent` | 发送的 PUBACK 报文数（QoS 1）。 |
| `emqx_packets_pubrec_received` | 收到的 PUBREC 报文数（QoS 2）。 |
| `emqx_packets_pubrec_sent` | 发送的 PUBREC 报文数（QoS 2）。 |
| `emqx_packets_pubrel_received` | 收到的 PUBREL 报文数（QoS 2）。 |
| `emqx_packets_pubrel_sent` | 发送的 PUBREL 报文数（QoS 2）。 |
| `emqx_packets_pubcomp_received` | 收到的 PUBCOMP 报文数（QoS 2）。 |
| `emqx_packets_pubcomp_sent` | 发送的 PUBCOMP 报文数（QoS 2）。 |
| `emqx_packets_subscribe_received` | 收到的 SUBSCRIBE 报文数。 |
| `emqx_packets_suback_sent` | 发送的 SUBACK 报文数。 |
| `emqx_packets_subscribe_error` | 处理失败的 SUBSCRIBE 数。 |
| `emqx_packets_subscribe_auth_error` | 被 AUTHZ 拒绝的 SUBSCRIBE 数。 |
| `emqx_packets_unsubscribe_received` | 收到的 UNSUBSCRIBE 报文数。 |
| `emqx_packets_unsuback_sent` | 发送的 UNSUBACK 报文数。 |
| `emqx_packets_unsubscribe_error` | 处理失败的 UNSUBSCRIBE 数。 |
| `emqx_packets_pingreq_received` | 收到的 PINGREQ 报文数。 |
| `emqx_packets_pingresp_sent` | 发送的 PINGRESP 报文数。 |

### 客户端生命周期（钩子触发计数）

| 指标 | 说明 |
|------|------|
| `emqx_client_connect` | 收到 CONNECT。 |
| `emqx_client_connack` | 已发送 CONNACK。 |
| `emqx_client_connected` | 触发了 `client.connected` 钩子。 |
| `emqx_client_disconnected` | 触发了 `client.disconnected` 钩子。 |
| `emqx_client_disconnected_reason` | 按原因聚合的断开次数。 |
| `emqx_client_subscribe` | 订阅钩子触发数。 |
| `emqx_client_unsubscribe` | 取消订阅钩子触发数。 |

### 会话生命周期

| 指标 | 说明 |
|------|------|
| `emqx_session_created` | 创建的会话数。 |
| `emqx_session_resumed` | 恢复的持久会话数。 |
| `emqx_session_takenover` | 被新客户端接管的会话数。 |
| `emqx_session_discarded` | 被丢弃的会话数（Clean Start 覆盖已有会话）。 |
| `emqx_session_terminated` | 已终止的会话数。 |

## 认证与授权

当 HTTP、LDAP 或数据库后端处于认证链路上时，可通过这些指标判断是 broker 还是后端出现了性能瓶颈或故障。

### 连接时认证结果

| 指标 | 说明 |
|------|------|
| `emqx_authentication_success` | 认证成功次数（不含匿名通过）。 |
| `emqx_authentication_success_anonymous` | 匿名通过次数。 |
| `emqx_authentication_failure` | 认证失败次数。 |

### 授权决策

| 指标 | 说明 |
|------|------|
| `emqx_authorization_allow` | 决策为 allow 的次数。 |
| `emqx_authorization_deny` | 决策为 deny 的次数。 |
| `emqx_authorization_nomatch` | 没有匹配规则的次数（退回到 `no_match` 配置）。 |
| `emqx_authorization_matched_allow` | 命中 allow 规则的次数。 |
| `emqx_authorization_matched_deny` | 命中 deny 规则的次数。 |
| `emqx_authorization_cache_hit` | 缓存命中次数。 |
| `emqx_authorization_cache_miss` | 缓存未命中次数。 |
| `emqx_authorization_superuser` | 超级用户旁路次数。 |

### 认证链状态

| 指标 | 说明 |
|------|------|
| `emqx_authn_total` | 已配置的认证 provider 数量。 |
| `emqx_authn_enable` | 每个 provider 的启用标志（0 / 1）。 |
| `emqx_authn_status` | 每个 provider 的资源状态。 |
| `emqx_authn_users_count` | 每个 provider 的用户记录数（适用于密码、mnesia 或基于数据库的 provider）。 |

### 认证 Provider 运行时计数

| 指标 | 说明 |
|------|------|
| `emqx_authn_success` | 每个 provider 命中成功的次数。 |
| `emqx_authn_failed` | 每个 provider 失败的次数。 |
| `emqx_authn_nomatch` | 每个 provider 选择忽略的次数（链路继续向下匹配）。 |
| `emqx_authn_latency` | 每个 provider 的后端延迟。 |

### 授权数据源状态

| 指标 | 说明 |
|------|------|
| `emqx_authz_total` | 已配置的授权数据源数量。 |
| `emqx_authz_enable` | 每个数据源的启用标志（0 / 1）。 |
| `emqx_authz_status` | 每个数据源的资源状态。 |
| `emqx_authz_rules_count` | 每个数据源的规则记录数（适用于文件、mnesia 或基于数据库的数据源）。 |

### 授权数据源运行时计数

| 指标 | 说明 |
|------|------|
| `emqx_authz_allow` | 每个数据源决策为 allow 的次数。 |
| `emqx_authz_deny` | 每个数据源决策为 deny 的次数。 |
| `emqx_authz_nomatch` | 每个数据源选择忽略的次数（链路继续向下匹配）。 |
| `emqx_authz_latency` | 每个数据源的后端延迟。 |

### 内置数据库规模

| 指标 | 说明 |
|------|------|
| `emqx_authn_builtin_record_count` | 内置认证数据库中的用户数。 |
| `emqx_authz_builtin_record_count` | 内置授权数据库中的规则数。 |

## 数据集成

流量进入规则引擎，扇出到动作和连接器，最终落到外部系统。每一层都暴露各自的计数器，按顺序读取可以定位消息在哪一层流失。

### 资源清单

| 指标 | 说明 |
|------|------|
| `emqx_rules_count` | 已配置的规则数。 |
| `emqx_actions_count` | 已配置的动作数。 |
| `emqx_connectors_count` | 已配置的连接器数。 |
| `emqx_schema_registrys_count` | Schema Registry 条目数。 |

### 单资源状态

| 指标 | 说明 |
|------|------|
| `emqx_rule_enable` | 规则启用标志（0 / 1）。 |
| `emqx_action_enable` | 动作启用标志（0 / 1）。 |
| `emqx_action_status` | 动作资源状态。 |
| `emqx_connector_enable` | 连接器启用标志（0 / 1）。 |
| `emqx_connector_status` | 连接器资源状态。 |

### 规则引擎：单规则计数

| 指标 | 说明 |
|------|------|
| `emqx_rule_matched` | 命中规则 WHERE 子句的消息数。 |
| `emqx_rule_passed` | 通过规则的消息数。 |
| `emqx_rule_failed` | 规则处理失败次数。 |
| `emqx_rule_failed_exception` | 规则执行中抛出 Erlang 异常的次数。 |
| `emqx_rule_failed_no_result` | SQL 没有产生结果的次数。 |

### 规则引擎：动作子计数

| 指标 | 说明 |
|------|------|
| `emqx_rule_actions_total` | 规则触发的动作调用总数。 |
| `emqx_rule_actions_success` | 动作返回成功的次数。 |
| `emqx_rule_actions_failed` | 动作失败次数。 |
| `emqx_rule_actions_failed_unknown` | 未知原因失败次数。 |
| `emqx_rule_actions_failed_out_of_service` | 下游资源不健康次数。 |
| `emqx_rule_actions_discarded` | 动作被丢弃次数（例如被限流）。 |

### 动作吞吐

| 指标 | 说明 |
|------|------|
| `emqx_action_matched` | 路由到该动作的消息数。 |
| `emqx_action_received` | 进入动作队列的次数。 |
| `emqx_action_success` | 动作调用成功次数。 |
| `emqx_action_failed` | 动作调用失败次数。 |
| `emqx_action_late_reply` | 响应在超时之后才到达的次数。 |
| `emqx_action_retried` | 重试次数。 |
| `emqx_action_retried_success` | 重试后成功的次数。 |
| `emqx_action_retried_failed` | 重试用尽仍失败的次数。 |

### 动作队列与在飞请求

| 指标 | 说明 |
|------|------|
| `emqx_action_inflight` | 正在处理的请求数。 |
| `emqx_action_queuing` | 队列中（等待派发）的请求数。 |

### 动作丢弃

任一序列出现非零速率，说明下游系统不健康或动作配置有误。

| 指标 | 说明 |
|------|------|
| `emqx_action_dropped` | 动作层丢弃总数。 |
| `emqx_action_dropped_queue_full` | 触发队列上限。 |
| `emqx_action_dropped_resource_stopped` | 目标资源已停止。 |
| `emqx_action_dropped_resource_not_found` | 目标资源缺失。 |
| `emqx_action_dropped_expired` | 派发前消息已过期。 |
| `emqx_action_dropped_other` | 其他原因。 |

## 最小化的”Broker 异常“面板

如果 Grafana 仪表盘只能展示少量曲线，优先选择以下这几条。大多数生产问题发生后几秒内，其中至少一条会出现明显波动：

- `rate(emqx_messages_dropped[1m])`：不为零说明 broker 在拒绝或丢弃工作。
- `rate(emqx_action_dropped[1m])`：数据集成层在丢弃工作。
- `emqx_cluster_nodes_stopped`：大于零说明有节点掉线。
- `rate(emqx_overload_protection_new_conn[1m])`：broker 正在主动拒绝新连接。
- `rate(emqx_authentication_failure[1m])`：速率突增通常意味着后端异常或受到攻击。
- `emqx_vm_run_queue`：持续大于零说明 CPU 饱和。
- `emqx_vm_process_messages_in_queues`：数值偏大说明进程邮箱出现积压。
- `emqx_mria_lag`：持续超过几秒说明复制开始落后。
- `emqx_license_expiry_at - time()`（企业版）：License 到期倒计时。