# 日志追踪

日志追踪用于收集 EMQX Cloud 部署中特定 MQTT 客户端、主题、客户端 IP 或规则 ID 的 debug 级别日志。借助日志追踪，您无需为整个部署启用详细日志，即可排查客户端连接失败、意外断开连接、订阅失败、消息发布异常、消息丢失或规则执行错误等问题。

## 适用范围与限制

日志追踪仅适用于运行 EMQX v6.1.3 或更高版本的专有版和弹性专有版部署。如果您的部署不满足这些要求，EMQX Cloud 控制台的**诊断工具**菜单下不会显示**日志追踪**。

日志追踪存在以下限制：

- 每个部署最多可创建 10 个追踪任务。
- 每个追踪任务最多可运行 24 小时。
- 追踪名称必须以字母开头，可包含字母、数字、下划线 (`_`) 和连字符 (`-`)，最大长度为 256 个字符。
- Payload 限制最大可设置为 1 MB，默认值为 1024 B。

## 使用场景

当您需要检查特定排查对象在 Broker 端的详细处理过程时，可使用日志追踪。典型场景包括：

- 客户端无法连接、意外断开连接或认证失败。
- 客户端无法向主题发布消息或订阅主题。
- 消息已发布，但未按预期被接收。
- 规则未按预期处理消息。
- 需要对比多节点部署中不同 Broker 节点上的日志。

对于部署中的常规错误和警告，请使用**诊断工具** -> **日志**。如需针对特定客户端、主题、客户端 IP 或规则进行定向排查，请使用日志追踪。

## 创建追踪任务

1. 在 EMQX Cloud 控制台中进入您的部署。

2. 在部署菜单中选择**诊断工具** -> **日志追踪**。

3. 在**日志追踪**页面中点击**新建**。

4. 在**新建日志追踪**对话框中配置以下字段：

   | 字段 | 描述 |
   | --- | --- |
   | **名称** | 输入追踪任务名称。建议使用可识别排查对象的描述性名称。 |
   | **类型** | 选择追踪条件类型。支持**客户端 ID**、**主题**、**客户端 IP** 和**规则 ID**。 |
   | **客户端 ID** / **主题** / **客户端 IP** / **规则 ID** | 输入要追踪的值。字段标签将根据所选**类型**变化。 |
   | **时间范围** | 选择追踪任务的开始和结束时间，最长为 24 小时。 |
   | **Payload 编码** | 选择 EMQX Cloud 在追踪日志中写入消息 Payload 的方式。 |
   | **Payload 限制** | 设置追踪日志中打印的 Payload 最大字节数。Payload 超出此值时，EMQX Cloud 会将其截断。 |

5. 点击**确认**。

EMQX Cloud 会在配置的开始时间启动追踪，并在结束时间自动停止。您也可以在追踪列表中手动停止正在运行的追踪任务。

::: tip

请将开始时间设置在重现问题之前，并尽量缩短追踪时间范围。这样可以减小日志大小，也便于查看追踪结果。

:::

## 追踪类型

您可以基于以下条件类型创建追踪任务：

- **客户端 ID**：捕获特定 MQTT 客户端与 Broker 之间的交互。
- **主题**：捕获特定主题的发布、订阅和取消订阅事件。支持主题通配符。
- **客户端 IP**：捕获来自特定客户端 IP 的客户端与 Broker 之间的交互。
- **规则 ID**：捕获特定规则的执行日志，包括 SQL 执行和动作执行详情。

## Payload 编码选项

使用 **Payload 编码**控制追踪日志中消息 Payload 的写入方式：

- **Text**：将 Payload 写为文本。建议对纯文本或 JSON 编码的 Payload 使用此选项。
- **HEX**：将 Payload 写为十六进制值。建议对自定义二进制协议使用此选项。
- **Hidden**：将 Payload 掩码为 `******`。当 Payload 包含敏感信息时，请使用此选项。

**Payload 限制**仅在 **Payload 编码**设置为 **Text** 或 **HEX** 时生效。如果 Payload 超过配置的限制，EMQX Cloud 仅将允许的字节数写入追踪日志。

## 查看和管理追踪任务

**日志追踪**页面列出为部署创建的所有追踪任务。列表中包含以下信息：

- **名称**：追踪任务名称。点击名称可打开追踪详情。
- **类型**：追踪条件类型。
- **条件**：要追踪的值，例如客户端 ID、主题、客户端 IP 或规则 ID。
- **时间范围**：追踪任务的开始和结束时间。
- **状态**：追踪任务的状态，例如**运行中**或**已停止**。
- **Payload 编码**：所选的 Payload 编码方式。
- **Payload 限制**：配置的 Payload 大小限制。
- **日志大小**：已收集追踪日志的大小。
- **操作**：可用操作，例如下载、停止或删除追踪任务。

您可以通过追踪列表中的操作管理追踪日志：

- 点击追踪名称，打开追踪详情。
- 点击下载图标，下载已收集的追踪日志。
- 点击停止图标，在追踪任务到达结束时间前将其停止。
- 点击删除图标，删除不再需要的已停止追踪任务。

