Cloud Trace 用の計装

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

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

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

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

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

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

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

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

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

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

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

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

通常、 Google Cloudで実行する場合、アプリケーションに認証情報を提供したり、アプリケーションで Google Cloud プロジェクト ID を指定する必要はありません。一部の言語では、 Google Cloud上で実行されている場合でも、 Google Cloud プロジェクト ID を指定する必要があります。また、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 によって、これらのエグザンプラが自動的に追加されます。詳細については、エグザンプラを使用して指標とトレースを関連付けるをご覧ください。

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

  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 プラットフォームで 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 やその他のオープンソース リポジトリへの詳細な構成情報、サンプル、リンクについては、ご使用の言語の設定ページをご覧ください。