API のトレース

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

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

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

API のトレースを表示する

API のトレースを表示するには:

  1. プロジェクトの [エンドポイント] > [サービス] ページに移動します。

    [エンドポイント] の [サービス] ページに移動

  2. 複数の API を所有している場合は、トレースを表示したい API をクリックします。

  3. [概要] タブが表示されていることを確認します。

  4. 下にスクロールして [トレースを表示] をクリックします。Stackdriver の [トレースリスト] ページが表示されます。

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

[トレースリスト] ページでは、個々のトレースをドリルダウンして、どのようなスパンが ESP によってトレースの中に作成されたかを調べることができます。

トレースとスパンの例

[トレースリスト] ページの詳細については、GCP Console でのトレースの表示をご覧ください。

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

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

  • リクエストとレスポンス全体に対応するスパン。
  • CheckServiceControl スパン。API の構成を取得する Service Controlservices.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 秒あたりのリクエスト数を見積もります。これを見積もるには、[Endpoints] の [サービス] ページにある [リクエスト] のグラフまたは Stackdriver 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 か月間のおよそのスパン数を計算できたら、Stackdriver の料金のページで詳しい料金情報をご確認ください。

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

ESP によるリクエストのサンプリングとトレースの送信を停止するには、ESP 起動オプションを設定して ESP を再起動します。ESP が Stackdriver 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. 最近 Cloud SDK を更新していない場合は、次のコマンドを実行します。
    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_trace_sampling=true オプションを追加します。
    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_trace_sampling=true
  3. docker run コマンドを発行して ESP を再起動します。

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

  1. --disable_trace_sampling オプションを削除するか、false に設定します。
  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_trace_sampling=true"
      ]
  2. kubectl create コマンドを使用して Kubernetes サービスを起動します。
    kubectl create -f deployment.yaml

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

  1. --disable_trace_sampling オプションを削除するか、false に設定します。
  2. Kubernetes サービスを起動します。
    kubectl create -f deployment.yaml

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

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

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

OpenAPI を使用した Cloud Endpoints
ご不明な点がありましたら、Google のサポートページをご覧ください。