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


# 导出账单 Excel 与日志排查

本章讲怎么从控制台导出账单 Excel、过滤与搜索日志、按请求 ID 关联日志条目。统计页与日志页的 UI 视角见 [统计](/zh-CN/console/statistics.md) 与 [日志查看器](/zh-CN/console/logs-viewer.md)，日志体存储的字段参考见 [日志与日志体存储](/zh-CN/reference/logs-and-body-storage.md)。

## 导出账单 Excel

入口：控制台 → **设置** → **计费** → **月度成本**（admin、monitor 可见）。

### 操作

1. 在月份下拉里选要导出的月份（上下界由 `/statistics/range` 给出）。
2. 点导出。
3. 得到一份 Excel，含 6 个 sheet：

| Sheet | 内容 |
|-------|------|
| model | 按模型汇总 |
| access key | 按访问密钥汇总 |
| key group | 按密钥组汇总 |
| access key × model | 每个访问密钥下的模型分布 |
| day | 按天汇总（浏览器本地时区切分） |
| week | 按周汇总（浏览器本地时区，周一为起点） |

每个 sheet 的费用按币种拆列（Cost (USD)、Cost (CNY)……），每列金额为该币种原值，不做跨币种加总。

`GET /console/api/billing/export`，文件名 `billing_{YYYY-MM}.xlsx`。

### 注意事项

- 同一账号同一时刻只能有一个导出进行中：多标签页、多设备并发导出或短时间重复点击时，后发的请求会提示"导出正在进行中，请稍候再试"（HTTP 429）；前一个导出完成后限制立即解除。
- 月份上下界来自 `/statistics/range`，只能导出有数据的月份。若网关刚部署不久，可能还没有完整月份数据。
- `count_tokens` 请求（Anthropic token 计数端点）**不计入统计**，因为它不实际调用上游、不产生费用——导出的 Excel 里不会看到这些请求。
- 持久化统计按 1 分钟桶存储；当前分钟桶在网关崩溃时会丢失，已完成的分钟桶保留。
- monitor 角色能导出（计费页对 monitor 可见，可看可导出），但不能改任何配置。

## 日志过滤与搜索

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

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

| 过滤方式 | 说明 |
|---------|------|
| 时间范围 | 选择起止时间 |
| 模型 | 按模型名过滤 |
| 状态码 | 按响应状态码过滤（2xx/4xx/5xx） |
| 访问密钥 | 按密钥名过滤 |
| 搜索 | 按请求 ID 或其他关键字搜索 |

### 实时日志（SSE 流）

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

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

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

## 请求 ID 关联

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

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

在日志页搜索框输入完整请求 ID 即可定位特定请求。

### 实战：定位客户端问题

客户端报错时，让客户端把响应里的 `z-request-id` 头给你，然后：

1. 进控制台 → 日志页
2. 在搜索框粘上这个 ID
3. 找到对应请求，点开展开详情
4. 看请求 / 响应 / 错误详情，定位问题

日志详情包含完整的请求/响应生命周期：

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

### 通知（Notification）

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

## 常见问题

**Q：统计里的请求数和日志对不上？**
统计是 1 分钟粒度聚合，日志是逐条记录。短时间窗口内可能有最多 1 分钟的刷盘延迟。`count_tokens` 请求在日志里能看到但不进统计。

**Q：导出的 Excel 月份选不了？**
月份上下界来自 `/statistics/range`，只能导出有数据的月份。若网关刚部署不久，可能还没有完整月份数据。

**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：怎么把日志导出（不是 Excel）？**
日志页本身没有导出 Excel 入口（只有计费页有）。需要把日志送出网关时，用日志页的 Live 开关背后的 SSE 流接到你自己的收集器；单条排查用 `z-request-id` 搜索。

**下一步**：[统计](/zh-CN/console/statistics.md) 看统计页 UI 视角；[日志查看器](/zh-CN/console/logs-viewer.md) 看日志页 UI 视角；[日志与日志体存储](/zh-CN/reference/logs-and-body-storage.md) 看字段与配置参考。