> ## 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 のトレース ID と Tencent Cloud APM 照会のための規範要件です。

## 1. 目的

本文書は、YouRouter Data Tracing の**規範的な挙動と利用要件**を定義します。目的は、YouRouter が返すトレース識別子を用いて Tencent Cloud Application Performance Management（APM）で単一リクエストのエンドツーエンド分散トレースを照会し、監査・突合・障害調査を可能にすることです。

## 2. 用語

本文書の **MUST / MUST NOT / REQUIRED / SHALL / SHALL NOT / SHOULD / SHOULD NOT / RECOMMENDED / MAY / OPTIONAL** は RFC 2119 に従って解釈されます。

* **Trace ID**：Tencent Cloud APM で分散トレースを取得するための一意識別子
* **APM**：Tencent Cloud Application Performance Management
* **Client**：YouRouter API の呼び出し元（サービス、SDK、スクリプト等）
* **Trace Retention Window**：APM で Trace を検索可能な期間。本文書では **72 時間（3 日）**

## 3. プロトコル

Trace ID の伝達手段として、HTTP レスポンスヘッダによる伝達を要求します（それ以外のトランスポート実装詳細は本文書で強制しません）。

## 4. Trace ID のレスポンス要件

### 4.1 ヘッダ定義

YouRouter は、**すべての成功した API レスポンス**で次のレスポンスヘッダを返さなければなりません（**MUST**）。

* **ヘッダ名**：`X-Yourouter-Trace-Id`
* **ヘッダ値**：`<trace_id>`（当該リクエストのトレースを識別する非空文字列）

**注**：Trace ID の形式、長さ、符号化、順序性などは本文書では定義しません。

### 4.2 欠落時の扱い

* YouRouter が制御不能な理由で Trace を生成または報告できない場合、ヘッダを省略できます（**MAY**）。
* `X-Yourouter-Trace-Id` が欠落している場合、Client は当該リクエストを**トレース不能**として扱わなければならず（**MUST**）、Tencent Cloud APM によるトレース検証に依存してはなりません（**MUST NOT**）。

## 5. 保持

### 5.1 保持期間

Tencent Cloud APM のトレースデータは \*\*72 時間（3 日）\*\*保持され検索可能です。

保持期間終了後、当該 Trace は検索不能または利用不能とみなされます（**SHALL**）。

### 5.2 時間制約付き要件

APM トレースデータに依存する監査、突合、証拠収集、障害調査は、リクエスト時刻から **72 時間以内**に完了しなければなりません（**MUST**）。

72 時間経過後、Trace を見つけられないこと自体を、システム不具合やデータ不整合の証拠として解釈してはなりません（**MUST NOT**）。

## 6. Client 側の永続化要件

### 6.1 即時永続化（必須）

レスポンス受信後、Client は `X-Yourouter-Trace-Id` の値を**直ちに抽出し永続化**しなければなりません（**MUST**）。

永続化先には、アプリログ、構造化ログ、DB、チケット、通知ペイロード、観測基盤のカスタムフィールドなどを使用できます（例示であり、これらに限定されません）（**MAY**）。

### 6.2 最小相関セット

相関の信頼性を高めるため、Client は Trace ID とともに次を永続化することが推奨されます（**SHOULD**）。

* Client 側リクエスト ID（社内 request id 等）
* リクエスト時刻（少なくとも秒精度）
* YouRouter API パスまたは操作
* HTTP ステータスコード（または同等の成功/失敗指標）

## 7. APM 照会手順

### 7.1 必須手順

保持期間内に、利用者は次の手順で Trace を取得しなければなりません（**MUST**）。

1. レスポンスヘッダから `X-Yourouter-Trace-Id` を取得
2. Tencent Cloud APM コンソールを開く
3. **Trace Search / Distributed Tracing**（名称は APM 版により異なる）へ移動
4. Trace ID で検索し、詳細を開く
5. エンドツーエンド遅延、依存グラフ、エラー/リトライ、上流呼び出しを確認

### 7.2 照会失敗時

72 時間以内に Trace が見つからない場合、利用者はまず次を確認することが推奨されます（**SHOULD**）。

* Trace ID のコピー誤り（切り詰め/空白）
* APM のサンプリング設定（トレースが生成されない場合がある）
* 検索時間範囲にリクエスト時刻が含まれる

上記を確認しても見つからない場合、利用者は Trace ID とリクエストメタデータを YouRouter サポートへ提供し、追加調査を依頼できます（**MAY**）。

## 8. 帰属と検証

### 8.1 帰属の原則

Trace 詳細では、利用者は YouRouter から上流サービスへの外向き呼び出しを主たる検証根拠として用いるものとします（**SHALL**）。例：

* 宛先ホスト/エンドポイント/URL（ルーティング先の検証）
* 遅延、ステータス、エラー詳細（結果と挙動の検証）

### 8.2 非目標

本文書は、安定したスパン名、属性キー、内部ラベル規約を要求または仮定してはなりません（**MUST NOT**）。実装とドキュメントは、固定タグ名を公開インターフェースとして依存すべきではありません（**SHOULD NOT**）。

## 9. セキュリティとプライバシー

Client は機微なリクエスト本文（プロンプト、個人データ等）のログ化を避けることが推奨されます（**SHOULD**）。

監査・障害調査に必要な最小限の相関メタデータと Trace ID のみを保存することが推奨されます（**SHOULD**）。

## 10. 適合

次を満たす実装は本文書に適合します。

* 成功レスポンスで `X-Yourouter-Trace-Id` を返す（4.1）
* 保持期間を 72 時間として文書化し運用する（5）
* Client に Trace ID の即時永続化を要求し、必須照会手順を提供する（6, 7）