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>（当該リクエストのトレースを識別する非空文字列）
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 です。- レスポンスヘッダから
X-Yourouter-Trace-Idを取得 - Tencent Cloud APM コンソールを開く
- Trace Search / Distributed Tracing（名称は APM 版により異なる）へ移動
- Trace ID で検索し、詳細を開く
- エンドツーエンド遅延、依存グラフ、エラー/リトライ、上流呼び出しを確認
7.2 照会失敗時
72 時間以内に Trace が見つからない場合、利用者はまず次を確認する SHOULD です。- Trace ID のコピー誤り（切り詰め/空白）
- APM のサンプリング設定（トレースが生成されない場合がある）
- 検索時間範囲にリクエスト時刻が含まれる
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）