Cloud Trace の概要

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

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

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

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 に送信した場合にのみ利用可能な情報に依存しています。

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

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

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

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

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

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

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

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

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

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

提供する計測サンプルでは、 OpenTelemetry を使用しています。

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

コンポーネント

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

トレース クライアント

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

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

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

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

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

  • [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 を使用してトレーススパンを送信しないでください。

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

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

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

料金

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

次のステップ