Cloud Trace 用の計装

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

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

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

トレースデータが自動的にキャプチャされない場合は、アプリケーションを計測してこのデータを収集する必要があります。

アプリケーション固有の情報を収集するように、アプリケーションをインストルメント化できます。いくつかのオープンソースの計装フレームワークを使用すると、アプリケーションから指標、ログ、トレースを収集し、そのデータを Google Cloud などのベンダーに送信できます。アプリケーションをインストルメント化するには、ベンダー固有の API とプロダクト固有の API やクライアント ライブラリではなく、OpenTelemetry などのオープンソースのインストルメンテーション フレームワークを使用することをおすすめします。

ベンダーに依存しないインストルメンテーション フレームワークを使用したアプリケーションのインストルメント化の詳細については、インストルメンテーションとオブザーバビリティをご覧ください。

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

トレースデータを収集するようにアプリケーションをインストルメント化するには、次のいずれかを行います。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Enable the Cloud Trace API.

    Enable the API

  2. プラットフォームを構成する。

    Cloud Trace は Google Cloud と他のプラットフォームで使用できます。

    • Google Cloud: アプリケーションが Google Cloud で実行されている場合、認証情報をサービス アカウントの形式でクライアント ライブラリに提供する必要はありません。ただし、Google Cloud Platform で 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"

次のステップ

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