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

# 数据追踪规范

> 关于 YouRouter Trace ID 与腾讯云 APM 查询方式的规范说明。

## 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>`，即一个非空字符串，用于标识该请求对应的追踪记录

**说明**：本文不定义 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：

1. 从响应头中获取 `X-Yourouter-Trace-Id` 的值。
2. 打开腾讯云 APM 控制台。
3. 进入 **Trace Search / Distributed Tracing** 页面，具体菜单名可能因 APM 版本而异。
4. 使用 Trace ID 搜索并打开对应的 Trace 详情。
5. 查看端到端时延、依赖关系图、错误或重试信息，以及 YouRouter 对上游服务的调用。

### 7.2 查询失败处理

如果在 72 小时内无法找到该 Trace，用户 **SHOULD** 先确认：

* Trace ID 是否复制正确，没有被截断或带入多余空白字符
* APM 的采样设置是否可能导致某些请求不生成 Trace
* 当前时间范围是否覆盖请求发生的时间

如果这些条件都确认无误但仍无法找到 Trace，用户 **MAY** 将 Trace ID 与请求元数据提交给 YouRouter 支持团队进行进一步排查。

## 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 节）