Cloud Trace 用の計装

Cloud Trace 用にアプリケーションをインストルメント化すると、分散トレース データをキャプチャし、個々のリクエストのレイテンシを調べ、トレース コンソールでサービス全体の集約レイテンシを確認できます。

このドキュメントでは、計測アプローチと構成オプションの概要について説明します。特定のプログラミング言語の詳細な手順については、言語固有の設定ページをご覧ください。

アプリケーションを計測可能にするタイミング

パフォーマンスの検証や問題のトラブルシューティング用のトレースデータが自動的にキャプチャされない場合は、アプリケーションを計測します。

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

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

アプリケーションの計測方法

アプリケーションを計測するには、次のようないくつかの方法があります。

  • 推奨: OpenTelemetry を使用し、トレースデータをコレクタに送信する OTLP エクスポータを使用してアプリケーションを構成し、Telemetry（OTLP）API を使用してトレースデータを Google Cloud プロジェクトに送信するようにコレクタを構成します。推奨事項の詳細については、計測方法を選択するをご覧ください。

  • OpenTelemetry を使用し、Telemetry API を使用してトレースデータを Google Cloud プロジェクトに送信する OTLP エクスポータでアプリケーションを構成します。

  • Compute Engine で動作するアプリケーションを作成する場合は、Ops エージェントと OpenTelemetry Protocol（OTLP）レシーバを使用して、アプリケーションからトレースと指標を収集することもできます。Ops エージェントはログも収集できますが、OTLP は使用しません。詳細については、Ops エージェントと OTLP を使用すると Ops エージェントの概要をご覧ください。

  • Telemetry API または Cloud Trace API を直接呼び出す。

  • Spring Boot アプリケーションの場合は、収集したトレースデータを Cloud Trace に転送するように構成します。この手順については、 Google Cloud用の Spring Cloud: Cloud Trace をご覧ください。

  • Cloud Trace クライアント ライブラリを使用するか、OpenTelemetry 用の Cloud Trace エクスポータを使用します。

インストルメンテーションのサンプル

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

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

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

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

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

カスタム スパンを作成する

OpenTelemetry とクライアント ライブラリを使用するとカスタム スパンを作成できますが、これらのライブラリは RPC 境界でスパンを自動的に作成するため、手動で作成する必要がない場合があります。

既存のスパンにカスタム アノテーションとタグを追加して、アプリケーションに関連する情報を追加することもできます。また、独自のアノテーションとタグを含む新しい子スパンを作成して、アプリケーションの動作をより詳細にトレースすることもできます。

ライブラリは通常、現在のスパンに関する情報（トレース ID やサンプリング ステータスなど）を保持するグローバル トレース コンテキストを維持します。アプリケーションは、グローバル トレース コンテキストを介して現在のスパンにアクセスできます。コンテキストはグローバルであるため、マルチスレッド アプリケーションがスレッド間でコンテキストを伝播して、正確なトレースデータを維持するようにしてください。

トレース サンプリングを強制する

リクエスト パスの各コンポーネントが独立したサンプリングの決定を行うため、スパンを強制的にサンプリングすることはできません。ただし、トレース ヘッダーの sampled フラグを true に設定すると、ダウンストリーム コンポーネントに影響を与えることができます。この設定は、リクエストをサンプリングするように子コンポーネントにヒントを与えます。トレース ヘッダーの詳細については、コンテキスト伝播のプロトコルをご覧ください。

  • アプリケーション: 計測ロジックが sampled フラグを考慮する方法を構成します。たとえば、OpenTelemetry を使用する場合、ParentBased サンプラーを使用すると、親のサンプリング フラグが考慮されます。

  • Google Cloud サービス: 各サービスは、独自のトレース サポートを決定します。一般に、サービスは独自のサンプリング レート制限を適用しながら、親サンプリング フラグをヒントとして受け入れます。

エグザンプラを使用して指標とトレースを関連付ける

エグザンプラを使用すると、指標データをトレースに関連付けることができます。エグザンプラは、指標測定に関連付けられた代表サンプル リクエストまたはスパンです。たとえば、エグザンプラにはトレースへのリンクを含めることができます。これにより、指標データとトレースデータを関連付けることができます。OpenTelemetry ベースの例については、エグザンプラを使用して指標とトレースを関連付けるをご覧ください。

