API のトレース

OpenAPI   |  gRPC

Extensible Service Proxy（ESP）または Extensible Service Proxy V2（ESPv2）と API のバックエンド コードをデプロイすると、それ以降はプロキシがすべてのリクエストを傍受して必要なチェックを行い、その後でリクエストを API バックエンドに転送します。バックエンドが応答すると、プロキシはテレメトリーを収集して報告します。プロキシが収集するテレメトリー データの 1 つがトレースで、これには Cloud Trace が使用されます。

このページでは、次の作業の方法を説明します。

• Google Cloud コンソールでトレースを表示する。
• Trace の費用を見積もる。
• トレース サンプリングを無効にするようにプロキシを構成します。

トレースの表示

トレースは、API へのリクエストとさまざまなイベント（RPC 呼び出しやインストゥルメントされたコードのセクションなど）を追跡し、各イベントが発生した時間を正確に記録します。このようなイベントは、トレースの中では「スパン」として表現されます。

プロジェクトのトレースを確認するには、Google Cloud コンソールの Cloud Trace ページに移動します。

[トレース] に移動

[Trace エクスプローラ] ページでは、個々のトレースをドリルダウンして、どのようなスパンが ESP によってトレースの中に作成されたかを調べることができます。フィルタを使用して、単一の API やオペレーションのトレースを表示できます。

作成された API のトレースとスパンは、その API が ESPv2 と ESP のどちらを使用するかによって異なります。各実装のトレース形式の概要を下に示します。

[Trace エクスプローラ] ページの詳細については、トレースを検索して調査するをご覧ください。

ESPv2 によって作成されるスパン

ESPv2 は、次の形式でトレースを作成します。

ESPv2 は、少なくとも 2 つのスパンをトレースごとに作成します。

• リクエストとレスポンス全体に対応する ingress OPERATION_NAME スパン。
• router BACKEND egress スパン。ESPv2 がバックエンドでリクエストの処理と応答を待機する時間です。これには、ESPv2 とバックエンド間のネットワーク ホップが含まれます。

API の構成に応じて、ESPv2 では、次のスパンが追加で作成されます。

• API で認証が必要な場合は、ESPv2 は認証の実行に必要な公開鍵を 5 分間キャッシュに保存します。公開鍵がキャッシュにない場合、ESPv2 が公開鍵を取得してキャッシュに保存し、JWT Remote PubKey Fetch スパンを作成します。
• API の使用に API キーが必要な場合、ESPv2 は API キーの検証に必要な情報をキャッシュに保存します。情報がキャッシュにない場合は、ESPv2 が Service Control を呼び出して Service Control remote call: Check スパンを作成します。

一般に、ESPv2 は受信リクエストをブロックするネットワーク呼び出しにのみスパンを作成します。非ブロッキング リクエストはトレースされません。ローカル処理では、スパンではなくタイム イベントが作成されます。例:

• 割り当ての適用にはリモート呼び出しが必要ですが、呼び出しは API リクエストの過程では発生せず、トレースにスパンが関連付けられません。
• API キーは、ESPv2 によって短期間キャッシュに保存されます。キャッシュを使用するリクエストには、トレースに関連付けられたタイム イベントが含まれます。

ESP によって作成されるスパン

警告: ESP では、スパンに関する詳細情報が提供されません。また、意味のない追加スパンも作成されます。ESPv2 に移行して、トレースのベスト プラクティスを取り入れた詳細なトレースを確認してください。

ESP は、次の形式でトレースを作成します。

少なくとも、トレースごとに次の 4 つのスパンが作成されます。

• リクエストとレスポンス全体に対応するスパン。
• CheckServiceControl スパン。API の構成を取得する Service Control の services.check メソッド呼び出しに対応するものです。
• QuotaControl スパン。API に対して割り当てが構成されているかどうかを調べるためのものです。
• Backend スパン。API のバックエンド コードで費やした時間を追跡するためのものです。

API の構成に応じて、ESP が次のスパンを追加で作成します。

• API の使用で認証が必要な場合、ESP はすべてのトレースに CheckAuth スパンを作成します。リクエストを認証するために、ESP は認証の実行に必要な公開鍵を 5 分間キャッシュに保存します。公開鍵がキャッシュにない場合、ESP が公開鍵を取得してキャッシュに保存し、HttpFetch スパンを作成します。
• API の使用に API キーが必要な場合、ESP はすべてのトレースに CheckServiceControlCache スパンを作成します。ESP は、API キーの検証に必要な情報をキャッシュに保存します。情報がキャッシュにない場合は、ESP が Service Control を呼び出して Call ServiceControl server スパンを作成します。
• API に対して割り当てが設定されている場合、ESP はすべてのトレースに QuotaServiceControlCache スパンを作成します。ESP は、割り当ての確認に必要な情報をキャッシュに保存します。情報がキャッシュにない場合は、ESP が Service Control を呼び出して Call ServiceControl server スパンを作成します。

