# 历史事件

历史事件是一种故障排查工具，用于记录 EMQX 部署中近期发生的客户端连接、认证和订阅事件。您可以使用历史事件排查连接失败、异常断开、认证失败和订阅未生效等问题。

历史事件适用于运行 EMQX v6.1.3 及以上版本的专有版和弹性专有版部署，不支持 Serverless 和 BYOC 部署。

## 历史事件适用场景

历史事件可以帮助您关联客户端生命周期中的不同事件。例如：

- 查看**连接确认**和**认证完成**事件，排查客户端连接失败的原因。
- 查看**客户端断开连接**事件的原因，排查客户端异常断开问题。
- 查看**订阅成功**和**取消订阅**事件，确认客户端使用的主题和 QoS。
- 比较事件时间，梳理客户端连接、认证和订阅操作的先后顺序。

历史事件会占用数据集成 TPS。客户端连接或重连越频繁，产生的事件越多，消耗的 TPS 也越高。启用历史事件前，请确保部署有足够的数据集成 TPS 余量。

## 启用历史事件

启用历史事件前，请确保满足以下条件：

- 部署处于运行中状态。
- 部署类型为专有版或弹性专有版。
- 部署运行 EMQX v6.1.3 或以上版本。
- 部署有足够的数据集成 TPS 余量。

按照以下步骤启用历史事件：

1. 在 EMQX Cloud 控制台中进入目标部署。
2. 在左侧导航栏中，点击**诊断工具** -> **历史事件**。
3. 点击**立即启用**。
4. 在确认对话框中，点击**确认**。

页面显示**已启用**状态，EMQX 开始记录支持的客户端生命周期事件，无需额外配置事件范围。历史事件仅记录启用后产生的事件，不会补录启用前发生的事件。

## 查找和查看事件

返回事件数量默认为 100 条。需要定位特定客户端或活动时，可以使用过滤条件缩小查询范围。每次查询都会读取部署中所有 EMQX 节点的本地事件日志，并聚合最新的匹配事件。

### 过滤事件

历史事件支持以下过滤条件和返回数量：

| 过滤条件 | 匹配方式 | 限制 |
| --- | --- | --- |
| **客户端 ID** | 包含匹配，区分大小写 | 最长 256 个字符 |
| **用户名** | 包含匹配，区分大小写 | 最长 256 个字符 |
| **IP 地址** | 精确匹配 | 最长 256 个字符 |
| **主题** | 包含匹配，不使用 MQTT topic filter 语义 | 最长 256 个字符 |
| **事件类型** | 精确匹配 | 从列表中选择支持的事件类型 |
| 事件数量 | 返回事件数上限 | `100`（默认）、`500`、`1,000`、`5,000` 或 `10,000` |

按照以下步骤查询事件：

1. 输入或选择一个或多个过滤条件。如需查询所有支持类型的近期事件，请将过滤条件全部留空。
2. 选择最多返回的事件数量。
3. 点击搜索图标。
4. 查看返回的事件。点击事件左侧的展开图标，查看事件详情。

如需移除所有过滤条件，点击清空图标。如需使用现有过滤条件获取最新事件快照，点击刷新图标。

![过滤和查询事件](./_assets/event-history-query.png)

### 解读查询结果

事件列表显示以下信息：

- **时间**：事件发生时间，精确到秒，并显示 UTC 偏移量。
- **事件类型**：控制台中的事件名称，例如**客户端连接成功**、**认证完成**或**订阅成功**。
- **客户端 ID**：客户端标识符。
- **IP 地址**：客户端 IP 地址和端口。如果端口信息不可用，则仅显示 IP 地址。
- **原因**：事件结果或原因（如有）。例如，认证事件可能显示 `success`，断开连接事件可能显示 `internal_error` 等原因。

不同事件类型显示的详情不同，包括 **用户名**、**主题**、**QoS**、**连接时间**、**协议名称** 和 **协议版本** 等字段。空字段以及主列表中已有的字段不会重复显示。

![查看事件详情](./_assets/event-history-event-details.png)

查询结果在本地分页，每页显示 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`。

## 停用历史事件

按照以下步骤停用历史事件：

1. 进入**历史事件**页面。
2. 点击右上角的**停用**。
3. 确认停用操作。

停用后，EMQX 不再记录新事件。已记录的事件不会立即删除，在磁盘日志轮转或 EMQX 节点替换前仍可能出现在查询结果中。您可以随时重新启用历史事件。

## 使用说明和限制

- **及时查询事件**：历史事件使用本地磁盘日志，不保证固定的保留时长。实际可查询的时间范围取决于事件量、可用磁盘空间和日志轮转情况。
- **将每次查询视为独立快照**：历史事件不支持服务端分页或时间范围查询。不同查询返回的结果是独立快照，数据可能不连续。
- **使用有针对性的过滤条件**：历史事件适用于排查近期客户端活动。如需进行精确的多维度搜索，请使用 EMQX Tables。
- **避免频繁查询**：每个部署在 60 秒内最多可查询 30 次历史事件，失败请求也计入限制。超过限制的请求将返回 `429 Too Many Requests`。
- **注意返回数量限制**：单次查询最多返回 10,000 条事件。