--- title: "请求日志" description: "pirouter 控制台的日志页逐条列出工作区里转发给 provider 的请求，几秒内出现、保留 18 个月，不记录正文；用 X-Pi-Trace-Id 能把你自己的日志和这里的记录对上。" canonical: "https://pirouter.ai/zh/docs/guides/logs" last-updated: "2026-10-17" lang: "zh" source: "content/docs/zh/guides/logs.mdx" --- # 请求日志 pirouter 控制台的日志页逐条列出工作区里转发给 provider 的请求，几秒内出现、保留 18 个月，不记录正文；用 X-Pi-Trace-Id 能把你自己的日志和这里的记录对上。 某一次请求失败了、花了多少、由哪个 provider 处理，到控制台的 **日志** 页查：按状态、模型和 API key 筛选，或者直接按响应里的 trace ID 搜索。 ## 打开日志页 在[控制台](https://app.pirouter.ai)侧栏点 **日志**。页面列出本工作区的每一笔请求，时间是 UTC。 时间范围可选 **今天**、**7 天**、**30 天** 或 **自定义时间段**，默认是 **7 天**。日志一次最多查 31 天，所以没有 **90 天**；日志页也没有 **24 小时**，用 **今天** 或自定义时间段。更长的趋势看[用量分析](https://pirouter.ai/zh/docs/guides/usage.md)。 工作区的所有成员都能看日志和每条请求的详情，看不到其他工作区的请求。 ![最近 7 天的日志页：状态图标、模型、各类 token 与花费列](/docs/shots/logs-list.zh.webp) ## 每条请求记录了什么 | 列 | 内容 | | ------------------------------------ | ------------------------------------------- | | **状态** | 行首的图标：成功、用量为估算，或失败类型 | | **时间（UTC）** | 请求的时间，精确到秒 | | **模型** | 调用的模型，带实际服务这次请求的 provider 标记 | | **输入**、**输出**、**缓存读**、**缓存写**、**推理** | 各类 token 数 | | **花费** | 这笔请求的金额，单位美元 | | **延迟** | 从网关收到请求到 provider 返回第一个字节的时间。非流式请求整次调用都算在里面 | | **API 密钥**、**Trace** | 默认隐藏，在 **列** 菜单里打开 | - **花费** 显示 **未计价** 的行没有价格，也没有扣费。它和花费为 $0.00 的行不同。 * 一笔请求的 token 数对不上时，缓存两列显示 **未拆分**，不硬拆。 ### 一条请求的详情 点一行打开详情。顶部是这次请求的 trace ID，可以复制；下面分三节： | 节 | 内容 | | ------ | ------------------------------------------------------------------ | | **用量** | 各类 token、合计、花费，以及 **计量** 方式：**供应商计量** 或 **估算** | | **延迟** | 首 token、生成、总耗时和吞吐 | | **请求** | **上游状态**、结束原因、是否流式、端点、**API 密钥**、**Trace ID**、**上游模型**、**上游请求 ID** | **上游模型** 和 **上游请求 ID** 与响应头 `X-Pi-Upstream-Model`、`X-Pi-Upstream-Request-Id` 是同一个值。找 provider 排查时，提供 **上游请求 ID**。 ![成功请求的详情：状态、模型与 provider、key 名与端点，下方是用量与延迟](/docs/shots/logs-detail.zh.webp) ### 不记录正文 日志不记录请求和响应的正文。pirouter 的请求记录里没有存放提示词、补全内容或请求体的字段，控制台里也看不到它们。pirouter 记录哪些信息、保留多久，见[数据策略与 ZDR](https://pirouter.ai/zh/docs/guides/data-policy.md)。 ## 只看失败的请求 工具栏的 **状态** 菜单分两组： - **结果**：**全部**、**成功**、**用量为估算**、**任意失败**，单选。 - **失败类型**：可以多选，列出的是勾选的类型的并集。 **用量为估算** 不算失败：provider 正常返回了，但没有给出可用的用量报告，token 和花费是估算的。 | 失败类型 | 错误码 | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **供应商不可用** | [`provider_unavailable`](https://pirouter.ai/zh/docs/api/errors.md#provider_unavailable) | | **超时** | `upstream_timeout`，见[超时](https://pirouter.ai/zh/docs/guides/timeouts.md#超时) | | **触发限流** | [`rate_limited`](https://pirouter.ai/zh/docs/api/errors.md#rate_limited) | | **余额不足** | [`insufficient_balance`](https://pirouter.ai/zh/docs/api/errors.md#insufficient_balance) | | **密钥被拒** | [`invalid_api_key`](https://pirouter.ai/zh/docs/api/errors.md#invalid_api_key)、[`api_key_not_found`](https://pirouter.ai/zh/docs/api/errors.md#api_key_not_found)、[`api_key_revoked`](https://pirouter.ai/zh/docs/api/errors.md#api_key_revoked)、[`api_key_expired`](https://pirouter.ai/zh/docs/api/errors.md#api_key_expired)、`key_type_forbidden` | | **请求无效** | [`validation_failed`](https://pirouter.ai/zh/docs/api/errors.md#validation_failed)、[`invalid_request`](https://pirouter.ai/zh/docs/api/errors.md#invalid_request)、[`model_not_found`](https://pirouter.ai/zh/docs/api/errors.md#model_not_found)、`not_found`、[`no_eligible_provider`](https://pirouter.ai/zh/docs/api/errors.md#no_eligible_provider)、`upstream_rejected`、[`context_length_exceeded`](https://pirouter.ai/zh/docs/api/errors.md#context_length_exceeded) | | **客户端断开** | `client_disconnect` | | **平台错误** | [`internal_error`](https://pirouter.ai/zh/docs/api/errors.md#internal_error)，以及其余错误码 | **用量为估算** 对应 `malformed_usage` 和 `stream_downgraded`。 打开失败行的详情，顶部显示失败类型的说明和原始错误码，例如 `rate_limited`。不在错误码表里的错误一律显示为 `internal_error`。 ![状态菜单：结果选项与失败类型列表](/docs/shots/logs-status.zh.webp) ![失败请求的详情：provider 不可用的说明与 provider\_unavailable 错误码](/docs/shots/logs-detail-failed.zh.webp) ## 按模型和 API key 筛选 和用量页是同一组控件：**模型** 可以多选，**API 密钥** 一次选一个 key。**状态**、模型和 key 三个筛选可以叠加。 ## 用 trace ID 找到一次请求 pirouter 的每个响应都带 `X-Pi-Trace-Id` 响应头，成功、失败和网关自己的拒绝都有。把它记进你自己的日志，就能在日志页找到对应的记录；联系支持时也提供这个值。 1. **取出 trace ID** 给 curl 加 `-i`，或者从你所用 SDK 的原始响应里读响应头。 响应头里有一行 `X-Pi-Trace-Id`，复制它的值。 2. **在日志页搜索** 把值粘贴到工具栏的 **按 trace ID 搜索** 框里，回车或点 **搜索**。 列表显示带这个 trace ID 的全部请求，不限日期，页面提示「筛选与时间段暂不生效」。搜索是精确匹配，区分大小写，首尾的空格会被去掉，最长 256 个字符。 3. **打开详情** 点结果中的一行。 详情里是这次请求的用量、延迟和 provider。看完点 **清除搜索**，回到原来的列表。 同一个 trace ID 可能对应多行。请求在返回第一个字节之前失败、由 pirouter 换到另一个部署或模型重试时，每次尝试各占一行：花费为 $0.00 的失败行是被接替的尝试，返回响应的那次才计费。见[模型回退](https://pirouter.ai/zh/docs/guides/fallbacks.md)。 ![trace 搜索模式：显示该 trace ID 的全部请求，筛选与时间段暂不生效](/docs/shots/fallbacks-trace.zh.webp) ## 其他操作 ### 分享一条请求 打开详情后，地址栏会带上这一行（`?row=`）。把链接发给同事，同一工作区的成员能直接打开这条请求。 ### 翻页与总数 每页 20 或 50 行，默认 50 行。用 **上一页**、**下一页**、**第一页**、**最后一页** 翻页，没有页码跳转。总数单独计算，显示为「共 N 条」；超过 3 秒还没数完时显示 **计数超时**，列表和翻页不受影响，缩小日期或筛选范围就能看到总数。 ## 多久出现、保留多久 请求通常在发出几秒后出现在日志页。 请求记录保留最近 18 个月。超出保留期的记录在日志页打不开，详情会提示它已超过保留期。 ## 不在日志里的请求 只有转发给了 provider 的请求才有日志。网关在转发之前就拒绝的请求不进日志，也不计入用量：key 无效、余额不足、模型不存在、参数校验失败、没有可用的 provider、输入超过上下文上限、被 pirouter 限流。这类请求也不计费，见[失败的请求](https://pirouter.ai/zh/docs/guides/billing.md#失败的请求)。这类请求只能凭响应里的 `X-Pi-Trace-Id` 联系支持排查。 ## 目前没有的能力 - **导出和读取日志的 API。** 日志页没有导出或下载 CSV 的功能，公开 API 也没有读取日志的端点。 * **查看请求或响应正文。** pirouter 不记录正文，见[不记录正文](https://pirouter.ai/zh/docs/guides/logs.md#不记录正文)。 * **按 `X-Pi-Session-Id` 搜索。** 控制台不显示这个值，也不能按它搜索。 ## 下一步 - [错误码](https://pirouter.ai/zh/docs/api/errors.md): 每个错误码的含义和处理办法。 - [用量分析](https://pirouter.ai/zh/docs/guides/usage.md): 按时间、模型和 key 看 token、花费和请求数。