> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inputapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 请求观测与排障记录

> 关联应用与网关请求，区分响应头延迟、首事件时间和完成状态。

## 关联一次请求

网关的 `middleware/request-id.go` 为请求生成 ID，并返回 `X-Gateway-Request-Id` 和兼容头 `X-Oneapi-Request-Id`。优先读取前者；反向代理产生的拒绝可能没有这两个头。不要把客户端传入的同名头当作网关认可的关联 ID。

应用应保留自己的业务请求 ID，并关联每次尝试返回的网关 ID。多个 SDK 重试是多个 HTTP 请求；一个 HTTP 请求内可能还有网关内部的渠道尝试。应用尝试次数不能代替内部尝试次数。

| 建议字段 | 含义与限制 |
| - | - |
| 应用请求 ID / 尝试次数 | 关联业务操作与显式新请求 |
| 网关请求 ID | 帮助部署方查询对应日志；不是鉴权凭证 |
| 协议 / 方法 / 路径模板 | 记录 `/v1/chat/completions` 等固定路由，避免原始 URL 中的敏感查询参数 |
| 模型 / HTTP 状态 | 使用受控字段；HTTP 200 后仍需校验业务响应 |
| 响应头耗时 / 首事件耗时 / 总耗时 | 三者分别计时；收到头部不等于收到可展示内容 |
| 完成结果 | 区分正常结束、拒绝、工具调用、截断、取消与失败 |

[只读诊断脚本](/zh/guides/rate-limits)演示安全的元数据记录。它记录收到响应头时的累计时间，不测量首 token、不代表模型推理延迟，也不调用生成接口。

## 生产应用如何记录

使用单调时钟测量耗时、带时区时间戳定位事件。流式内容可能先出现角色、空增量或工具参数，只有实际可消费的数据才算相应的首事件。完成指标必须等待协议结束条件，不能把连接 EOF 或第一条数据算作成功。

业务日志采用字段白名单：不记录 API Key、Authorization、Cookie、完整 prompt / 输出、Base64 媒体、原生签名、压缩密文或带签名的下载 URL。不要直接打印 SDK 异常对象或完整 HTTP 响应体。生产环境中的正文保留、访问控制和保留期限由部署方确认；`store: false` 不等于所有组件都不留日志。

## 故障反馈最小清单

1. 时间和时区、部署环境、SDK 名称及版本。
2. 方法与路径模板、模型、HTTP 状态、脱敏后的错误类型。
3. 应用尝试次数、网关请求 ID、是否已收到部分内容或任务 ID。
4. 可复现的最小请求结构，用占位符替换业务正文及凭据；任务 ID 仅通过获准的支持渠道共享。
5. 预期行为和实际行为，例如“期望完成文本，实际 `finish_reason=length`”。

先看[排障指南](/zh/guides/troubleshooting)与[协议边界](/zh/guides/protocol-compatibility)。日志中的成功状态只能说明对应请求结果，不能证明所有模型或所有渠道均已验收。

[Read in English](/en/guides/observability)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.