Cloud Trace の概要

Google Cloudの分散トレース システムである Cloud Trace を使用すると、ユーザーや他のアプリケーションからの受信リクエストをアプリケーションが処理するのにかかる時間や、リクエストの処理時に実行されるオペレーション（リモート プロシージャ コールなど）が完了するのにかかる時間を知ることができます。Trace は、サービスの開発、エージェント アプリケーションの開発、障害のトラブルシューティングにも役立ちます。たとえば、複雑なマイクロサービス アーキテクチャでリクエストがどのように処理されるかを理解したり、調査するログを特定したりするのに役立ちます。

Trace は、App Engine などの Google Cloud サービスと、計測したアプリケーションからレイテンシ データを受信するため、次の質問に答えるうえで役立ちます。

  • アプリケーションがリクエストを処理するのにどのくらい時間がかかるか？
  • アプリケーションがリクエストを処理するのになぜそんなに時間がかかるのか？
  • 一部のリクエストが他のリクエストより時間がかかるのはなぜか？
  • アプリケーションへのリクエストの全体的なレイテンシは？
  • アプリケーションのレイテンシは時間とともに増加しているのか、減少しているのか？
  • アプリケーションのレイテンシを小さくするにはどうすればよいか？
  • アプリケーションにどのような依存関係があるか？

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

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

環境サポート

Trace は、次の環境の Linux 上で動作します。

Trace には、アプリケーションを計装可能にしてトレース情報をキャプチャするためのクライアント ライブラリが用意されています。言語別の設定手順については、Trace 用の計測をご覧ください。

自動トレースのある構成

構成によっては、トレースデータが自動的にキャプチャされることもあります。

  • App Engine スタンダード環境

    Java 8、Python 2、PHP 5 アプリケーションで Trace クライアント ライブラリを使用する必要はありません。これらのランタイムは、アプリケーション URI へのリクエストのレイテンシ データを Trace に自動的に送信します。リクエストには、App Engine サービスへのラウンドトリップ RPC 呼び出しに関するレイテンシ データが含まれます。Trace は、Cloud SQL を除いたすべての App Engine Admin API と連携します。

  • Cloud Run functions と Cloud Run

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

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

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

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

  • トレースデータは、OpenTelemetry 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 の使用を禁止する場合は、組織のポリシーの制約を作成します。

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

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

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

トレース生成をサポートするリモート Google Cloud MCP サーバーと、これらのサーバーにスパンの作成を指示するようにアプリケーションを構成する方法については、Trace を使用して MCP 呼び出しを調査するをご覧ください。

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

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

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

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

  • トレース生成をサポートするリモート Google Cloud MCP サーバーと、これらのサーバーにスパンの作成を指示するようにアプリケーションを構成する方法については、Trace を使用して MCP 呼び出しを調査するをご覧ください。

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

コンポーネント

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

トレース クライアント

OpenTelemetry ライブラリがご使用のプログラミング言語で利用できる場合は、OpenTelemetry を使用してトレースデータの作成と送信が簡単に処理できます。OpenTelemetry は、簡単に使用できるだけでなく、バッチ処理を実装してパフォーマンスを向上させることができます。

OpenTelemetry ライブラリが存在しない場合は、Trace SDK ライブラリをインポートし、Cloud Trace API を使用してコードを計測します。Cloud Trace API は、トレースデータを Google Cloud プロジェクトに送信します。

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

トレースデータを、準リアルタイムで Trace インターフェースに表示して分析できます。

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

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

  • Observability Analytics: このページでは、SQL を使用してスパンの集計分析を実行するクエリを実行できます。SQL クエリでトレースデータとログデータを結合することもできます。クエリの結果は、表形式またはグラフで表示できます。リンクされたデータセットを作成すると、BigQuery を使用してスパンを分析できます。詳細については、トレースのクエリと分析をご覧ください。

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 を無効にします。Cloud Trace API を無効にすると、次のようになります。

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

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

料金

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

次のステップ