Cloud Trace

解決する課題

マイクロサービスやサーバーレスでは、1 つのユーザーリクエストが複数のサービスを横断します。どのサービスのどの処理で時間がかかっているかを、ログだけから突き止めるのは困難です。Cloud Trace は 分散トレース によってこの可視化を担います。

• リクエスト全体が どのサービスを順にたどった のかを把握したい
• エンドツーエンドの遅延のうち、どの区間で時間を使っている のかを特定したい
• 平均では見えない テールレイテンシ（遅いリクエスト） を見つけたい
• リリース前後で レイテンシが悪化していないか を継続的に確認したい

主要概念と用語

Cloud Trace は Google Cloud Observability の一部で、メトリクスの Cloud Monitoring やログの Cloud Logging と連携して使います。

• トレース（Trace）: 1 つのリクエストがシステム全体を通過する一連の処理の記録。複数のスパンで構成される
• スパン（Span）: トレース内の個々の処理単位（例: あるサービスでの 1 回の関数呼び出しや RPC）。開始/終了時刻を持ち、所要時間が分かる
• 親子関係（Parent / Child Span）: スパンは入れ子になり、呼び出しの階層を表す。これによりウォーターフォール表示が描ける
• トレースコンテキストの伝播（Context Propagation）: トレース ID をサービス間の HTTP ヘッダー等で受け渡し、別サービスのスパンを 1 つのトレースに束ねる仕組み。W3C Trace Context などの標準ヘッダーを使う
• 計装（Instrumentation）: アプリにトレース送信のコードを組み込むこと。現在は OpenTelemetry（OTel）が標準的な手段
• サンプリング（Sampling）: 全リクエストではなく一部のみをトレースとして収集すること。負荷とコストを抑える
• レイテンシ分布 / 分析レポート: 収集したトレースから応答時間の分布（パーセンタイル）や時系列の傾向を可視化する機能

仕様・制限・クォータ

• トレースの取り込みは サンプリング が前提で、全リクエストを保存するものではない。サンプリングレートはクライアント側（OpenTelemetry の設定）で制御する
• トレースデータには 保持期間 があり、一定期間を過ぎたトレースは自動的に削除される（長期保管が必要なら BigQuery 等へエクスポートする）
• 1 トレースあたりのスパン数や、スパンに付与できる属性（ラベル）の数・サイズには上限がある
• トレースの取り込みやエクスポートには API のレート上限 があり、超過分はスロットリングされ得る
• 具体的な保持日数・サンプリング既定値・各種上限は変動するため、設計時は最新の公式ドキュメントとプロジェクトのクォータ画面で確認する

内部の仕組み

各サービスは、自分が処理した区間をスパンとして生成し、共通のトレース ID とともに Trace API に送信します。サービス間では トレースコンテキスト（トレース ID と親スパン ID）が HTTP ヘッダーなどで伝播され、受け取った下流サービスは自分のスパンをそのトレースの子として記録します。Cloud Trace はこれらのスパンをトレース ID で束ね、時刻情報をもとに ウォーターフォール（時間軸の入れ子） として再構成します。

App Engine スタンダードなど一部のマネージドサービスは、追加実装なしでトレースを送信します。それ以外の Compute Engine / GKE / Cloud Run 上の独自アプリは、OpenTelemetry などで明示的に計装する必要があります。

設計パターン / ベストプラクティス

• 計装は OpenTelemetry に統一 し、特定ベンダーに依存しない形でスパンを生成・エクスポートする
• サービス間呼び出しでは トレースコンテキストを必ず伝播 させ、トレースの分断を防ぐ
• 重要な業務処理には カスタムスパンや属性（ユーザー種別、処理種別など）を付け、遅延の原因を分類できるようにする
• サンプリングは 頭固定の全件にせず、本番では適切なレートに調整して負荷とコストを抑える。エラー時は確実に取りたい場合に応じてサンプリング戦略を設計する
• トレース ID をログにも出力し、Cloud Logging のログとトレースを相互参照 できるようにする
• メトリクス（Monitoring）で異常を検知し、トレースで原因区間を掘り下げる、という二段構えで使う

運用・監視

• トレースが表示されない → アプリの計装有無、サービスアカウントの IAM 権限（トレース書き込み権限）、Trace API の有効化を確認
• トレースが途中で切れる → 各サービスでのトレースコンテキスト伝播の実装漏れを確認
• 想定よりデータが少ない → サンプリングレートの設定値を確認（低すぎると遅いリクエストを取りこぼす）
• 遅延の調査 → レイテンシ分布のパーセンタイル（特に p95 / p99）を見て、平均では隠れるテールレイテンシを起点に該当トレースを掘る
• リリース回帰の検知 → 分析レポートで時系列のレイテンシ傾向を比較し、デプロイ前後の悪化を早期に発見

コスト

課金は主に 取り込んだスパン数 に基づきます。月次の無料枠を超えた取り込みスパンに対して従量課金される、というのが基本的な考え方です。したがってコスト最適化の要点は、収集するスパンの量を必要十分に絞ることに集約されます。

セキュリティ

• トレースの読み取り/書き込み権限は IAM ロール で最小化する（閲覧はトレース閲覧者、送信はトレースエージェント相当の書き込みロール）
• アプリからの送信には、キー JSON ではなく アタッチされたサービスアカウント（GKE では Workload Identity）を使い、鍵の漏洩リスクを避ける
• スパンの属性に 個人情報や機微情報を入れない。URL のクエリパラメータやリクエストボディをそのまま属性にすると意図せず流出し得る
• 機微データが混入し得る場合は、計装側でマスキング/除外してから送信する

Well-Architected の観点

• 運用上の優秀性（Operational Excellence）: リクエストの経路と遅延を可視化し、障害や性能劣化の原因特定（MTTR 短縮）を支える。ログ・メトリクスと相互参照することで運用の見通しが良くなる
• パフォーマンス効率（Performance Efficiency）: ボトルネック区間を定量的に特定でき、当て推量ではなくデータに基づいた最適化ができる。テールレイテンシの監視でユーザー体験の劣化を早期に捉える

試験で問われるポイント

関連サービス・比較

Cloud Trace は単独ではなく、Observability の他サービスと組み合わせて使います。役割の違いと AWS 相当サービスを押さえます。

GCP 内では、メトリクスは Cloud Monitoring、ログは Cloud Logging、エラーの集約は Error Reporting が担い、Cloud Trace は「時間軸での処理の流れ」に特化します。これらを併用して可観測性を構成します。

ハンズオン / CLI例

# プロジェクトで Cloud Trace API を有効化する
gcloud services enable cloudtrace.googleapis.com --project=PROJECT_ID

# アプリ実行用サービスアカウントにトレース書き込み権限を付与する
# （roles/cloudtrace.agent がスパン送信に必要なロール）
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:app-sa@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/cloudtrace.agent"

# 直近に取り込まれたトレースの一覧を確認する
gcloud trace list-traces --project=PROJECT_ID --limit=10

# 特定のトレースの詳細（スパン構成）を表示する
gcloud trace describe-trace TRACE_ID --project=PROJECT_ID