ログトレーサビリティ向上（trace フルパス横断）のPRD¶

1. メタデータ¶

• 作成者: 秋田隼豊
• 作成日: 2026/04/17

2. 目的と背景 (Why)¶

• なぜこれを作るのか？: 現在、ロードバランサー → バックエンド(Cloud Run) → Agent Engine の一連のリクエストフローにおいて、各コンポーネントのログが同一トレースで紐付けられていない。 障害発生時に複数コンポーネントのログを手動で突き合わせる必要があり、原因特定に時間がかかる。
• 目指すゴール: Cloud Logging 上で trace ID 一つで全コンポーネント（LB・バックエンド・Agent Engine）のログを横断検索できる状態にする。

3. ターゲットユーザー (Who)¶

• 誰のための機能か？:
• バックエンド・インフラ担当エンジニア（障害調査・ログ分析を行う担当者）

4. ユーザーメリットと想定効果 (Value & ROI)¶

• ユーザーが得られる価値:
• trace="projects/xxx/traces/yyy" の一つのクエリで、LB・バックエンド・Agent Engine のログを一括確認できる。
• Agent Engine でエラーが発生した際、trace フィールドから対応するバックエンドのログへ即座に辿れる。
• 想定効果:
• 障害調査・ログ分析工数の削減。

5. 機能要件 (What)¶

• 主要な機能 / ユーザーストーリー:

• [担当エンジニア] は [障害の原因特定] のために [trace ID 一つで全コンポーネントのログを横断検索] できる。

• 実装対象:

• sorarun-backend（chat.ts）:
  • LB から受け取った trace ID を使い、projects/{PROJECT_ID}/traces/{TRACE_ID} 形式のフルパスを組み立てる。
  • Agent Engine へのリクエストの state_delta に trace フルパスを渡す。
  • Agent Engine へのリクエストヘッダーに X-Cloud-Trace-Context を付与する。
  • バックエンド自身のログ出力に logging.googleapis.com/trace フィールドを含める。
• sorarun-adk:
  • trace フルパスをログフィールドに含めるエラーログ出力ヘルパー（log.py）を新規作成する。
  • vertexai_search.py と grounding_check.py のエラー発生箇所で上記ヘルパーを呼び出す。

6. 非機能要件・やらないこと¶

• システム要件:
• Cloud Logging の logging.googleapis.com/trace フィールドを使用する（標準フォーマット準拠）。
• 今回のスコープ外:
• Agent Engine の INFO / DEBUG ログへの trace 付与（エラー時のみ対応）。
• trace 以外のログ改善（フォーマット変更、ログレベル見直しなど）。