# 大量客户端离线告警处理指南

大量客户端离线告警表示在部署中，短时间内出现了大量客户端断开连接的情况。该告警仅在 **30 分钟前连接数不少于 100**，且**客户端离线比例超过设定阈值**时触发。

该情况通常意味着大量客户端在短时间内与 EMQX 断开连接。常见问题包括网络波动或区域性故障，以及客户端未正确实现自动重连机制。

## 网络波动导致客户端离线且未能自动重连

### 问题描述

由于网络抖动、区域性运营商故障或网络维护，可能导致客户端与 EMQX 的连接在短时间内大量中断。如果客户端未能正确实现自动重连机制，连接数会持续下降并触发大量客户端离线告警。

在部署的**监控**页面中，若观察到连接数曲线在短时间内大幅下降，且客户端离线情况集中分布在特定区域或运营商，则通常符合此类情况。

### 常见原因

- 网络抖动或区域性网络故障。  
- 客户端未实现或未正确实现自动重连机制。  

### 处理方法

- 确认客户端已正确实现自动重连机制，例如采用指数退避策略进行重连。  
- 与网络运营商确认是否存在网络波动或故障，必要时启用备用链路或跨区域灾备方案。  

## 集群变更或节点故障导致客户端掉线且无法重连

### 问题描述

在进行 EMQX 集群升级、扩容或维护时，可能会发生节点切换或节点重启，导致已连接到相关节点的客户端被强制断开。如果客户端未能及时自动重连，或集群在升级或维护过程中出现异常，可能导致大量客户端同时掉线并触发告警。

在部署的**监控**页面中，若发现客户端断开时间与节点状态变化（如重启、扩容或缩容）在时间上高度一致，则通常可以判断为此类情况。

### 常见原因

- 集群升级、扩容或维护过程中发生节点切换。  
- 节点故障导致连接中断。  
- 客户端自动重连机制不完善或重连失败。  

### 处理方法

- 在计划进行集群维护或升级前，关注 EMQX 发布的公告或通知，并提前做好客户端侧的准备。  
- 确认客户端具备稳定的自动重连机制，确保在节点重启或切换后能够快速恢复连接。  
- 如因集群变更或节点故障导致大量客户端离线，请立即提交紧急工单，与 EMQX 技术支持人员联系以获取协助。  

## 排查步骤

1. 登录 EMQX Cloud 控制台，进入部署。

2. 进入**告警** -> **告警列表**，确认是否存在大量客户端离线告警，并查看告警触发的时间段及其影响范围。

   ![clients_disconnect_alerts](./_assets/clients_disconnect_alerts.png)

3. 结合**监控** -> **指标** -> **时间轴** -> **连接数**，观察过去 30 分钟内客户端连接数是否从 100 个以上骤降，且下降幅度超过设定阈值。

   ![clients_disconnect_monitor](./_assets/clients_disconnect_monitor.png)

4. 对照告警触发时间，确认是否存在网络波动、区域性故障，或集群节点状态变化等情况。

## 监控与统计

在 **指标** -> **时间轴** -> **连接数**中，可以查看基于时间轴的整体客户端连接数趋势，用于持续观察客户端离线情况是否得到缓解。

## 客户端离线事件追踪说明

- EMQX Cloud 作为消息中间件，不会存储历史客户端信息，包括客户端历史离线时间及离线原因。  

- 若需要长期追踪客户端离线事件，可订阅事件主题 `$events/client_disconnected`，并结合规则引擎将事件转发或存储。  示例 SQL 如下：

  ```sql
  SELECT
      *
  FROM
      "$events/client_disconnected"
  ```

- 可进一步添加条件过滤，例如 `clientid`、`reason`、`disconnected_at` 等。参考：[SQL 数据源和字段](../../rule_engine/rule_engine_events.md#客户端连接断开事件-events-client-disconnected)。