トレースのサンプリング レート

ESP は、トレースデータを取得するために、API へのリクエストのうち少数をサンプリングします。サンプリング レートを制御するために、ESP はリクエスト カウンターとタイマーを保持します。API への 1 秒あたりのリクエスト数によって、サンプリング レートが決まります。1 秒間にリクエストが 1 件もなかった場合は、ESP からのトレースは送信されません。

1 秒間のリクエスト数に応じて、次のように送信されます。

• 999 以下の場合はトレース 1 件が送信されます。
• 1,000 以上 1,999 以下の場合はトレース 2 件が送信されます。
• 2,000 以上 2,999 以下の場合はトレース 3 件が送信されます。
• その他に関しても同様です。

要約すると、サンプリング レートは ceiling 関数 ceiling(requests per second/1000) を使用して見積もることができます。

Trace の費用を見積もる

Trace の費用を見積もるには、ESP が 1 か月に Trace に送信するスパン数を見積もる必要があります。

1 か月あたりのスパン数を見積もるには:

1. API への 1 秒あたりのリクエスト数を見積もります。これを見積もるには、[エンドポイント] の [サービス] ページにある [リクエスト] のグラフまたは Cloud Logging を使用します。詳細については、API のモニタリングをご覧ください。
2. ESP から Trace に送信される 1 秒あたりのトレース数を式 ceiling(requests per second/1000) で計算します。
3. トレース 1 つに含まれるスパンの数を見積もります。これを見積もるには、ESP によって作成されるスパンの情報に基づいて計算するか、[トレースリスト] ページで API のトレース数を確認します。
4. API が 1 か月間にトラフィックを受け取る秒数を見積もります。たとえば、1 日の特定の時間帯にだけリクエストを受け取る API もあれば、散発的に受け取る API もあります。
5. この 1 か月あたりの秒数にスパン数を乗算します。

例:

1. API へのリクエストが 1 秒あたり最大 5 件であるとします。
2. トレースのサンプリング レートは ceiling（5/1,000）= 1 となります。
3. この API には割り当てが構成されていません。API の使用に API キーも認証も必要ありません。したがって、ESP が作成するスパンの数はトレース 1 つにつき 4 個です。
4. この API がリクエストを受け取るのは、月曜日から金曜日までの営業時間内のみです。この API が 1 か月間にトラフィックを受け取る秒数はおよそ 3,600 × 8 × 20 = 576,000 となります。
5. 1 か月あたりのスパンの数は、およそ 576,000 × 4 = 2,304,000 となります。

1 か月間のおよそのスパン数を計算した後、Trace の料金のページで詳しい料金情報をご確認ください。

トレース サンプリングを無効にする

ESP によるリクエストのサンプリングとトレースの送信を停止するには、ESP 起動オプションを設定して ESP を再起動します。ESP が Cloud Trace に送信するトレースは、[エンドポイント] の [サービス] ページに表示されるグラフとは無関係です。このグラフは、トレース サンプリングを無効にした後も引き続き利用できます。

次のセクションの説明は、API と ESP をデプロイ済みであるか、デプロイのプロセスを理解していることを前提としています。詳しくは、API バックエンドをデプロイするをご覧ください。

App Engine

App Engine フレキシブル環境で ESP トレースのサンプリングを無効にするには:

1. app.yaml ファイルを編集します。endpoints_api_service セクションで、trace_sampling オプションを追加し、その値を false に設定します。例:

   endpoints_api_service:
     name: example-project-12345.appspot.com
     rollout_strategy: managed
     trace_sampling: false

   アプリケーションがマイクロサービスに基づいている場合は、すべての app.yaml ファイルに trace_sampling: false を含める必要があります。

2. 最近 Google Cloud CLI を更新していない場合は、次のコマンドを実行します。

   gcloud components update

3. app.yaml ファイルを保存します。
4. バックエンド コードと ESP を App Engine にデプロイするには:

   gcloud app deploy

トレース サンプリングを再び有効にするには:

