# 日志

日志用于排查设备智能体创建、设备接入、对话控制、IM 接入、语音和视觉等运行问题。你可以在控制台查看和筛选记录，也可以直接读取本地日志文件。

## 打开日志页面

在控制台左侧导航点击 **日志**，进入 `/workspace/logs`。页面主要分为两部分：

| 区域 | 用途 |
| --- | --- |
| 日志文件 | 查看当前可用的日志文件，文件名通常类似 `device-agent-2026-05-11.log`。 |
| 日志记录 | 查看选中文件里的最近记录，默认加载最近 200 条。 |

如果页面提示“文件日志已关闭”，点击右上角 **日志配置**，启用文件日志并保存。启用后，新记录会开始写入日志文件；启用前的历史记录不会补写。

![日志页面](../images/docs/operate-reference/logs/zh/01-logs-page.png)

## 本地日志文件

文件日志默认写入运行时目录下的 `logs` 子目录：

| 运行方式 | 默认目录 |
| --- | --- |
| 仓库源码开发 | `<repo>/.device_agent/logs` |
| 已安装的生产二进制 | `~/.device_agent/logs` |

Agent Gateway 启动时会打印 `Runtime Home`。`LOG_DIR=logs` 会相对这个目录解析；如果 `LOG_DIR` 是绝对路径，则直接写入该路径。注意目录名是 `.device_agent`。

同一天日志按大小切分，文件名如下：

```text
device-agent-2026-05-11.log
device-agent-2026-05-11.001.log
device-agent-2026-05-11.002.log
```

`device-agent-YYYY-MM-DD.log` 是当天第一个文件；超过 `LOG_MAX_SIZE_MB` 后继续写入 `.001.log`、`.002.log` 等分片。日志页面只列出符合这个命名规则的文件。

## 日志记录格式

日志文件是 JSON Lines，每行是一条完整 JSON 记录。

```json
{
  "time": "2026-05-11T05:20:12.123Z",
  "level": "info",
  "module": "MQTT",
  "msg": "device connected",
  "requestId": "req-...",
  "productId": "product-001",
  "deviceId": "device-001",
  "topic": "device-agent/product-001/device/device-001/out",
  "args": [{ "durationMs": 18 }]
}
```

常用字段如下：

| 字段 | 说明 |
| --- | --- |
| `time` | ISO 时间，始终按 UTC 写入。 |
| `level` | `debug`、`info`、`warn` 或 `error`。 |
| `module` | 产生日志的后端模块，例如 `Gateway`、`HTTP`、`MQTT`、`Agent`、`Tools`、`Skills`、`Voice`、`NTP`、`A2A-Channel`。 |
| `msg` | 日志消息。 |
| `requestId` / `sessionId` / `traceId` | 串联一次请求、对话或工具调用。 |
| `namespace` / `productId` / `deviceId` / `topic` | 定位租户、设备和 MQTT 主题。 |
| `method` / `path` / `statusCode` / `durationMs` | HTTP 或服务调用相关信息。 |
| `provider` / `tool` | 模型服务、语音服务或工具执行相关信息。 |
| `args` / `error` | 补充上下文和异常信息，已做脱敏和截断。 |

包含 `apiKey`、`authorization`、`cookie`、`password`、`secret`、`token`、`privateKey` 等敏感含义的字段会写成 `[redacted]`。普通业务数据不会自动移除，分享日志前仍要检查设备 ID、主题、状态值和第三方用户 ID。

## 本地排查命令

在源码开发环境中，从仓库根目录查看日志：

```bash
ls -lh .device_agent/logs
tail -n 200 .device_agent/logs/device-agent-2026-05-11.log
jq 'select(.level == "error")' .device_agent/logs/device-agent-2026-05-11.log
jq 'select(.deviceId == "device-001") | {time, level, module, msg, topic}' \
  .device_agent/logs/device-agent-2026-05-11.log
jq 'select(.requestId == "req-...")' .device_agent/logs/device-agent-2026-05-11.log
```

日志页面使用这些本地接口：

