分散トレース エラーのトラブルシューティング

このドキュメントでは、Secure Web Proxy で Cloud Trace とテレメトリー ポリシーを使用している場合に、分散トレースに関する問題を診断して解決する方法について説明します。

トレースが Trace に表示されない

Secure Web Proxy によって生成されたトレース スパンが [Trace エクスプローラ] に表示されない場合は、次の項目を確認します。

  1. Cloud Trace API が有効になっていることを確認する: Secure Web Proxy ゲートウェイをホストするGoogle Cloud プロジェクトで Trace API（cloudtrace.googleapis.com）が有効になっていることを確認します。

    <pre class="devsite-click-to-copy">
gcloud services enable cloudtrace.googleapis.com
</pre>

  2. テレメトリー ポリシーが存在し、有効であることを確認する: gcloud beta network-services telemetry-policies describe コマンドを使用して、テレメトリー ポリシーが正しいリージョンに存在し、適切な Secure Web Proxy ゲートウェイを参照していることを確認します。

    gcloud beta network-services telemetry-policies describe POLICY_NAME \
    --location=REGION

    次のように置き換えます。

    • POLICY_NAME: テレメトリー ポリシーの名前（my-swp-tracing-policy など）
    • REGION: テレメトリー ポリシーがデプロイされているリージョン（us-central1 など）

  3. サンプリング レートを確認する: ポリシーの samplingRate が低い場合（たとえば、1% の場合は 0.01、0.1% の場合は 0.001）、個々の手動テスト リクエストがサンプリングされないことがあります。トレースが機能していることを確認するには、ポリシーを一時的に更新して 100% のサンプリング（samplingRate: 1.00）を使用し、本番環境のレートを復元します。

  4. ターゲット ゲートウェイ リソース URI を検証する: テレメトリー ポリシーの telemetryTarget.resources フィールドで、Secure Web Proxy ゲートウェイの完全修飾リソース URL または短縮名が正確に指定されていることを確認します。

    //networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/GATEWAY_NAME

    次のように置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの ID
    • REGION: Secure Web Proxy ゲートウェイがデプロイされているリージョン（us-central1 など）
    • GATEWAY_NAME: Secure Web Proxy ゲートウェイ インスタンスの名前

    プロジェクト ID、リージョン、ゲートウェイ名が一致しない場合、プロキシはポリシー構成を受信できません。

  5. Identity and Access Management（IAM）権限を確認する:

    • Google Cloud コンソールでスパンを表示するには、ユーザー アカウントまたはサービス アカウントに Cloud Trace ユーザーロール（roles/cloudtrace.user）が付与されていることを確認します。
    • 次のサービス アカウントに Cloud Trace エージェントのロール（roles/cloudtrace.agent）が付与されていることを確認します。
      • service-PROJECT_NUMBER@compute-system.
      • service-PROJECT_NUMBER@gcp-sa-networksecurity.
      • クライアント アプリケーションがスパンを生成または伝播する場合のクライアント仮想マシン（VM）サービス アカウント

子スパンが欠落しているか、トレースグラフが破損している

Secure Web Proxy プロキシのスパンが、アプリケーション リクエストの子スパンではなく、独立したルート トレースまたは切断されたルート トレースとして表示される場合は、次の操作を行います。

  1. 親ベースのサンプリングを有効にする: テレメトリー ポリシーの YAML ファイルで、parentBasedSampling.enabled が true に設定されていることを確認します。

    tracingConfiguration:
  samplingRate: 0.01
  parentBasedSampling:
    enabled: true

    親ベースのサンプリングが無効になっている場合、Secure Web Proxy は、ローカルの samplingRate と一致しない上流でサンプリングされたトレースをドロップする可能性があります。

  2. OpenTelemetry のインストルメンテーションを確認する: アプリケーションが、分散トレース コンテキスト伝播が有効になっている OpenTelemetry SDK を使用していることを確認します。詳細については、OpenTelemetry TraceContext プロパゲータのドキュメントをご覧ください。

トレースの取り込み量が想定外に多い

Trace でトレースの取り込み量または費用が予想よりも多い場合は、次の操作を行います。

  1. ベースライン サンプリング レートを下げる: トラフィックの多い本番環境では、samplingRate を 0.01（1%）や 0.001（0.1%）などの小さい割合に設定します。
  2. 親ベースのサンプリングに依存する: ゲートウェイのベースライン samplingRate を低く保ち、parentBasedSampling を有効にします。この組み合わせにより、プロキシはアップストリーム アプリケーションが明示的に選択したリクエストのみをサンプリングします。
  3. 一時的なデバッグ ポリシーを削除する: トラブルシューティング中に 100% のサンプリング（samplingRate: 1.00）を適用した場合は、デバッグ プロセスが完了したら、ポリシーを削除するか、以前の構成に戻します。

次のステップ