1. app.yaml から trace_sampling オプションを削除します。
2. バックエンド コードと ESP を App Engine にデプロイするには:

   gcloud app deploy

Compute Engine

Compute Engine と Docker での ESP トレース サンプリングを無効にするには:

1. VM インスタンスに接続します。

   gcloud compute ssh [INSTANCE_NAME]

2. docker run コマンドの ESP のフラグに --disable_cloud_trace_auto_sampling オプションを追加します。

   sudo docker run \
       --name=esp \
       --detach \
       --publish=80:8080 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=[SERVICE_NAME] \
       --rollout_strategy=managed \
       --backend=[YOUR_API_CONTAINER_NAME]:8080 \
       --disable_cloud_trace_auto_sampling

3. docker run コマンドを発行して ESP を再起動します。

トレース サンプリングを再び有効にするには:

1. --disable_cloud_trace_auto_sampling を削除します。
2. docker run コマンドを発行して ESP を再起動します。

GKE

GKE での ESP トレース サンプリングを無効にするには:

1. デプロイメント マニフェスト ファイル（deployment.yaml として参照されます）を開き、次のコードを containers セクションに追加します。

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:1
     args: [
       "--http_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=[SERVICE_NAME]",
       "--rollout_strategy=managed",
       "--disable_cloud_trace_auto_sampling"
     ]

2. kubectl create コマンドを使用して、Kubernetes Service を起動します。

   kubectl create -f deployment.yaml

トレース サンプリングを再び有効にするには:

1. --disable_cloud_trace_auto_sampling オプションを削除します。
2. Kubernetes Service を起動します。

   kubectl create -f deployment.yaml

ESP を Compute Engine VM インスタンスで実行するときに、Docker コンテナを使用しない場合は、--disable_cloud_trace_auto_sampling オプションに相当する VM インスタンス メタデータ Key-Value ペアはありません。トレース サンプリングを無効にするには、ESP をコンテナ内で実行する必要があります。

リクエストのトレースを強制的に行うことをクライアント側で指定するには、X-Cloud-Trace-Context ヘッダーをリクエストに追加します。詳細については、リクエストを強制的にトレースするをご覧ください。リクエストの中に X-Cloud-Trace-Context ヘッダーがある場合は、トレース サンプリングが無効になっていても ESP から Trace にトレースデータが送信されます。

トレース コンテキストの伝播

分散トレースの場合、リクエスト ヘッダーにトレース ID を指定するトレース コンテキストが含まれることがあります。そのトレース ID は、ESPv2 が新しいトレーススパンを作成し、Cloud Trace に送信するときに使用されます。そのトレース ID は、1 つのリクエストのすべてのトレースを検索して、スパンを結合するために使用されます。リクエストにトレース コンテキストが指定されず、トレースが有効になっている場合は、すべてのトレーススパンに対してトレース ID がランダムに生成されます。

次の例では、Cloud Trace は 1 つのリクエストに対し、ESPv2 によって作成されたスパン（1）とバックエンドによって作成されたスパン（2）を関連付けます。これにより、システム全体のレイテンシの問題をデバッグできます。

詳細は、OpenTelemetry Core のコンセプト: コンテキストの伝搬をご覧ください。

注: 分散トレースでは、クライアントとバックエンドでトレースをサポートする必要がありますが、このドキュメントの対象範囲外の事項です。OpenTelemetry を使用することをおすすめします。

サポートされるヘッダー

ESPv2 は、次のトレース コンテキスト伝搬ヘッダーをサポートしています。

• traceparent: 標準の W3C トレース コンテキストを伝播するヘッダー。ほとんどの最新のトレース フレームワークでサポートされています。
• x-cloud-trace-context: GCP のトレース コンテキスト伝搬ヘッダー。古いトレース フレームワークと Google のライブラリでサポートされていますが、ベンダー固有の機能です。
• grpc-trace-bin: OpenCensus トレース ライブラリで gRPC バックエンドが使用するトレース コンテキスト伝搬ヘッダー。

新しいアプリケーションを構築する場合は、traceparent によるトレース コンテキストの伝搬を使用することをおすすめします。デフォルトでは、ESPv2 がこのヘッダーを抽出して伝搬します。デフォルト動作の変更についての詳細は、ESPv2 トレース起動オプションをご覧ください。

注: ESPv2 とは異なり、ESP のトレース コンテキストの伝搬は起動オプションで手動で有効にする必要があります。ESP では、traceparent ヘッダーはサポートされていません。