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 に転送するように構成します。この手順については、Spring Cloud for Google Cloud：Cloud Traceをご覧ください。

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

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

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

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

    これらのサンプルでは、 OpenTelemetry Protocol（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"

次のステップ