| 接口 | 用途 |
| --- | --- |
| `GET /api/logs/files` | 列出可读日志文件。 |
| `GET /api/logs/tail?file=device-agent-2026-05-11.log&lines=200` | 读取指定文件末尾记录，`lines` 最大为 `1000`。 |
| `GET /api/logs/tail?file=device-agent-2026-05-11.log&before=<offset>` | 继续读取更早记录，`before` 使用上一次响应里的 `nextBeforeOffset`。 |
| `GET /api/logs/download?file=device-agent-2026-05-11.log` | 下载指定日志文件。 |

## 查看和筛选记录

选中一个日志文件后，可以用以下方式定位问题：

| 操作 | 适合场景 |
| --- | --- |
| 刷新 | 设备刚上线、刚下发命令或刚完成一次对话后，刷新查看最新记录。 |
| 查看更早记录 | 当前 200 条不够时，继续加载更早的记录。 |
| 按级别筛选 | 只看 `warn` 或 `error`，快速定位异常。 |
| 按消息搜索 | 搜索错误关键词、平台名称、MQTT 主题或模型服务返回信息。 |
| 按模块筛选 | 只看某类能力的记录，例如 MQTT、HTTP、Voice、Tools、A2A。 |
| 按请求 ID 搜索 | 对一次 HTTP 请求、对话或工具调用做链路排查。 |
| 按设备 ID 搜索 | 只查看某台设备的上报、命令和响应记录。 |

每条记录都可以展开查看完整 JSON。需要分享单条记录时，点击右侧复制按钮；需要导出当前文件时，点击右上角下载按钮。

## 日志级别

| 级别 | 说明 |
| --- | --- |
| `debug` | 最详细，适合临时排查复杂问题。记录量较大，不建议长期打开。 |
| `info` | 默认推荐级别，记录启动、连接、请求和主要运行状态。 |
| `warn` | 只记录可能影响功能但未必导致失败的问题。 |
| `error` | 只记录失败和异常。 |

日常使用建议保持 `info`。如果某个问题难以复现，可以临时切到 `debug`，复现后再调回 `info`。

## 配置日志

在日志页面点击 **日志配置**，可以调整：

| 配置 | 作用 |
| --- | --- |
| 级别 | 控制记录多少日志。 |
| 控制台日志 | 是否在服务启动终端中输出日志。 |
| 文件日志 | 是否写入可在日志页面查看和下载的日志文件。 |
| 日志目录 | 文件日志保存位置。相对路径会放在设备智能体数据目录下。 |
| 单文件上限 | 单个日志文件达到上限后会自动切分。 |
| 保留天数 | 超过保留天数的旧日志会自动清理。 |
| 总容量上限 | 所有日志文件超过上限后，会优先删除更旧的文件。 |
| 文件日期时区 | 控制日志文件名按系统时区还是 UTC 日期生成。 |

保存后的日志配置会写入本地配置。`.env` 中的同名配置仍会在服务启动时覆盖控制台保存的值。

常用 `.env` 配置如下：

```bash
LOG_LEVEL=info
LOG_CONSOLE_ENABLED=true
LOG_FILE_ENABLED=true
LOG_DIR=logs
LOG_MAX_SIZE_MB=50
LOG_RETENTION_DAYS=14
LOG_MAX_TOTAL_SIZE_MB=1024
LOG_TIMEZONE=system
```

更多配置入口见 [配置](./configuration.md)。

## 常见排查路径

| 问题 | 建议查看 |
| --- | --- |
| 设备没有出现在列表中 | 按设备 ID 搜索，确认设备是否连接 MQTT、上报在线状态或遥测。 |
| 对话控制没有生效 | 搜索设备 ID 或请求 ID，查看命令是否下发、设备是否返回响应。 |
| IM 机器人没有回复 | 按模块或平台名称搜索，查看平台凭证、白名单、消息接收和回复是否正常。 |
| 语音没有识别或没有播报 | 按语音相关模块筛选，查看语音服务、会话和识别结果。 |
| 工具或技能没有执行 | 按工具相关模块筛选，查看工具加载、权限和执行结果。 |
| 模型服务返回异常 | 按 `error` 或模型服务名称搜索，查看请求失败、鉴权失败或超时信息。 |

下载或分享日志前，先确认日志中是否包含设备 ID、主题、状态值、第三方平台用户 ID 等敏感信息。常见密钥字段会被脱敏，但业务数据仍可能出现在日志消息中。