> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/console/logs-viewer · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 日志查看器

日志页展示每个 API 请求的完整记录：客户端请求、上游转发、响应、错误详情。支持实时流式推送、持久化存储和日志体查看。

入口：控制台 → **日志**（admin、monitor 可见）。

日志体存储的字段参考与环境变量见 [日志与日志体存储](/zh-CN/reference/logs-and-body-storage.md)。

## 日志列表

列表展示最近的请求记录，每条包含：

| 字段 | 说明 |
|------|------|
| 时间 | 请求时间戳 |
| 模型 | 请求的模型名；模型名前可挂标签标识路由来源（见下） |
| 上游 | 实际处理该请求的上游名 |
| 路径 | 客户端请求的端点路径（如 `/v1/chat/completions`） |
| 状态码 | 上游响应状态码 |
| 延迟 | 总耗时（毫秒） |
| 用户 | 访问密钥名（未认证显示 `anonymous`） |
| 输入 Token | prompt token 数 |
| 输出 Token | completion token 数 |

模型列的标签：

| 标签 | 含义 |
|------|------|
| `MM` | 该请求的模型名经**身份作用域模型映射**规则改写（访问密钥/组的 `model_mappings`）。tooltip 显示 `原名 → 映射名`。若同时命中负载均衡或脚本改路，`MM` 与对应标签叠加显示 |
| `LB` | 该请求经**负载均衡**虚拟路由派发到某上游节点 |
| `SW` | 该请求的上游模型被脚本 `context.useModel()` 改路 |

普通请求无标签。`MM` 与 `LB`/`SW` 可叠加（`MM` 在前）；`LB` 与 `SW` 互斥（脚本改路优先）。

## 日志详情

点击某条日志展开详情抽屉（标题含处理该请求的实例 ID，多实例部署时便于定位），包含完整的请求/响应生命周期。抽屉右上角有**下载日志**按钮，把该条日志（请求/响应全文）导出为文件下载（大 body 由 worker 线程格式化，不卡页面）：

| 标签 | 内容 |
|------|------|
| 概览 | 请求 ID、模型、上游 URL、状态码、延迟、token 用量、访问密钥名/组；模型映射 / 负载均衡信息条（命中时展示） |
| 客户端请求 | 请求头（敏感值脱敏）+ 请求体 |
| 上游请求 | 转换后的请求头 + 请求体（发给上游的实际内容） |
| 上游响应 | 响应状态码 + 响应头 + 响应体 |
| 错误 | 4xx/5xx 时的错误详情（截断至 512 字节） |

### 通知（Notification）

日志详情页顶部展示该请求的特殊通知，例如：
- **script_use_model_swap（`SW`）**：该请求的上游模型是脚本经 `context.useModel` 切换的，非客户端原始请求的模型。这是**管理员配置的内部改路**，目标不过模型访问控制。

注意 `SW` 与模型列的 `MM` 是两种机制：`MM` 表示**身份映射**把客户端发的模型名按访问密钥/组的映射规则改写（见 [身份作用域模型映射配置](/zh-CN/howto/configure-identity-model-mapping.md)）；`SW` 表示脚本改路。两者可同时出现在同一请求上。

## 实时日志（SSE 流）

控制台右上角有 **Live 日志开关**。打开后，所有请求实时推送到浏览器：

- 使用 SSE（Server-Sent Events）传输
- 包含所有请求（401/429 早期失败、内部端点、控制台路由）
- 未认证请求显示 `user: "anonymous"`
- 多实例部署时（Redis 模式），汇聚所有实例的请求日志

关闭 Live 时是轮询刷新；打开时是实时推送。

## 过滤与搜索

日志页支持以下过滤方式：

| 过滤方式 | 说明 |
|---------|------|
| 时间范围 | 选择起止时间 |
| 模型 | 按模型名过滤 |
| 上游 | 按上游名过滤 |
| 路径 | 按请求端点路径过滤 |
| 状态码 | 按响应状态码过滤，语法见下 |
| 访问密钥 | 按密钥名过滤 |
| 搜索 | 按请求 ID 或其他关键字搜索 |

**状态码筛选语法**：不止 `2xx/4xx/5xx`，支持五种形态——精确值（`200`）、状态类（`5xx`）、比较（`>=400`、`>200`）、区间（`200-299`）、取反（`!2xx`）。多个条件用空格或逗号分隔，组合语义是：正向条件（不带 `!`）之间为 **OR**，负向条件（带 `!`）之间为 **AND**，两组再取 AND。例：`5xx !500` = 5xx 但不含 500；`200 201` = 200 或 201。

## 请求 ID 关联

每个请求都有唯一的 `z-request-id` 头（格式 `<iso8601>-<uuid4>`），该 ID：

- 在请求进入处理流程前注入到请求头
- 镜像到响应头返回给客户端
- 作为额外头转发给上游
- 嵌入所有结构化日志条目

在日志页搜索框输入完整请求 ID 即可定位特定请求。详见 [导出账单 Excel 与日志排查](/zh-CN/howto/billing-export-and-logs.md)。

## 常见问题

**Q：日志列表是实时的吗？**
打开 Live 开关后是实时推送（SSE）。关闭 Live 时是轮询刷新。

**Q：为什么日志里的 body 被截断了？**
每个 body 的捕获大小跟随准入上限：请求体按 `server.max_request_size_mb` 截断，响应体按 `server.max_response_body_mb` 截断。大 body（如长对话、大型 embedding 请求）会被截断。调大这些上限可捕获更多，但增加内存和磁盘开销。详见 [日志与日志体存储](/zh-CN/reference/logs-and-body-storage.md)。

**Q：流式请求的响应体在哪看？**
流式响应的 body 在流结束后由后台任务记录。如果流异常中断（客户端断连），body 可能不完整（标记 `body_incomplete`）。

**Q：日志太多，磁盘快满了怎么办？**
调小 `log_retention_days`（如 3 天）加速清理；调小 `stream_body_max_disk_mb` 减少流式 body 磁盘占用。详见 [日志与日志体存储](/zh-CN/reference/logs-and-body-storage.md)。

**Q：谁能看日志？**
日志页对 admin 与 monitor 可见。`normal_user` 不能登录控制台，也就看不到日志（它只有 API key 的使用权）。

**Q：日志和审计日志有什么区别？**
日志（本章）记录每次 API 调用的请求/响应；审计日志（[审计与安全配置](/zh-CN/reference/audit-and-security-config.md)）记录控制台配置变更（增/删/改）。两者互补。

**下一步**：[统计](/zh-CN/console/statistics.md) 看用量统计；[日志与日志体存储](/zh-CN/reference/logs-and-body-storage.md) 看字段与配置参考；[总览仪表板](/zh-CN/console/overview-dashboard.md) 看全局概览。