Cloud Trace 用の計測

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

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

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

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

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

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

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

ログ、指標、トレースを収集するようにアプリケーションをインストルメント化する際の推奨事項については、インストルメンテーション アプローチの選択をご覧ください。

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

  • 次のプログラミング言語で、OpenTelemetry と関連する Cloud Trace エクスポータを使用できます。

    OpenTelemetry SDK 例
    C++ SDK C++ の例
    Go SDK Go の例
    Java SDK Java の例
    Node.js SDK Node.js の例
    Python SDK Python の例
    Ruby SDK OpenTelemetry のドキュメントをご覧ください。

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

  • クライアント ライブラリを使用するか、Cloud Trace API を直接呼び出して、Cloud Trace にトレースデータを送信できます。ただし、言語がそのライブラリでサポートされている場合は、OpenTelemetry を使用することをおすすめします。

  • Zipkin サーバーを構成して、Zipkin クライアントからトレースを受信し、それらのトレースを分析のために Cloud Trace に転送できます。この方法の詳細については、Cloud Trace と Zipkin の使用をご覧ください。

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

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

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

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

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

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

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

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

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

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

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

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

Cloud Trace API を有効にする

Cloud Trace を使用するには、Google Cloud プロジェクトで Cloud Trace API が有効になっている必要があります。この設定により、Google Cloud プロジェクトは認証済みのソースからトレース データを受信できます。Google Cloud プロジェクトでは、デフォルトで Cloud Trace API が有効になっているため、何もする必要はありません。 ただし、Google Cloud プロジェクトのアクセス スコープを変更した場合は、Cloud Trace API を有効にする必要があります。

Enable the required API.

Enable the API

次のステップ

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