トレースデータの SQL クエリ結果を表示するダッシュボード グラフに、システム生成のエグザンプラが表示されることがあります。これらのエグザンプラーは、特定のクエリ結果をトレースに直接リンクします。詳細については、トレース エグザンプラを生成して表示するをご覧ください。

プロジェクトとプラットフォームを構成する

このセクションでは、必要な API と Identity and Access Management（IAM）ロールについて説明し、プラットフォームの認証情報を構成する方法について説明します。

API を有効にする

デフォルトでは、 Google Cloud プロジェクトで Cloud Trace API と Telemetry API が有効になっているため、何もする必要はありません。ただし、組織で定義されているセキュリティの制約により、これらの API のいずれかまたは両方が無効になっている可能性があります。トラブルシューティング情報については、制約のある Google Cloud 環境でアプリケーションを開発するをご覧ください。

Telemetry API と Cloud Trace API がまだ有効になっていない場合は、有効にします。

API を有効にするために必要なロール

API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を通じてこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を通じてこの権限を取得できます。ロールを付与する方法を確認する。

API を有効にする

IAM ロールを付与する

必要な IAM ロールは、 Google Cloud コンソールでトレースデータを表示するか、プロジェクトにトレースデータを書き込むかによって異なります。

  • Google Cloud コンソールを使用してトレースデータを表示するために必要な権限を取得するには、プロジェクトに対する Cloud Trace ユーザー （roles/cloudtrace.user）IAM ロールを付与するよう管理者に依頼してください。

  • Cloud Trace API を使用してトレースデータを書き込むために必要な権限を取得するには、プロジェクトに対する Cloud Trace エージェント （roles/cloudtrace.agent）IAM ロールを付与するよう管理者に依頼してください。

  • Telemetry API を使用してトレースデータを書き込むために必要な権限を取得するには、プロジェクトに対する Cloud Telemetry 書き込みロール （roles/telemetry.writer）IAM ロールの付与を管理者に依頼してください。

認証

このセクションでは、アプリケーションがGoogle Cloud で実行されている場合と、それ以外の場所で実行されている場合の認証方法について説明します。

Google Cloudで実行する

アプリケーションが Google Cloudで実行されている場合、一般的に認証情報を提供する必要はありません。ただし、一部の言語クライアント ライブラリでは、 Google Cloudでホストされている場合でもプロジェクト ID が必要です。

Google Cloud プラットフォームで Cloud Trace API のアクセス スコープが有効になっていることを確認します。次の構成では、デフォルトのアクセス スコープ設定に Cloud Trace API アクセス スコープが含まれます。

カスタム アクセス スコープを使用する場合は、Cloud Trace API のアクセス スコープを有効にする必要があります。たとえば、Google Cloud CLI を使用して GKE クラスタを作成し、--scopes フラグを指定する場合は、スコープに trace.append が含まれていることを確認します。次のコマンドは、--scopes フラグの設定を示しています。

gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

ローカルやその他の場所で実行する

アプリケーションが Google Cloudの外部で実行されている場合は、認証情報をクライアント ライブラリに提供する必要があります。サービス アカウントに Cloud Trace エージェント ロール（roles/cloudtrace.agent）を付与する必要があります。ロールの詳細については、IAM によるアクセス制御をご覧ください。

Google Cloud クライアント ライブラリは、アプリケーションのデフォルト認証情報（ADC）を使用してアプリケーションの認証情報を検索します。これらの認証情報を指定するには、次の 3 つの方法があります。

  • gcloud auth application-default login を実行する

  • オペレーティング システムのデフォルトパスにサービス アカウント キーファイルを配置します。以下に、Windows と Linux のデフォルトのパスを一覧表示します。

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • GOOGLE_APPLICATION_CREDENTIALS 環境変数をサービス アカウントのパスに設定します。

    Linux / macOS

        export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

    Windows

        set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

    PowerShell:

        $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

次のステップ