Cloud Trace の概要

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

Trace は、次のような質問に答えるのに役立ちます。

  • アプリケーションがリクエストを処理するのにどのくらい時間がかかるか？
  • リクエストの完了に時間がかかるのはなぜか？
  • リクエストによって完了までの時間が異なるのはなぜか？
  • アプリケーションへのリクエストの全体的なレイテンシは？
  • アプリケーションのレイテンシは時間の経過とともに増加したか減少したか？
  • アプリケーションのレイテンシを短縮するにはどうすればよいか？
  • アプリケーションにどのような依存関係があるか？

トレースとログを組み合わせて 根本原因分析を行う方法については、ブログ投稿 分散アプリケーションのトラブルシューティング: トレースとログを組み合わせて根本原因分析を実行するをご覧ください。

アプリケーションのプロファイリングについては、 Cloud Profiler をご覧ください。

環境サポート

Trace は、次の環境で Linux 上で実行されます。

コンポーネント

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

トレース クライアント

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

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

スパンデータを表示して分析するには、コンソールの Google Cloud [Trace エクスプローラ] ページと [Observability Analytics] ページを使用します。

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

  • [Observability Analytics]: 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 クライアント ライブラリよりも優れています。詳細については、 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 はログ、指標、トレースデータを受信できるため、この API を無効にしないでください。

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

VPC Service Controls のサポート

Trace は、VPC Service Controls でサポートされるサービスです。Trace サービス名は cloudtrace.googleapis.com です。Trace サービスに作成した VPC Service Controls の制限は、そのサービスにのみ適用されます。これらの制限 は、トレースデータの取り込みが可能な telemetry.googleapis.com サービスなどの他のサービスには適用されません。

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

Cloud Trace とデータ所在地

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

Google Cloud プロジェクトにトレースデータが保存されないようにするには、 Cloud Trace API を無効にします。Telemetry API はログ、指標、トレースデータを受信できるため、この 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 の料金ページをご覧ください。

次のステップ