概要

このページでは、アプリケーションを Cloud Trace 用にインストゥルメントする方法について簡単に説明します。Cloud Trace の設定方法について詳しくは、言語別の設定ページをご覧ください。

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

Cloud Trace では、OpenTelemetry の使用をおすすめします。 OpenTelemetry は、OpenCensus と OpenTracing を統合したオープンソース プロダクトです。

アプリケーションのトレースのインストルメント化

アプリケーションのトレースを実装するには、次の 3 つの方法があります。

  • OpenTelemetry と関連する Cloud Trace クライアント ライブラリを使用します。アプリケーションをインストゥルメント化するには、この方法をおすすめします。

  • お使いの言語で OpenTelemetry クライアント ライブラリを使用できない場合は、OpenCensus を使用します。

  • Cloud Trace APIを使用して、Cloud Trace にトレースデータを送信するカスタム メソッドを作成します。

OpenTelemetry は、現在のところすべての言語で利用できるわけではありません。使用している言語で推奨されるクライアント ライブラリについては、次の表をご覧ください。

言語 推奨されるクライアント ライブラリ
Python OpenCensus
Java OpenCensus
Node.js OpenTelemetry
Go OpenTelemetry
C# .NET Cloud Trace API
PHP OpenCensus
Ruby Cloud Trace API

アプリケーションをインストゥルメント化するタイミング

アプリケーションで Cloud Trace にトレースを送信するには、インストゥルメント化する必要があります。Google クライアント ライブラリを使用してコードをインストゥルメント化できます。ただし、アプリケーションのインストゥルメント化には OpenTelemetry または OpenCensus を使用することをおすすめします。これらはオープンソースのトレース パッケージです。OpenTelemetry は現在開発中であり、推奨されるパッケージです。

スパンの作成

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

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

認証

アプリケーションで認証情報を指定する必要はありません。また、Google Cloud で実行するときにアプリケーションで Google Cloud プロジェクト ID を指定する必要もありません。一部の言語では、Google Cloud で実行されている場合でも、Google Cloud プロジェクト ID を指定する必要があります。

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

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

Google Cloud プロジェクトの構成

Cloud Trace を使用するには、Google Cloud プロジェクトで Cloud Trace API を有効にする必要があります。この設定により、Google Cloud プロジェクトで認証されたソースからトレースデータを受信できるようになります。

Google Cloud プロジェクトでは、デフォルトで Cloud Trace API が有効になっているため、何もする必要はありません。Google Cloud プロジェクトのアクセス スコープを変更し、設定を確認する場合は、次の操作を行います。

  1. Google Cloud Console から [API とサービス] に移動します。

    [API とサービス] に移動

  2. [API とサービスを有効化] をクリックします。

  3. 検索バーで、「Trace API」と入力します。

  4. [API が有効です] と表示されている場合、この API はすでに有効になっており、何もする必要はありません。それ以外の場合は、[有効にする] をクリックします。

サンプリング レート

Cloud Trace はすべてのリクエストをサンプリングしません。たとえば、Java と OpenCensus を使用する場合、10,000 個あたり 1 個のリクエストのみがトレースされます。App Engine を使用している場合、リクエストは App Engine インスタンスごとに毎秒 0.1 リクエストの割合でサンプリングされます。Cloud Trace API を使用する場合は、顧客のレートを構成できます。Java OpenCensus パッケージなどの一部のパッケージは、サンプリング レートの構成をサポートしています。

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

特定のリクエストを強制的にトレースするには、そのリクエストに X-Cloud-Trace-Context ヘッダーを追加します。ヘッダーの仕様は次のとおりです。

"X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=TRACE_TRUE"

ここで

  • TRACE_ID は、128 ビットの番号を表す 32 文字の 16 進数値です。 リクエストを束ねるつもりがないのであれば、リクエスト間で一意の値にする必要があります。これには UUID を使用できます。

  • SPAN_ID は、符号なしのスパン ID の 10 進数表現です。トレースはランダムに生成され、トレースで一意です。後続のリクエストでは、SPAN_ID を親リクエストのスパン ID に設定します。ネストされたトレースの詳細については、TraceSpanRESTRPC)の説明をご覧ください。

  • このリクエストをトレースするには、TRACE_TRUE1 に設定する必要があります。リクエストをトレースしない場合は 0 を指定します。

たとえば、curl でトレースを強制するには、次のようにします。

curl "http://www.example.com" --header "X-Cloud-Trace-Context:
  105445aa7843bc8bf206b12000100000/1;o=1"

次のステップ

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