API のトレース

OpenAPI | gRPC

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

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

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

トレースの表示

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

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

[トレース] に移動

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

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

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

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

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 は、次の形式でトレースを作成します。

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 か月あたりのスパン数を見積もるには:

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

例:

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

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

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

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

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

Compute Engine

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

VM インスタンスに接続します。
```
gcloud compute ssh [INSTANCE_NAME]
```

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

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

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

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

GKE

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

デプロイメントマニフェストファイル（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"
  ]

kubectl create コマンドを使用して、Kubernetes Service を起動します。
```
kubectl create -f deployment.yaml
```

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

--disable_cloud_trace_auto_sampling オプションを削除します。
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）を関連付けます。これにより、システム全体のレイテンシの問題をデバッグできます。

ESPv2 のトレースコンテキストの伝搬の例

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

サポートされるヘッダー

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

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

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