对于正在运行的追踪任务，您可以将其停止或下载日志；对于已停止的追踪任务，您可以下载日志或删除任务。

![日志追踪列表](./_assets/log_trace_list.png)

## 查看追踪详情

点击追踪名称，打开追踪详情页面。

追踪详情页面通过日志查看器显示收集到的追踪日志。根据被追踪的活动，每行日志会显示时间戳、协议或模块标签、客户端标识符、源地址、报文类型、主题、认证结果、授权结果或规则执行详情等信息。

如果部署包含多个 Broker 节点，追踪详情页面会提供节点选择器。默认情况下，页面会选择最近生成追踪日志的节点。您也可以手动选择其他节点以查看该节点上的日志。

您还可以在追踪详情页面执行以下操作：

- 刷新显示的追踪日志。
- 下载所选节点的追踪日志。
- 当部署包含多个节点时，切换到其他节点。

## 示例：追踪测试 MQTT 客户端

本示例介绍如何为测试客户端创建追踪任务、使用在线调试（内置 MQTT 客户端）生成 MQTT 流量，并验证生成的追踪日志。

### 第 1 步：创建客户端 ID 追踪任务

1. 进入**诊断工具** -> **日志追踪**。

2. 点击**新建**。

3. 使用以下值配置追踪任务：

   | 字段 | 值 |
   | --- | --- |
   | **名称** | `client_trace_test` |
   | **类型** | `客户端 ID` |
   | **客户端 ID** | `trace_client_001` |
   | **时间范围** | 选择约 30 分钟的时间范围。 |
   | **Payload 编码** | `Text` |
   | **Payload 限制** | `1024 B` 或 `1 KB` |

4. 点击**确认**。

追踪任务将显示在列表中。在所选时间范围内，其状态为**运行中**。

### 第 2 步：生成测试流量并触发追踪日志

将**诊断工具** -> **在线调试**中的内置 MQTT 客户端与日志追踪配合使用，可以在不使用外部 MQTT 客户端的情况下重现问题并生成追踪日志。

1. 进入**诊断工具** -> **在线调试**。

2. 使用以下任一方式连接到部署：

   - **使用自动生成的认证信息连接**：如果部署支持此选项，可用于快速测试。
   - **使用已添加的认证信息连接**：使用已在**访问控制** -> **认证**中配置的用户名和密码。

3. 确保 MQTT 客户端使用以下客户端 ID：

   ```text
   trace_client_001
   ```

   MQTT 客户端必须使用与追踪条件相同的客户端 ID 进行连接。

4. 在**消息**区域中，使用以下值发布测试消息：

   | 字段 | 值 |
   | --- | --- |
   | **主题** | `trace/test` |
   | **QoS** | `QoS 0` |
   | **Payload 格式** | `JSON` |
   | **Payload** | `{ "message": "hello" }` |

5. 点击**发布**。您可以多次发布消息，以生成更多追踪日志。

   MQTT 客户端页面会显示连接状态、发布主题、Payload 和已发送的消息。

   ![使用 MQTT 客户端生成日志追踪测试流量](./_assets/log_trace_mqtt_client_demo.png)

### 第 3 步：验证追踪日志

1. 返回**诊断工具** -> **日志追踪**。

2. 在追踪列表中检查 `client_trace_test` 追踪任务：

   - 如果追踪任务仍在所选时间范围内，请确认其**状态**为**运行中**。
   - 确认匹配的客户端产生流量后，**日志大小**有所增加。

   ![包含 MQTT 客户端面板的日志追踪列表](./_assets/log_trace_demo_trace_list.png)

   验证追踪日志时，请保持 MQTT 客户端面板打开。您可以点击**断开连接**停止测试客户端，或点击**编辑**更新连接设置，以便使用其他客户端 ID 重新连接。

3. 点击 `client_trace_test`，打开追踪详情。

4. 检查追踪日志。本示例的日志可能包括以下条目：

   - MQTT 连接报文，例如 `CONNECT` 和 `CONNACK`。
   - 发布到 `trace/test` 主题的消息，例如 `PUBLISH` 报文。
   - 认证和授权结果。
   - Keep Alive 报文，例如 `PINGREQ` 和 `PINGRESP`。

5. 如果部署包含多个 Broker 节点，请使用节点选择器切换节点并查看特定节点的日志。

6. 点击刷新图标重新加载显示的日志，或点击下载图标下载追踪日志。

完成测试后，请返回追踪列表。如果追踪任务仍在运行，请将其停止。下载所需日志后，可以删除已停止的追踪任务。

## 最佳实践

- 使用范围尽可能小的追踪条件，减少日志量。
- 重现问题时，使用较短的时间范围。
- 如果 Payload 可能包含敏感信息，请将 **Payload 编码**设置为 **Hidden**。
- 仅在需要检查较大 Payload 时增加 **Payload 限制**。
- 停止或删除不再需要的追踪任务。