日志追踪

日志追踪用于收集 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 大小限制。
• 日志大小：已收集追踪日志的大小。
• 操作：可用操作，例如下载、停止或删除追踪任务。

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

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

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

查看追踪详情

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

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

如果部署包含多个 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：

   trace_client_001

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

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

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

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

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

   

第 3 步：验证追踪日志

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

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

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

   

   验证追踪日志时，请保持 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 限制。
• 停止或删除不再需要的追踪任务。