# 部署日志

日志是排查问题和优化 EMQX 部署性能的重要工具。EMQX 部署日志记录了访问、操作和网络事件等信息。您可以通过 EMQX 控制台实时查看日志，或下载日志进行离线分析。

## 查看部署日志

要查看部署日志，您可以在 EMQX 控制台中进入您的部署，选择菜单中的**日志**，进入**日志**页面。

![view_log](./_assets/logs.png)

### 按时间筛选

日志页面默认显示过去 3 天的日志。您可以选择以下预设时间范围进行筛选：

- 最近 1 小时
- 最近 12 小时
- 最近 1 天

您也可以通过日历选择器自定义时间范围。但需注意：

- 每次最多可选择连续 3 天的日志。
- 最多可查看过去 14 天内的日志。

### 按日志级别筛选

部署日志根据严重程度分为以下 5 个级别：

- Warning（警告）
- Error（错误）
- Critical（严重错误）
- Alert（告警）
- Emergency（紧急）

您可以在下拉框中选择日志级别，并点击**搜索**按钮进行筛选。

### 按错误类型筛选

您可以根据以下错误类型进行日志筛选：

- **数据集成**：与数据集成相关的错误，例如 MySQL 未运行、授权失败或表结构错误等。
- **客户端**：与客户端相关的错误，包括认证信息错误、访问控制信息错误或其他无法连接的原因。
- **消息**：与消息相关的错误，例如编码问题、消息丢失或丢弃等。
- **认证**：认证错误，如无法连接到后端服务导致的扩展认证失败。
- **授限**：权限校验失败，如授权规则未正确生效。

### 按告警类型筛选

您可以通过**告警类型**下拉框，按告警类型对日志进行筛选。告警类型分为以下三个分类：

**认证与访问控制**

- 大量认证失败
- 大量 ACL 拒绝
- 外置认证模块状态异常
- 外置 ACL 模块状态异常
- 客户端因连接抖动而被暂时封禁

**客户端与消息**

- 消息丢失
- 大量客户端离线

**数据集成**

- 连接器状态异常
- SQL 匹配失败
- 动作执行失败
- 动作状态异常

### 按客户端 ID、IP 及更多条件筛选

您可以使用以下字段进行日志筛选：

- 客户端 ID
- 客户端 IP

此外，还可以通过**更多筛选**下拉框选择以下字段：

- 用户名
- 主题
- 连接器名称
- 动作名称
- 规则 ID

### AI 日志分析

针对单条日志，您可以点击日志条目中的 **AI 分析**按钮，获取 AI 生成的日志解读与处理建议，帮助您快速理解日志含义。

::: tip 注意

每个用户每小时最多可对 10 条不同日志发起 AI 分析。

:::

![logs_ai_analysis](./_assets/logs_ai_analysis.png)

### 重置与下载日志

- 点击**重置**可恢复默认日志视图。
- 点击**下载**可导出最多 1,000 条日志记录。

## 常见日志分析

本节汇总了 EMQX 中常见的 warning/error 日志类型，包含日志示例、问题成因及处理建议，便于运维和排查故障。

### 客户端连接与权限类日志

#### [Warning] 客户端认证失败

**日志示例：**
```
clientid: xx, peername: xxx:xx, username: 1, pid: <0.99601.0>, reason: not_authorized, tag: AUTHN, msg: authentication_failure
```
此日志代表未找到对应的 MQTT 用户名认证数据。

```
clientid: xx, peername: xxx:xx, username: test, pid: <0.15269.0>, reason: bad_username_or_password, tag: AUTHN, msg: authentication_failure
```
此日志代表找到对应的 mqtt 用户名认证数据，但是用户名对应的密码匹配失败。

**处理建议：** 检查客户端配置的用户名与密码是否正确。

#### [Warning] 客户端 ACL 授权失败

**日志示例：**

```
clientid: xx, peername: xxx:xx, username: test, topic: test, pid: <0.34387.0>, action: SUBSCRIBE(Q0), source: built_in_database, tag: AUTHZ, msg: authorization_permission_denied
```

**问题说明：**
客户端认证成功，但尝试订阅/发布无权限的主题，触发权限拒绝。

**处理建议：**

- 检查访问控制配置是否正确。
- 验证当前用户是否有访问指定主题的权限。

#### [Warning] 非标准 MQTT 协议连接失败

**日志示例：**

```
[MQTT] Parse failed for function_clause[{emqx_frame,parse_packet,[{mqtt_packet_header,4,false,3,true}
```

**问题说明：**
客户端连接时使用了非标准 MQTT 协议或数据格式错误。

**处理建议：**检查客户端连接使用的是否为标准 MQTT 协议（如 3.1.1 或 5.0）。

