# 通过日志定位调用问题

来源: https://platform.lyrouter.com/ai_gateway/docs/logs
更新日期: 2026-10-22

每次经过 LYRouter 网关的模型调用，都会在工作空间的 **日志分析** 页留下一条日志。按时间、API Key、模型和状态码找到这次请求，打开详情就能看到实际调用的模型和服务商、失败来自网关还是上游、各阶段耗时、Token 和费用。日志在调用结束后几秒内可以查到；联系支持时，请附上日志详情顶部的 Request ID。

## 找到这次请求

在工作空间左侧菜单打开 **日志分析**，列表只显示当前工作空间的调用。当前账号管理员和工作空间管理员能看到工作空间内所有 API Key 的日志；普通成员只能看到自己创建的 API Key 产生的日志，一条都没有时列表显示「暂无你可查看的日志」。API Key 删除后，它产生的日志仍然保留，「API Key」列标注「已删除」。

- **搜索框**：输入后自动生效，不区分大小写，同时匹配模型、API Key 名称、创建人、Request ID、Trace ID 和 API 路径。搜索框不匹配错误信息，查找失败的调用请用「状态码」筛选。
- **添加筛选**：「时间范围」「服务商」「请求意图」「是否流式」「状态码」选中即生效；「模型」「客户端」「API Key」「会话 ID」「请求关键字」「响应关键字」输入后按回车或点击 **应用筛选**。「请求关键字」「响应关键字」在提示词和回答正文中搜索，只能搜到开启全文日志期间保存的内容。组织账户还可以按「创建人」「部门」筛选。所有条件同时生效，可在列表上方逐个移除，或点击 **清空全部**。
- **自定义列**：默认显示时间、API Key、API 路径、模型（请求）、服务商、总 Token、状态和状态说明，组织账户还显示创建人。「模型（实际）」「费用」「首 Token」「总延迟」「会话」等列在 **自定义列** 中打开。
- **时间**：「时间」是请求结束的时间。排查运行很久的请求时，用它减去「总延迟」，得到请求到达网关的大致时间。

（截图：在日志分析中按时间、API Key、模型和状态码查找请求。）

## 判断失败来自网关还是上游

列表的「状态」是返回给客户端的 HTTP 状态码，「状态说明」给出来源和原因。鼠标停在「状态说明」上，可以看到最终状态码、来源、原因和上游状态码。

