Cloud Trace の概要

Cloud Trace は、リクエストのレイテンシを追跡し、サービスと生成 AI アプリケーション全体のパフォーマンス ボトルネックのトラブルシューティングに役立つ、 Google Cloudの分散トレース システムです。Google Cloud サービスと計測されたアプリケーションからレイテンシ データを収集することで、Trace はマイクロサービス アーキテクチャでリクエストがどのように処理されるかを把握し、関連するログを特定するのに役立ちます。

Trace を使用すると、エンドツーエンドのリクエスト レイテンシを測定し、パフォーマンスの傾向を時系列で比較して、遅延の原因となっているダウンストリームの依存関係を特定できます。トレースとログを関連付ける手順については、トレースとログを組み合わせて根本原因分析を実行するをご覧ください。

環境サポート

次の環境の Linux でトレースを実行します。

コンポーネント

Trace は、トレースを収集して Google Cloud プロジェクトに送信するトレース クライアントで構成されます。その後、Google Cloud コンソールを使用して、トレース クライアントによって収集されたデータを表示して分析できます。データモデルについては、トレースとスパンをご覧ください。

トレース クライアント

トレース クライアントは、アプリケーションからレイテンシとスパンのデータを収集し、 Google Cloud プロジェクトにエクスポートします。環境と要件に応じて、アプリケーション コードを計測することで、トレースデータを自動または手動で収集できます。

トレース インターフェース

スパンデータを表示して分析するには、Google Cloud コンソールの [Trace エクスプローラ] ページと [オブザーバビリティ分析] ページを使用します。

  • Trace エクスプローラ: トレースデータの集計情報を表示し、個々のトレースを詳細に調べることができます。集計されたレイテンシ データはヒートマップに表示され、ポインタで探索できます。表示するデータを制限するには、フィルタを追加します。個々のスパンとトレースを表示して調べることもできます。

  • オブザーバビリティ分析: SQL クエリ インターフェースを提供します。クエリでトレースデータとログデータを結合し、クエリ結果を表またはグラフとして表示できます。リンクされた BigQuery データセットを作成すると、BigQuery を使用してトレースデータを分析できます。詳細については、トレースのクエリと分析をご覧ください。

自動トレースのある構成

次の構成では、トレースデータが自動的にキャプチャされます。

  • App Engine スタンダード環境

    • 第 1 世代のランタイムは、トレース スパンを自動的にインターセプトして Cloud Trace に送信します。詳細については、以前のバンドル サービスの概要をご覧ください。

    • 第 2 世代のランタイムは、リクエストの全体的なレイテンシを自動的にキャプチャし、リクエストに X-Cloud-Trace-Context HTTP ヘッダーを追加します。詳細については、ランタイム サポート スケジュールをご覧ください。

  • Cloud Run functions と Cloud Run

    受信および送信 HTTP リクエストで、レイテンシ データが Trace に自動的に送信されます。

アプリケーションを計測する

アプリケーションを計測して、パフォーマンスの把握や障害のトラブルシューティングに役立つ特定の情報を収集します。いくつかのオープンソースの計測化フレームワークは、ログ、指標、トレースデータを収集し、そのデータを Google Cloudなどのベンダーに送信できます。エージェント アプリケーションの場合、一部のフレームワークはプロンプトとレスポンスを収集したり、一部のリモート Google Cloud MCP サーバー呼び出しのトレースを可能にするコンテキストを渡したりできます。

アプリケーションを計装化する場合は、ベンダー固有またはプロダクト固有の API やクライアント ライブラリではなく、OpenTelemetry などのオープンソースの計装化フレームワークを使用することをおすすめします。これらのフレームワークの詳細については、 計測とオブザーバビリティと計測方法を選択するをご覧ください。

提供するインストルメンテーションのサンプルでは、OpenTelemetry を使用しています。

  • コレクタベースのエクスポートを使用するサンプルについては、以下をご覧ください。

    これらのサンプルは、OpenTelemetry プロトコル（OTLP）形式に従った指標データとトレースデータを、Telemetry API を使用してプロジェクトに送信します。サンプルでは、ログデータに Google Cloud エクスポータを使用しています。

  • トレースデータの直接エクスポートを使用して、そのデータを Telemetry API に送信する方法については、Trace エクスポータから OTLP エンドポイントに移行するをご覧ください。

  • プロンプトとレスポンスを収集するようにエージェント アプリケーションを構成する方法を示すサンプルについては、生成 AI アプリケーションを計測する方法をご覧ください。

