Cloud Trace 用の計装

このドキュメントでは、Cloud Trace 用にアプリケーションを計装可能にする方法の概要を簡単に説明します。Cloud Trace の設定の詳細な手順については、言語別の設定ページをご覧ください。

Cloud Trace では、アプリケーションの分散トレースデータを提供します。アプリケーションを計装可能にすると、Cloud Trace コンソールで、1 つのリクエストのレイテンシデータを分析して、アプリケーション全体の集約したレイテンシを確認できます。

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

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

アプリケーションを計測可能にして、パフォーマンスの把握や障害のトラブルシューティングに役立つ特定の情報を収集します。いくつかのオープンソースの計装フレームワークは、ログ、指標、トレースデータを収集し、そのデータをなどのベンダーに送信できます 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 を直接呼び出します。
Cloud Trace クライアントライブラリを使用するか、OpenTelemetry 用の Cloud Trace エクスポータを使用します。
Spring Boot アプリケーションの場合は、収集したトレースデータを Cloud Trace に転送するように構成します。この手順については、Spring Cloud for Google Cloud：Cloud Traceをご覧ください。

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

コレクタベースのエクスポートを使用するサンプルについては、以下をご覧ください。
- Go
- Java
- Node.js
- Python
これらのサンプルは、トレースデータを Telemetry API に送信します。
トレースデータの直接エクスポートを使用して、そのデータを Telemetry API に送信する方法については、 Trace エクスポータから OTLP エンドポイントに移行するをご覧ください。
プロンプトとレスポンスを収集するようにエージェントアプリケーションを構成する方法を示すサンプルについては、生成 AI アプリケーションを計測する方法をご覧ください。

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

スパンを作成するタイミング

Cloud Trace クライアントライブラリには通常、現在のスパンに関する情報（トレース ID やトレースがサンプリングされるかどうかなど）を保持するグローバルトレースコンテキストが保持されています。これらのライブラリでは通常、RPC の境界にスパンが作成されます。ただし、デフォルトの作成アルゴリズムではニーズを満たせない場合は、ユーザーがスパンを作成する必要があります。

現在アクティブなスパンには、Tracer オブジェクトでラップされることもあるグローバルトレースコンテキストからアクセスできます。アプリケーションに関連する情報をカスタムアノテーションとタグを使用して、既存のスパンに追加できます。また、独自のアノテーションとタグで新しい子スパンを作成して、アプリケーションの動作を詳細にトレースすることもできます。コンテキストはグローバルであるため、コンテキストを更新するマルチスレッドのアプリケーションは適切な隔離を使用する必要があります。

認証情報を提供するタイミング

上で実行する場合、一般的にアプリケーションに認証情報を提供したり、アプリケーションでプロジェクト ID を指定する必要はありません。 Google Cloud Google Cloud一部の言語では、プロジェクト ID を指定する必要があります。 Google Cloud 上で実行されている場合でも、 Google Cloudまた、Google Kubernetes Engine で Autopilot モードを使用する場合、または Workload Identity Federation for GKE を有効にする場合は、Workload Identity Federation for GKE を使用するようにアプリケーションを構成する必要があります。

の外部で実行している場合は、アプリケーションに認証情報を提供する必要があります。 Google Cloudアプリケーションで Google Cloud プロジェクト ID も指定する必要があります。

詳しくは、言語別の設定ページをご覧ください。

リクエストを強制的にトレースする方法

アプリケーションが常にすべてのスパンをサンプリングしない限り、一般に、リクエストをエンドツーエンドでトレースすることはできません。それは、エンドツーエンドリクエストの各コンポーネントはサンプリングの決定を独自に行うためです。ただし、トレースヘッダーに sampled フラグを追加し、このフラグを true に設定することで、決定に影響を与えることができます。この設定は、リクエストをサンプリングするように子コンポーネントにヒントを与えます。トレースヘッダーの詳細については、コンテキスト伝播のプロトコルをご覧ください。

コードを所有するダウンストリームコンポーネントの場合は、計測ロジックが sampled フラグを考慮しているかどうかを判断する必要があります。たとえば、計測に OpenTelemetry を使用する場合、ParentBased サンプラーを使用すると、親のサンプリングフラグが考慮されます。

Google Cloud 通常、トレース情報を Cloud Trace に記録するサービスでは、親サンプリングフラグをヒントとして受け入れますが、ほとんどのサービスでレート制限のサンプリングも行われます。各 Google Cloud サービスは、トレースをサポートするかどうか、親サンプリングフラグをどう利用するか、サンプリングのレートの制限を決定します。

指標データとトレースデータを関連付ける方法

分布値の指標データをトレースに関連付けるには、エグザンプラを指標データポイントにアタッチします。必要な構成手順を完了すると、推奨される計装ライブラリである OpenTelemetry は、これらのエグザンプラを自動的に追加します。詳細については、エグザンプラを使用して指標とトレースを関連付けるをご覧ください。

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

Cloud Trace API が有効になっていることを確認します。

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

Cloud Trace API を有効にします。
API を有効にするために必要なロール
API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。詳しくは、ロールを付与する方法をご覧ください。
API の有効化
プラットフォームを構成する。

Cloud Trace は Google Cloud と他のプラットフォームで使用できます。
- Google Cloud: アプリケーションが Google Cloudで実行されている場合、認証情報をサービスアカウントの形式でクライアントライブラリに提供する必要はありません。ただし、は、 Google Cloud プラットフォームで Cloud Trace API のアクセススコープが有効になっていることを確認する必要があります。
  
  次の構成では、デフォルトのアクセススコープ設定に Cloud Trace API アクセススコープが含まれています。
  - Compute Engine
  - Google Kubernetes Engine（GKE）
    
    注: Autopilot を使用している場合、または GKE クラスタで Workload Identity Federation for GKE を有効にする場合は、Workload Identity Federation for GKE を使用するようにアプリケーションを構成します。
  - App Engine フレキシブル環境
  - App Engine スタンダード環境
  - Cloud Run
  カスタムアクセススコープを使用する場合は、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"

次のステップ

GitHub やその他のオープンソースリポジトリへの詳細な構成情報、サンプル、リンクについては、ご使用の言語の設定ページをご覧ください。

OpenTelemetry の例: