关联一次请求
网关的middleware/request-id.go 为请求生成 ID，并返回 X-Gateway-Request-Id 和兼容头 X-Oneapi-Request-Id。优先读取前者；反向代理产生的拒绝可能没有这两个头。不要把客户端传入的同名头当作网关认可的关联 ID。
应用应保留自己的业务请求 ID，并关联每次尝试返回的网关 ID。多个 SDK 重试是多个 HTTP 请求；一个 HTTP 请求内可能还有网关内部的渠道尝试。应用尝试次数不能代替内部尝试次数。
只读诊断脚本演示安全的元数据记录。它记录收到响应头时的累计时间，不测量首 token、不代表模型推理延迟，也不调用生成接口。
生产应用如何记录
使用单调时钟测量耗时、带时区时间戳定位事件。流式内容可能先出现角色、空增量或工具参数，只有实际可消费的数据才算相应的首事件。完成指标必须等待协议结束条件，不能把连接 EOF 或第一条数据算作成功。 业务日志采用字段白名单：不记录 API Key、Authorization、Cookie、完整 prompt / 输出、Base64 媒体、原生签名、压缩密文或带签名的下载 URL。不要直接打印 SDK 异常对象或完整 HTTP 响应体。生产环境中的正文保留、访问控制和保留期限由部署方确认；store: false 不等于所有组件都不留日志。
故障反馈最小清单
- 时间和时区、部署环境、SDK 名称及版本。
- 方法与路径模板、模型、HTTP 状态、脱敏后的错误类型。
- 应用尝试次数、网关请求 ID、是否已收到部分内容或任务 ID。
- 可复现的最小请求结构，用占位符替换业务正文及凭据；任务 ID 仅通过获准的支持渠道共享。
- 预期行为和实际行为，例如“期望完成文本，实际
finish_reason=length”。