### 消息投递与流控类日志

#### [Warning] 消息被丢弃（队列已满）

**日志示例：**
```
clientid: xx, peername: xxx:xx, username: test, topic: test, pid: <0.198894.0>, payload: xxxxxxxxxx, payload_encode: hex, queue: {"store_qos0":true,"max_len":1000,"len":1000,"dropped":56942}, msg: dropped_msg_due_to_mqueue_is_full
```

**问题说明：**
由于客户端离线或消费能力不足，导致服务器端队列堆积，消息被丢弃。

**处理建议：**
1. 若客户端长时间离线：
   - 设置 `clean session = true`。
   - 启用自动重连功能，避免断线后会话丢失。
2. 若客户端消费能力不足：
   - 优化客户端 SDK，提升处理速率。
   - 使用共享订阅以分摊消息压力。

#### [Warning] TPS 超过限制

**日志示例：**
```
clientid: xx, peername: xxx:xx, username: test, topic: test, pid: <0.194662.0>, reason: {failed_to_consume_from_limiter,{{listener,'tcp:default'},messages}}, tag: QUOTA, msg: cannot_publish_to_topic_due_to_quota_exceeded
```

**问题说明：**
客户端的消息发布频率超过了部署设定的 TPS 限制。

**处理建议：**
- 调整客户端发布速率，使其低于部署设置的 TPS 限值。
- 或根据业务需求调整部署限速配置。

### 部署数据集成类日志

#### [Error] MySQL 连接器启动失败

**日志示例：**
```
[warning] tag: CONNECTOR/MYSQL, msg: start_resource_failed, reason: {start_pool_failed,<<"connector:mysql:test">>,{shutdown,#{cause => ehostunreach,port => 3306,user => <<"root">>,host => "xxx",database => <<"mqtt">>}}}, resource_id: <<"connector:mysql:test">>
```

**问题说明：**
MySQL 数据连接器初始化失败，可能是数据库连接配置不正确或数据库不可达。

**处理建议：**
- 检查 MySQL 服务状态及网络可达性。
- 检查 MySQL 连接器配置信息（主机、端口、用户名、数据库名等）是否正确。

#### [Error] HTTP 连接器启动失败

**日志示例：**
```
pid: <0.28885448.0>, line: 810, reason: timeout, resource_id: connector:http:c-xxX, tag: CONNECTOR/WEBHOOK, msg: start_resource_failed
```

**问题说明：**
Webhook 或 HTTP 类型连接器启动失败，通常为 HTTP 服务连接超时。

**处理建议：**
- 检查目标 HTTP 服务是否可访问。
- 检查 HTTP 连接器配置中的 URL、端口、认证信息等是否正确。

#### [Error] RocketMQ 连接器启动失败

**日志示例：**
```
[error] crasher: initial call: rocketmq_client:init/1, pid: <0.5161.0>, exit: {fail_to_connect_rocketmq_server,...}
[warning] tag: CONNECTOR/ROCKETMQ, msg: start_resource_failed, reason: {fail_to_connect_rocketmq_server,...}, resource_id: <<"connector:rocketmq:test">>
```

**问题说明：**
RocketMQ 客户端未能连接到目标服务，导致连接器初始化失败。

**处理建议：**
- 检查 RocketMQ 服务是否运行正常。
- 检查 RocketMQ 连接器配置中的地址、端口及权限信息是否正确。

#### [Error] Kafka 资源异常

**日志示例：**
```
topic: xxx, pid: <0.25097.0>, group: ..., reason: failed_to_fetch_metadata, msg: failed_to_refresh_partition_count_will_retry
topic: xxx, pid: <0.25048.0>, errors: [{"reason":"connection_timed_out","host":"xxx:xx"}], msg: failed_to_fetch_metadata
```

**问题说明：**
Kafka 连接器无法获取主题元数据，可能由于连接超时或 Kafka 集群配置错误。

**处理建议：**
- 检查 Kafka 服务可用性与网络连接情况。
- 确保动作中配置的 Kafka 主题已在 Kafka 中预先创建。

#### [Error] MQTT 资源异常

**日志示例：**
```
pid: <0.5959.0>, line: 59, reason: timeout, resource_id: connector:mqtt:c-xxx, tag: RESOURCE, msg: start_ecpool_error
pid: <0.5959.0>, line: 895, reason: timeout, resource_id: connector:mqtt:c-xxx, tag: CONNECTOR/MQTT, msg: start_resource_failed
```

**问题说明：**
MQTT 类型连接器初始化超时，可能为目标 MQTT 服务不可达或连接超时。

**处理建议：**
- 检查目标 MQTT Broker 状态及网络可达性。
- 检查 MQTT 连接器配置项（host、port、认证等）是否正确。