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


# 日志与日志体存储

日志页展示每个 API 请求的完整记录：客户端请求、上游转发、响应、错误详情。支持实时流式推送、持久化存储和日志体查看。UI 视角的日志列表/详情/SSE 实时流见 [日志查看器](/zh-CN/console/logs-viewer.md)。

## 日志体（Request/Response Body）

每个请求的请求体和响应体在日志中被捕获，可在详情页查看：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `LOG_BODY_TO_TERMINAL` | `false` | 是否将 body 记录到终端输出 |
| `LOG_PERSIST_REQUEST_LOGS` | `false` | 是否持久化到数据库 |
| `LOG_RETENTION_DAYS` | `7` | 日志保留天数（0 = 禁用自动清理） |
| `OMS_RETENTION_DAYS` | `30` | Responses 有状态对话保留天数（0 = 禁用自动清理） |

**安全警告**：日志体可能包含敏感数据（PII、提示词中的密钥、生成的内容）。仅在调试时启用，调试完成后关闭。

### 敏感信息脱敏

请求体在落盘前自动脱敏（28 类凭据），包括：
- `Authorization` 头的值
- API key 字段
- 其他已知凭据模式

## SSE 日志体磁盘溢出

流式响应体不驻留内存，落盘到磁盘段文件：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `LOG_STREAM_BODY_MAX_DISK_MB` | `1024` | 流式 body 磁盘上限（MB） |
| `LOG_STREAM_BODY_BATCH_SIZE_KB` | `64` | writer batch 大小 |
| `LOG_STREAM_BODY_LINGER_MS` | `5` | batch 最长等待时间（毫秒） |
| `LOG_STREAM_BODY_CHANNEL_CAPACITY_CHUNKS` | `2048` | mpsc 通道容量（chunks 数） |

超过磁盘上限后，新 chunk 被丢弃并标记 `body_incomplete`。

## 环境变量

日志相关环境变量（`LOG_LEVEL`、`LOG_FORMAT`、磁盘总量 `LOG_QUEUE_*` 等）的完整清单见 [环境变量配置参考](/zh-CN/reference/configuration.md#log-retention)。改完环境变量需重启容器生效。

## 请求 ID 关联

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

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

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

## 日志体详情字段

日志详情页展开后包含：

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

### 通知（Notification）

日志详情页顶部展示该请求的特殊通知，例如：
- **script_use_model_swap**：该请求的上游模型是脚本经 `context.useModel` 切换的，非客户端原始请求的模型

## 常见问题

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

**Q：为什么日志里的 body 被截断了？**
每个 body 的捕获大小跟随其准入上限（ADR-005）：请求体跟随 `MAX_REQUEST_SIZE_MB`，响应体跟随 `MAX_RESPONSE_BODY_MB`。大 body（如长对话、大型 embedding 请求）会被截断。调大准入上限可捕获更多，但增加内存和磁盘开销。

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

**Q：日志太多，磁盘快满了怎么办？**
调小 `LOG_RETENTION_DAYS`（如 3 天）加速清理；调小 `LOG_STREAM_BODY_MAX_DISK_MB` 减少流式 body 磁盘占用。

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

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

**下一步**：[日志查看器](/zh-CN/console/logs-viewer.md) 看 UI 视角；[环境变量配置参考](/zh-CN/reference/configuration.md) 看全部环境变量；[审计与安全配置](/zh-CN/reference/audit-and-security-config.md) 看审计日志。