历史事件
历史事件是一种故障排查工具，用于记录 EMQX 部署中近期发生的客户端连接、认证和订阅事件。您可以使用历史事件排查连接失败、异常断开、认证失败和订阅未生效等问题。
历史事件适用于运行 EMQX v6.1.3 及以上版本的专有版和弹性专有版部署，不支持 Serverless 和 BYOC 部署。
历史事件适用场景
历史事件可以帮助您关联客户端生命周期中的不同事件。例如：
- 查看连接确认和认证完成事件，排查客户端连接失败的原因。
- 查看客户端断开连接事件的原因，排查客户端异常断开问题。
- 查看订阅成功和取消订阅事件，确认客户端使用的主题和 QoS。
- 比较事件时间，梳理客户端连接、认证和订阅操作的先后顺序。
历史事件会占用数据集成 TPS。客户端连接或重连越频繁，产生的事件越多，消耗的 TPS 也越高。启用历史事件前，请确保部署有足够的数据集成 TPS 余量。
启用历史事件
启用历史事件前，请确保满足以下条件：
- 部署处于运行中状态。
- 部署类型为专有版或弹性专有版。
- 部署运行 EMQX v6.1.3 或以上版本。
- 部署有足够的数据集成 TPS 余量。
按照以下步骤启用历史事件：
- 在 EMQX Cloud 控制台中进入目标部署。
- 在左侧导航栏中，点击诊断工具 -> 历史事件。
- 点击立即启用。
- 在确认对话框中，点击确认。
页面显示已启用状态，EMQX 开始记录支持的客户端生命周期事件，无需额外配置事件范围。历史事件仅记录启用后产生的事件，不会补录启用前发生的事件。
查找和查看事件
返回事件数量默认为 100 条。需要定位特定客户端或活动时，可以使用过滤条件缩小查询范围。每次查询都会读取部署中所有 EMQX 节点的本地事件日志，并聚合最新的匹配事件。
过滤事件
历史事件支持以下过滤条件和返回数量：
| 过滤条件 | 匹配方式 | 限制 |
|---|---|---|
| 客户端 ID | 包含匹配，区分大小写 | 最长 256 个字符 |
| 用户名 | 包含匹配，区分大小写 | 最长 256 个字符 |
| IP 地址 | 精确匹配 | 最长 256 个字符 |
| 主题 | 包含匹配，不使用 MQTT topic filter 语义 | 最长 256 个字符 |
| 事件类型 | 精确匹配 | 从列表中选择支持的事件类型 |
| 事件数量 | 返回事件数上限 | 100（默认）、500、1,000、5,000 或 10,000 |
按照以下步骤查询事件：
- 输入或选择一个或多个过滤条件。如需查询所有支持类型的近期事件，请将过滤条件全部留空。
- 选择最多返回的事件数量。
- 点击搜索图标。
- 查看返回的事件。点击事件左侧的展开图标，查看事件详情。
如需移除所有过滤条件，点击清空图标。如需使用现有过滤条件获取最新事件快照，点击刷新图标。
解读查询结果
事件列表显示以下信息：
- 时间：事件发生时间，精确到秒，并显示 UTC 偏移量。
- 事件类型：控制台中的事件名称，例如客户端连接成功、认证完成或订阅成功。
- 客户端 ID：客户端标识符。
- IP 地址：客户端 IP 地址和端口。如果端口信息不可用，则仅显示 IP 地址。
- 原因：事件结果或原因（如有）。例如，认证事件可能显示
success，断开连接事件可能显示internal_error等原因。
不同事件类型显示的详情不同，包括 用户名、主题、QoS、连接时间、协议名称 和 协议版本 等字段。空字段以及主列表中已有的字段不会重复显示。
查询结果在本地分页，每页显示 10 条事件。切换页码不会重新查询 EMQX。执行新搜索、清空过滤条件或刷新结果时，控制台会发送新查询并返回第 1 页。
支持的事件类型
事件类型列表包含以下客户端生命周期事件：
| 控制台事件类型 | 内部事件类型 | 说明 |
|---|---|---|
| 客户端连接成功 | client.connected | 客户端成功连接到 EMQX。 |
| 客户端断开连接 | client.disconnected | 客户端断开与 EMQX 的连接。排查异常断开时，请查看原因。 |
| 连接确认 | client.connack | EMQX 向客户端发送 CONNACK 报文。 |
| 认证完成 | client.check_authn_complete | 客户端认证流程结束。请查看原因获取认证结果。 |
| 订阅成功 | session.subscribed | 客户端订阅主题。展开事件可查看主题和 QoS。 |
| 取消订阅 | session.unsubscribed | 客户端取消订阅主题。展开事件可查看主题和 QoS。 |
历史事件不记录消息事件，例如 $events/message/delivery_dropped。
停用历史事件
按照以下步骤停用历史事件：
- 进入历史事件页面。
- 点击右上角的停用。
- 确认停用操作。
停用后，EMQX 不再记录新事件。已记录的事件不会立即删除，在磁盘日志轮转或 EMQX 节点替换前仍可能出现在查询结果中。您可以随时重新启用历史事件。
使用说明和限制
- 及时查询事件：历史事件使用本地磁盘日志，不保证固定的保留时长。实际可查询的时间范围取决于事件量、可用磁盘空间和日志轮转情况。
- 将每次查询视为独立快照：历史事件不支持服务端分页或时间范围查询。不同查询返回的结果是独立快照，数据可能不连续。
- 使用有针对性的过滤条件：历史事件适用于排查近期客户端活动。如需进行精确的多维度搜索，请使用 EMQX Tables。
- 避免频繁查询：每个部署在 60 秒内最多可查询 30 次历史事件，失败请求也计入限制。超过限制的请求将返回
429 Too Many Requests。 - 注意返回数量限制：单次查询最多返回 10,000 条事件。