| 「状态说明」 | 含义 | 下一步 |
| --- | --- | --- |
| 「网关」+ 具体原因，如「余额不足」「安全围栏已拦截请求」「网关限流规则已拒绝请求」「模型不可用」 | 网关在调用上游之前拒绝了请求 | 按原因查看[401 / 403：鉴权与权限](https://platform.lyrouter.com/ai_gateway/docs/auth-errors)、[429：限流与配额](https://platform.lyrouter.com/ai_gateway/docs/rate-errors)或[模型不可用](https://platform.lyrouter.com/ai_gateway/docs/unavailable) |
| 「网关」+「连接上游失败，未收到响应」「上游请求超时」「上游请求或响应读取失败」 | 网关已发起调用，但连接上游失败、等待超时或读取中断 | 见[超时与流式中断](https://platform.lyrouter.com/ai_gateway/docs/stream-errors) |
| 「上游」+「服务商返回“…”」 | 上游服务商返回了错误状态码，网关回退完所有候选后原样转发 | 在详情「原始报文」的「上游响应」中查看服务商的报错原文 |
| 「未知」+「历史记录未保存状态来源」 | 较早的日志没有记录来源 | 结合「原始报文」判断 |

## 日志详情里看什么

点击日志行，右侧打开「日志详情」。顶部是「Request ID」和「状态码」，下面是 API 路径、时间、API Key、客户端、模型（请求）、模型（实际）、服务商、Token 总量、吞吐和费用。基本信息下方有三个页签：

| 页签 | 内容 |
| --- | --- |
| 「概览」 | 「路由追踪」「安全审查」「各阶段耗时」「Token 消耗」 |
| 「对话」 | 请求参数、系统提示词、历史消息（默认折叠）、工具调用和回答（思考过程默认折叠）；失败的请求显示「错误响应」 |
| 「原始报文」 | ① 客户端请求、② 上游请求、③ 上游响应、④ 客户端响应，每段包含请求头或响应头和报文体，可以 **复制** |

- **路由追踪**：实际命中的服务商和模型、使用的 BYOK、每次上游调用尝试和换下一个候选的原因，见[查看实际路由](https://platform.lyrouter.com/ai_gateway/docs/route-log)。
- **安全审查**：「配额管理」「模型访问控制」「客户端访问控制」在这次请求上的命中记录、「风险检测」结果和意图分类，见[安全围栏与语义审计](https://platform.lyrouter.com/ai_gateway/docs/guardrails)。
- **各阶段耗时**：分为 ① 鉴权、② 选路、③ 选 Key、④ 上游调用，最后一行是「总耗时」；某个阶段没有记录时显示 `—`。上游调用重试过时，④ 旁边显示「· N 次尝试，最长 X」，耗时是各次尝试之和。阶段数据没有采集到时，①～③ 显示 `—` 并额外显示「首 Token（TTFT）」一行；完全读不到阶段数据时，只显示「总耗时」「上游耗时」「首 Token（TTFT）」三项。④ 占总耗时的大部分，说明时间主要花在上游服务商。
- **原始报文**：`Authorization`、`x-api-key`、`api-key`、`Cookie` 等凭据类请求头不会出现，上游服务商的真实地址也会隐去。

（截图：日志详情的概览包含路由追踪、安全审查、各阶段耗时和 Token 消耗。）

「对话」和「原始报文」中的正文只在工作空间开启全文日志后保存，没有保存时详情标注「本条日志未记录正文」。失败的请求例外：即使没有开启全文日志，也会保存上游返回的错误响应和网关返回给客户端的错误响应，便于排查。开关和保存范围见[日志内容与数据处理](https://platform.lyrouter.com/ai_gateway/docs/privacy)；超过留存期的正文不再显示，见[数据保留、导出与删除](https://platform.lyrouter.com/ai_gateway/docs/retention)。

（截图：原始报文按客户端请求、上游请求、上游响应和客户端响应四段展示。）

## Token 与费用怎么读

日志把一次调用的 Token 分成四项，互不重叠，相加就是这次调用的全部 Token：

| 名称 | 含义 |
| --- | --- |
| 「输入（缓存未命中）」 | 没有命中上游提示词缓存的输入 Token |
| 「输入（缓存命中）」 | 命中上游提示词缓存的输入 Token |
| 「输出」 | 模型生成的 Token |
| 「显式缓存创建」 | 通过 `cache_control` 显式写入上游缓存的 Token |

- 详情「Token 消耗」列出四项的数量和占比，「总计」是四项之和。
- 列表的「总 Token」和详情的「Token 总量」是上游上报的输入加输出，不含「显式缓存创建」，所以可能小于「总计」。
- 「费用」是这次调用按调用时实际扣除的 Credits 折算的人民币金额（¥），没有费用记录时显示「未计算」。账户实际扣了多少 Credits，以 **订阅充值** 页「消费明细」为准；按时间、模型、API Key 汇总的用量见[用量归因与分析](https://platform.lyrouter.com/ai_gateway/docs/analytics)，计费方式见[计费规则与信用点](https://platform.lyrouter.com/ai_gateway/docs/billing)。

## 普通成员与管理员的差异

| 能力 | 当前账号管理员、工作空间管理员 | 普通成员（仅自己创建的 API Key） |
| --- | --- | --- |
| 对话、原始报文、费用、各阶段耗时、会话 | 可以查看 | 可以查看 |
| 「状态说明」中上游返回的状态码 | 显示「服务商返回“…”」 | 显示「服务商返回，未记录更具体原因」，上游报错原文在「原始报文」的「上游响应」中查看 |
| 「路由追踪」 | 可以查看 | 不显示 |
| 「安全审查」 | 完整命中记录和风险检测明细 | 只显示部分命中类别 |
| 导出日志、修改全文日志设置 | 可以 | 不可以，**导出** 按钮提示「仅工作空间管理员或所有者可导出日志。」 |

加密导出的步骤和限制见[数据保留、导出与删除](https://platform.lyrouter.com/ai_gateway/docs/retention#加密导出)。

（截图：当前账号管理员和工作空间管理员可以按当前筛选创建加密导出任务。）

## 常见问题

### 刚发出的请求在日志里找不到，怎么办？

**答：** 日志在调用结束后异步写入，稍等几秒后点击 **刷新**，或打开「自动刷新 · 15s」。仍然找不到时，逐项排查：列表上方是否还有筛选条件（点击 **清空全部**）；普通成员是否用了别人创建的 API Key；请求是否没有带有效的 API Key（401 `missing credentials` 或 `invalid api key`，这类请求无法归属到任何工作空间）；请求是否是 `GET /v1/models`（获取模型列表不记日志）；请求是否被错误率熔断（429 `api_key_circuit_open`）或永久封禁（403 `api_key_permanently_banned`）拒绝，这两类请求也不写入日志。

### 请求成功了，但日志显示的模型或服务商和预期不同？

**答：** 看「模型（实际）」和「服务商」。请求的模型全部失败或在本工作空间未开通时，网关会改用工作空间的默认模型；通过虚拟模型或 `lyrouter/auto` 调用时，实际模型由它们决定。每次尝试和换通道的原因在「路由追踪」中，见[查看实际路由](https://platform.lyrouter.com/ai_gateway/docs/route-log)和[失败重试与备用模型](https://platform.lyrouter.com/ai_gateway/docs/fallback)。

### 怎样查看同一段对话的所有请求？

**答：** 在 **自定义列** 中打开「会话」列，同一会话的请求用同色标签标出，点击标签即按该会话筛选。鼠标停在标签上可以看到会话 ID 和来源：「声明（客户端 x-session-id）」表示由客户端提供；「推断（网关派生）」表示由网关推断，标签末尾带 `≈`。

### 图像、视频生成任务的日志怎么看？

**答：** 列表中只出现创建任务的那次请求，「任务类型」列显示「异步」，任务结算前「费用」显示「结算中」。打开详情后在顶部切换「本次请求」和「整个任务」：「本次请求」是提交任务的那次 HTTP 请求，本身不产生费用；「整个任务」显示任务 ID、任务费用、生成耗时、轮询次数和生成结果。接口用法见[多模态能力](https://platform.lyrouter.com/ai_gateway/docs/multimodal)和[异步任务](https://platform.lyrouter.com/ai_gateway/docs/async)。

### 提交调用问题时需要提供哪些信息？

**答：** 网关的响应中不包含请求 ID，请先在日志中找到这次请求，复制详情顶部的 Request ID，再附上调用时间（精确到分钟并注明时区）、接口路径、模型、API Key 的名称和完整报错原文。不要发送 API Key 明文或完整的鉴权请求头。