1. 目的
本文定义 YouRouter 数据追踪能力的规范行为和使用要求。目标是通过查询腾讯云 Application Performance Management（APM）中的分布式追踪数据，让用户能够围绕单次请求进行审计、对账与排障。2. 术语
本文中的 MUST、MUST NOT、REQUIRED、SHALL、SHALL NOT、SHOULD、SHOULD NOT、RECOMMENDED、MAY 和 OPTIONAL，采用 RFC 2119 中的含义来表示要求等级。- Trace ID：用于在腾讯云 APM 中检索分布式追踪的唯一标识。
- APM：腾讯云 Application Performance Management。
- Client：调用 YouRouter API 的任何客户端，包括服务、SDK、脚本等。
- Trace Retention Window：Trace 在 APM 中可被检索的时间窗口。在本文中为 72 小时（3 天）。
3. 协议
除要求通过 HTTP 响应头传递 Trace ID 外，本文不强制规定底层传输实现细节。4. Trace ID 响应要求
4.1 Header 定义
YouRouter MUST 在每一次成功的 API 响应中返回以下响应头：- Header 名称：
X-Yourouter-Trace-Id - Header 值：
<trace_id>，即一个非空字符串，用于标识该请求对应的追踪记录
4.2 缺失处理
- 如果由于超出 YouRouter 控制范围的因素，无法生成或返回 Trace，YouRouter MAY 省略该响应头。
- 如果
X-Yourouter-Trace-Id缺失，Client MUST 将该请求视为不可追踪，且 MUST NOT 依赖腾讯云 APM 对该请求进行基于追踪的校验。
5. 保留期限
5.1 保留窗口
腾讯云 APM 中的 Trace 数据保留并可检索 72 小时（3 天）。 超过该时间窗口后，该 Trace SHALL 视为不可检索或不可用。5.2 时间限制要求
任何依赖 APM Trace 数据进行的审计、对账、证据收集或排障，都 MUST 在请求发生后的 72 小时内完成。 72 小时后，如果无法定位该 Trace，用户 MUST NOT 将此理解为系统故障或数据不一致的证据。6. Client 持久化要求
6.1 立即持久化（必须）
Client 在收到响应后，MUST 立即提取并持久化X-Yourouter-Trace-Id 的值。
持久化目标 MAY 包括但不限于：应用日志、结构化日志管道、数据库、工单系统、告警消息体或可观测性平台的自定义字段。
6.2 最小关联字段集合
为了便于后续关联与排障，Client SHOULD 与 Trace ID 一起持久化以下字段：- 客户端请求标识，例如内部 request id
- 请求时间戳，至少精确到秒
- YouRouter API 路径或操作名
- HTTP 状态码，或等效的成功/失败指示信息
7. APM 查询流程
7.1 必要流程
在保留窗口内，用户 MUST 按以下步骤检索 Trace：- 从响应头中获取
X-Yourouter-Trace-Id的值。 - 打开腾讯云 APM 控制台。
- 进入 Trace Search / Distributed Tracing 页面，具体菜单名可能因 APM 版本而异。
- 使用 Trace ID 搜索并打开对应的 Trace 详情。
- 查看端到端时延、依赖关系图、错误或重试信息，以及 YouRouter 对上游服务的调用。
7.2 查询失败处理
如果在 72 小时内无法找到该 Trace，用户 SHOULD 先确认：- Trace ID 是否复制正确，没有被截断或带入多余空白字符
- APM 的采样设置是否可能导致某些请求不生成 Trace
- 当前时间范围是否覆盖请求发生的时间
8. 归因与校验
8.1 归因原则
在 Trace 详情页中，用户 SHALL 以 YouRouter 发往上游服务的出站调用作为主要校验证据，重点包括：- 目标 Host、Endpoint 或 URL，用于验证实际路由去向
- 时延、状态码和错误信息，用于验证请求结果与行为
8.2 非目标内容
本文 MUST NOT 要求或假设任何固定的 span tag 名称、属性键名或内部标签约定。实现和文档 SHOULD NOT 将这些内部字段当作公开接口依赖。9. 安全与隐私
Client SHOULD 避免记录敏感请求内容，例如提示词或个人数据。 Client SHOULD 仅保存 Trace ID 和满足审计、排障所需的最小关联信息。10. 一致性要求
当满足以下条件时，可认为实现符合本规范：- YouRouter 在成功响应中返回
X-Yourouter-Trace-Id（见第 4.1 节） - 文档明确并执行 72 小时的 Trace 保留窗口（见第 5 节）
- 文档要求 Client 立即持久化 Trace ID，并提供必要的查询流程（见第 6 节和第 7 节）