Cloud Trace クライアント ライブラリを使用してアプリケーションを計測できますが、OpenTelemetry を使用することをおすすめします。OpenTelemetry ライブラリは、Trace クライアント ライブラリよりもシンプルで、OpenTelemetry が定義する OTLP 形式でトレースデータをエクスポートするため、こちらを使用することをおすすめします。詳細については、Trace 用の計装と Cloud Trace 用のクライアント ライブラリをご覧ください。

Cloud Trace とエージェント アプリケーション

エージェント アプリケーションの動作を理解するには、リモートの Google Cloud MCP サーバーを呼び出すときにプロンプトとレスポンスを収集するか、スパンを生成するように構成します。プロンプトとレスポンスは、エージェント アプリケーションが使用する推論を理解するのに役立ちます。ツール呼び出しを記録するスパンは、ツールの呼び出し、呼び出しステータス、リクエスト レイテンシを確認するのに役立ちます。

いくつかの計測サンプルでは、プロンプトとレスポンスを収集するようにアプリケーションを構成する方法を示しています。これらのサンプルは OpenTelemetry に依存しています。詳細については、生成 AI アプリケーションを計測する方法をご覧ください。

Google Cloud MCP サーバーはトレース スパンを生成できます。詳細については、Trace を使用して MCP 呼び出しを調査するをご覧ください。

トレースデータを取り込む API

トレースデータは、Telemetry API または Cloud Trace API を使用してプロジェクトに送信できます。Telemetry API をおすすめする理由は次のとおりです。

  • この API は、オープンソースの OpenTelemetry エコシステムとの互換性を提供します。また、この API の上限は、独自の Google Cloud API である Cloud Trace API の上限よりも柔軟なことがよくあります。

  • トレースデータは、OTLP で定義された proto ファイルと概ね一致する形式で保存されます。一部のフィールドは、保存前に OpenTelemetry 固有のデータ型から JSON データ型に変換されることがあります。ストレージ形式については、トレースデータのスキーマをご覧ください。

  • コレクタベースのトレースデータのエクスポートの場合、計測は Google Cloud固有のエクスポータに依存しません。

  • アプリケーション モニタリングなどの一部の機能は、トレースデータを Telemetry API に送信した場合にのみ利用可能な情報に依存しています。

Google Cloud プロジェクトでトレースデータが保存されないようにするには、Cloud Trace API を無効にします。Cloud Trace API を無効にすると、次のようになります。

  • Google Cloud サービスがトレースデータをプロジェクトに送信しない。
  • Google Cloud は、Cloud Trace API エンドポイントに送信されたリクエストにエラーコードで応答します。
  • Google Cloud Observability は、トレース固有の Telemetry API エンドポイントに送信されたトレースデータを破棄します。Telemetry API はログ、指標、トレースデータを受信できるため、無効にしないでください。

組織を管理していて、Cloud Trace の使用を禁止する場合は、組織のポリシーの制約を作成します。

VPC Service Controls のサポート

Google Cloud サービスとアプリケーションは、Cloud Trace API または Telemetry API を使用して、トレースデータをプロジェクトに送信できます。Cloud Trace が提供する可視化サービスは、Cloud Trace API を使用して、表示するトレースデータを取得します。

トレースデータの保存先の Google Cloud リージョンと、顧客管理の鍵でデータが暗号化されるかどうかを指定するデフォルトを設定するには、Observability API を使用します。この API を使用して、リンクされた BigQuery データセットを構成することもできます。これにより、BigQuery サービスを使用してトレースデータをクエリできます。また、トレース スコープを構成することもできます。これにより、複数のプロジェクトに保存されているトレースデータを集計できます。

詳しくは以下をご覧ください。

Cloud Trace とデータ所在地

データ所在地または影響レベル 4（IL4）の要件があるために Assured Workloads を使用している場合は、Cloud Trace API を使用してトレーススパンを送信しないでください。

Google Cloud プロジェクトでトレースデータが保存されないようにするには、Cloud Trace API を無効にします。Telemetry API は、ログ、指標、トレースデータを受信できるため、無効にしないでください。

トレースの保持

カテゴリ 保持期間
_Trace バケットに保存されたスパン 30 日

IAM ロール

Cloud Trace は、Identity and Access Management（IAM）を使用してリソースへのアクセスを制御します。Cloud Trace API と Telemetry API のロールの一覧については、IAM によるアクセス制御をご覧ください。

Telemetry API はコンシューマー API であるため、Telemetry API にデータを送信するには、割り当てプロジェクトを指定し、その割り当てを使用する権限をアプリケーションのサービス アカウントに付与する必要があります。詳細については、Telemetry API: 認証をご覧ください。

料金

Cloud Trace の料金については、Google Cloud Observability の料金ページをご覧ください。

次のステップ