大量客户端取消订阅告警处理指南
大量客户端取消订阅告警表示在部署中，短时间内出现了大量客户端取消订阅主题的情况。该告警仅在 30 分钟前订阅数不少于 100，且取消订阅比例超过设定阈值时触发。
该情况通常意味着客户端发生了批量取消订阅行为，可能导致消息无法正常推送至订阅端。常见问题包括客户端异常断开连接、客户端重新连接后未重新订阅，或客户端取消订阅相关逻辑存在缺陷。
客户端异常断连导致取消订阅
问题描述
由于网络抖动、区域性运营商故障或网络维护，可能导致客户端与 EMQX Cloud 的连接在短时间内大量中断。如果客户端未正确实现会话保留和自动重连机制，其已有订阅关系可能会被取消，从而触发大量客户端取消订阅告警。
在部署监控页面中，若观察到客户端连接数和主题订阅数在短时间内同时大幅下降，则通常符合此类情况。
常见原因
- 网络抖动或区域性网络故障导致客户端大量断连。
- 客户端未实现会话保留机制，断线后订阅关系无法保留。
- 客户端未实现或未正确实现自动重连逻辑。
处理方法
- 确认客户端已正确实现会话保留和自动重连机制，确保断线后能够及时恢复连接，并保持订阅关系。
- 在启用会话保留的场景下，确保
clientid固定，避免因重连导致clientid变化而丢失订阅。
客户端 SDK 或 API 调用问题
问题描述
当订阅数量在短时间内显著下降，但客户端连接数保持相对稳定时，通常表明客户端仍然在线，但订阅被主动取消。该情况可能由客户端 SDK 的默认行为缺陷，或应用层错误调用 API（例如批量调用 unsubscribe 接口）导致。
在部署监控页面中，若观察到取消订阅数量大幅上升，但连接数维持稳定，并且客户端日志中在相同时间段出现批量 unsubscribe 或异常重连行为，则可能与客户端逻辑或 SDK 问题有关。
常见原因
- 客户端代码逻辑存在缺陷，出现重复订阅后又取消订阅，但未执行重新订阅。
- 第三方 SDK 在处理 Clean Session 或持久会话参数时存在兼容性问题。
- 应用层误用批量
unsubscribe接口，导致订阅被集中清空。
处理方法
- 检查客户端代码逻辑，确认不存在“重复订阅后取消订阅但未重新订阅”的问题。
- 如使用第三方 SDK，建议升级至最新版本，并重点排查其在 Clean Session 和持久会话参数处理上的行为。
- 在业务代码中避免不必要的批量
unsubscribe或清空全部订阅的调用；如确有需要，需确保后续resubscribe能够正确执行。
排查步骤
登录 EMQX Cloud 控制台。
进入部署告警 -> 告警列表，确认是否存在大量客户端取消订阅告警，并查看告警触发的时间范围及其影响规模。
结合监控 -> 指标 -> 时间轴 -> 订阅数，确认过去 30 分钟内订阅数量是否从 100 个以上骤降，且下降幅度超过设定阈值。
对照告警触发时间，结合客户端日志和应用行为，判断是异常断连导致的被动取消，还是客户端主动调用取消订阅接口导致。
监控与统计
在指标 -> 时间轴 -> 订阅数中，可以查看基于时间轴的整体订阅数量变化趋势，用于持续观察取消订阅情况是否得到缓解。
客户端取消订阅事件追踪说明
EMQX Cloud 不存储历史客户端订阅变更信息。若需要长期追踪客户端取消订阅行为，可订阅事件主题
$events/session_unsubscribed，并结合规则引擎将事件转发或存储。 示例 SQL 如下：sqlSELECT * FROM "$events/session_unsubscribed"可进一步添加条件过滤，例如
clientid、topic等。参考：SQL 数据源和字段。该规则仅在客户端主动取消订阅时触发；若因客户端断连导致订阅被动取消，则不会生成该事件。