このドキュメントでは、Cloud Trace を使用してアプリケーション ロードバランサの分散トレースを構成する方法について説明します。ロードバランサの転送ルールをターゲットとするテレメトリー ポリシーを作成し、Cloud Trace で結果のトレースを表示します。
このドキュメントの例では、次のアーキテクチャを持つ e コマース アプリケーションを使用します。
- ウェブ ストアフロントの顧客トラフィックを受信するグローバル外部アプリケーション ロードバランサ。
- ストアフロントから内部カート、在庫、決済サービスにチェックアウト リクエストをルーティングするリージョン内部アプリケーション ロードバランサ。
サンプリング モードやトレース コンテキスト ヘッダーの処理など、分散トレースの仕組みについては、分散トレースの概要をご覧ください。
始める前に
プロジェクトで Cloud Trace API と Network Services API を有効にします。
gcloud services enable \ cloudtrace.googleapis.com \ networkservices.googleapis.comサポートされているロードバランサがデプロイされていることを確認します。詳しくは以下をご覧ください。
ロードバランサの転送ルールの名前とスコープをメモします。転送ルールのスコープは、ロードバランサの種類によって異なります。
- グローバル転送ルール: グローバル外部アプリケーション ロードバランサとクロスリージョン内部アプリケーション ロードバランサで使用されます。
- リージョン転送ルール: リージョン外部アプリケーション ロードバランサとリージョン内部アプリケーション ロードバランサで使用されます。
プロジェクト内の転送ルールを一覧表示するには、
gcloud compute forwarding-rules listコマンドを使用します。gcloud compute forwarding-rules list
必要なロール
テレメトリー ポリシーの構成とトレースの表示に必要な権限を取得するには、プロジェクトに対する次の Identity and Access Management（IAM）ロールを付与するよう管理者に依頼してください。
- テレメトリー ポリシーを作成、更新、削除する: Compute ネットワーク管理者（
roles/compute.networkAdmin）または Compute 管理者（roles/compute.admin） - Google Cloud コンソールでトレースを表示する: Cloud Trace ユーザー（
roles/cloudtrace.user）
ロードバランサがトレーススパンを Cloud Trace に書き込めるようにするには、プロジェクトの Cloud Trace エージェントのロール（roles/cloudtrace.agent）を次のサービス アカウントに付与します。
- Compute Engine サービス エージェント:
service-PROJECT_NUMBER@compute-system. - ネットワーク セキュリティ サービス エージェント:
service-PROJECT_NUMBER@gcp-sa-networksecurity. - バックエンドが独自のスパンを Cloud Trace にエクスポートする場合は、バックエンド ワークロードのサービス アカウント。このロールがないと、Cloud Trace にはロードバランサのスパンのみが表示され、トレースにバックエンド スパンは含まれません。
PROJECT_NUMBER は、使用するGoogle Cloud プロジェクト番号に置き換えます。
ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
テレメトリー ポリシーの構成
テレメトリー ポリシーは、次の形式の YAML ファイルで定義します。
name: "projects/PROJECT_ID/locations/LOCATION/telemetryPolicies/POLICY_NAME"
displayName: "DISPLAY_NAME"
telemetryTarget:
resources:
- "FORWARDING_RULE_URI"
tracingConfiguration:
samplingRate: SAMPLING_RATE
parentBasedSampling:
enabled: ENABLE_PARENT_BASED_SAMPLING
samplingRate: PARENT_BASED_SAMPLING_RATE
次の表に、テレメトリー ポリシーのフィールドを示します。
| フィールド | 説明 |
|---|---|
name |
テレメトリー ポリシーのリソース名。次のように置き換えます。
|
displayName |
省略可。テレメトリー ポリシーの人が読める形式の名前（DISPLAY_NAME）。 |
telemetryTarget.resources |
ポリシーが適用される転送ルールの完全なリソース名（
|
tracingConfiguration.samplingRate |
トレースするリクエストの割合（SAMPLING_RATE）。0.0（0%）～1.0（100%）の値で指定します。たとえば、0.01 はリクエストの 1% をサンプリングします。デフォルト値は 0.0 です。 |
tracingConfiguration.parentBasedSampling.enabled |
省略可。ロードバランサが受信 W3C traceparent ヘッダー（ENABLE_PARENT_BASED_SAMPLING）のサンプリング フラグを優先するかどうかは、true または false です。デフォルト値は false です。内部アプリケーション ロードバランサでのみサポートされます。 |
tracingConfiguration.parentBasedSampling.samplingRate |
省略可。トレースするアップストリーム サンプリング リクエストの割合（PARENT_BASED_SAMPLING_RATE）。0.0～1.0 の値で指定します。たとえば、1.0 は、アップストリーム クライアントまたはサービスがすでにサンプリングしたすべてのリクエストをトレースします。 |
外部ロードバランサのトレースを構成する
この例では、e コマース ストアフロントのグローバル外部アプリケーション ロードバランサの転送ルールで確率的サンプリングを構成します。サンプリング レートを 0.01 にすると、リクエストの 1% がトレースされます。これにより、エッジのレイテンシとエラーをキャプチャしながら、トラフィックが多いときでも Cloud Trace の取り込み費用を予測可能な範囲に抑えることができます。
storefront-tracing-policy.yamlという名前の YAML ファイルを作成します。cat <<EOF > storefront-tracing-policy.yaml name: "projects/PROJECT_ID/locations/global/telemetryPolicies/storefront-tracing-policy" displayName: "Tracing policy for the storefront load balancer" telemetryTarget: resources: - "//compute.googleapis.com/projects/PROJECT_ID/global/forwardingRules/FORWARDING_RULE_NAME" tracingConfiguration: samplingRate: 0.01 EOF次のように置き換えます。
PROJECT_ID:Google Cloud プロジェクトの IDFORWARDING_RULE_NAME: ロードバランサのグローバル転送ルールの名前
リージョン外部アプリケーション ロードバランサの場合は、ポリシー名の
globalを転送ルールのリージョンに置き換え、リージョン転送ルールの形式を使用します。gcloud beta network-services telemetry-policies importコマンドを使用して、テレメトリー ポリシーをインポートします。gcloud beta network-services telemetry-policies import storefront-tracing-policy \ --source=storefront-tracing-policy.yaml \ --location=global
内部ロードバランサのトレースを構成する
この例では、内部チェックアウト サービスと決済サービス用にリージョン内部アプリケーション ロードバランサを構成します。このポリシーでは、次のサンプリング設定を使用します。
- アップストリームのサンプリング決定を伴わないリクエストのベースライン
samplingRateは0.01（1%）です。 samplingRateが1.0（100%）の親ベースのサンプリング。これにより、ストアフロントまたはアップストリーム サービスですでにサンプリングされているすべてのチェックアウト リクエストが、内部ロードバランサを介してトレースされます。
ポリシーを構成する手順は次のとおりです。
checkout-tracing-policy.yamlという名前の YAML ファイルを作成します。cat <<EOF > checkout-tracing-policy.yaml name: "projects/PROJECT_ID/locations/REGION/telemetryPolicies/checkout-tracing-policy" displayName: "Tracing policy for the internal checkout load balancer" telemetryTarget: resources: - "//compute.googleapis.com/projects/PROJECT_ID/regions/REGION/forwardingRules/FORWARDING_RULE_NAME" tracingConfiguration: samplingRate: 0.01 parentBasedSampling: enabled: true samplingRate: 1.0 EOF次のように置き換えます。
PROJECT_ID:Google Cloud プロジェクトの IDREGION: 転送ルールのリージョン（例:us-central1）FORWARDING_RULE_NAME: ロードバランサのリージョン転送ルールの名前
クロスリージョン内部アプリケーション ロードバランサの場合は、ポリシー名のロケーションとして
globalを使用し、グローバル転送ルールの形式を使用します。テレメトリー ポリシーをインポートします。
gcloud beta network-services telemetry-policies import checkout-tracing-policy \ --source=checkout-tracing-policy.yaml \ --location=REGION
テレメトリー ポリシーを確認する
テレメトリー ポリシーが存在し、正しい転送ルールをターゲットにしていることを確認するには、gcloud beta network-services telemetry-policies describe コマンドを使用します。
gcloud beta network-services telemetry-policies describe POLICY_NAME \
--location=LOCATION
次のように置き換えます。
POLICY_NAME: テレメトリー ポリシーの名前LOCATION:globalまたはテレメトリー ポリシーのリージョン
ロケーション内のすべてのテレメトリー ポリシーを一覧表示するには、gcloud beta network-services telemetry-policies list コマンドを使用します。
gcloud beta network-services telemetry-policies list \
--location=LOCATION
テレメトリー ポリシーを更新する
サンプリング設定を変更する場合、または同じポリシーを別の転送ルールに適用する場合は、次の操作を行います。
ポリシーの YAML ファイルを編集します。たとえば、ストアフロント ポリシーを複数のグローバル転送ルールに適用するには、各転送ルールを
telemetryTarget.resourcesリストに追加します。telemetryTarget: resources: - "//compute.googleapis.com/projects/PROJECT_ID/global/forwardingRules/storefront-https-fr" - "//compute.googleapis.com/projects/PROJECT_ID/global/forwardingRules/cart-https-fr"更新したポリシーをインポートします。
gcloud beta network-services telemetry-policies import POLICY_NAME \ --source=POLICY_FILE \ --location=LOCATIONPOLICY_FILEは、ポリシー YAML ファイルのパスに置き換えます。
トレースを表示
トレースを構成してロードバランサ経由でトラフィックを送信したら、 Google Cloud コンソールでトレースを表示します。
Google Cloud コンソールで、[Trace エクスプローラ] ページに移動します。
Google Cloud プロジェクトを選択します。
[フィルタ] フィールドに、検査するトレースを検索するフィルタを入力します。（属性 ID やレイテンシのしきい値など）。
必要に応じて、特定のトレースを調査するには、ツールバーに移動して [トレース ID] をクリックし、トレース ID を入力します。
トレースをクリックすると、タイムライン ビューとグラフビューにそのスパンが表示されます。
ロードバランサのスパンを調べて、合計時間やリクエストを処理したバックエンドなどの詳細を確認します。
Trace エクスプローラの使用方法について詳しくは、トレースを検索して調査するをご覧ください。
トレースをログおよび指標と関連付ける
ロードバランサのトレーススパンをリクエストログと指標に関連付けることで、レイテンシやエラーの原因を特定できます。
トレースとログを関連付ける
バックエンド サービスでロギングを有効にすると、ロードバランサはサンプリングされたリクエストの各リクエスト ログエントリに trace フィールドを追加します。このフィールドの形式は次のとおりです。
projects/PROJECT_ID/traces/TRACE_ID
ロードバランサのログエントリからトレースを表示する
Google Cloud コンソールで、[ログ エクスプローラ] ページに移動します。
ロードバランサのログエントリを開きます。
ログエントリの概要で、トレース アイコンをクリックします。
[トレースの詳細を表示] を選択します。
[Trace エクスプローラ] ページでトレースが開きます。
トレースからロードバランサのログを表示する
Google Cloud コンソールで、[Trace エクスプローラ] ページに移動します。
トレースをクリックして [詳細] ペインを開きます。
[ログを表示] をクリックします。
リクエストのロードバランサのログエントリが表示されます。
トレースと指標を関連付ける
ロードバランサの指標のレイテンシ スパイクをトレーススパンの内訳と比較して、レイテンシがロードバランサで発生しているのか、バックエンドで発生しているのかを判断します。これらの指標は、Cloud Monitoring の Metrics Explorer で表示してクエリできます。次の指標を使用します。
- グローバル外部アプリケーション ロードバランサ:
loadbalancing.googleapis.com/https/total_latencies、loadbalancing.googleapis.com/https/backend_latencies - リージョン外部アプリケーション ロードバランサ:
loadbalancing.googleapis.com/https/external/regional/total_latencies - 内部アプリケーション ロードバランサ:
loadbalancing.googleapis.com/https/internal/total_latencies
トレースを無効にする
ロードバランサのリクエストのトレースを停止するには、次のいずれかを行います。
- ポリシーの
telemetryTarget.resourcesリストから転送ルールを削除し、更新されたポリシーをインポートします。 gcloud beta network-services telemetry-policies deleteコマンドを使用して、テレメトリー ポリシーを削除します。gcloud beta network-services telemetry-policies delete POLICY_NAME \ --location=LOCATION
ベスト プラクティス
分散トレースを構成する際は、次のベスト プラクティスを考慮してください。
- トラフィック量に合わせてサンプリング レートを調整する: トラフィック量の多い本番環境ワークロードでは、
samplingRateを0.01（1%）または0.001（0.1%）に設定して、オブザーバビリティと Cloud Trace の取り込み費用のバランスを取ります。 - 多層アーキテクチャに親ベースのサンプリングを使用する: 内部アプリケーション ロードバランサで親ベースのサンプリングを有効にして、アップストリームでサンプリングされたリクエストがすべての内部ホップでトレースされるようにします。
- バックエンドを計測する: バックエンド サービスで W3C トレース コンテキスト プロパゲータとともに OpenTelemetry SDK を使用して、バックエンド スパンがロードバランサが開始するトレースに参加するようにします。
トラブルシューティング
このセクションでは、一般的な問題とその解決策について説明します。
トレースが Cloud Trace に表示されない
Cloud Trace にトレースが表示されない場合は、次の操作を行います。
プロジェクトで Cloud Trace API が有効になっていることを確認します。
gcloud services enable cloudtrace.googleapis.com \ --project=PROJECT_ID必要なロールに記載されているサービス アカウントに Cloud Trace エージェントのロール（
roles/cloudtrace.agent）が付与されていることを確認します。テレメトリー ポリシーが正しい場所に存在し、正しい転送ルールをターゲットにしていることを確認します。詳細については、テレメトリー ポリシーを確認するをご覧ください。
構成済みの
samplingRateを確認します。トラフィック量またはサンプリング レートが低い場合、ロードバランサはトレースをすぐにキャプチャしないことがあります。トレースが機能することを確認するには、samplingRateを一時的に1.0に設定し、テストが完了したら本番環境のレートを復元します。
トレーススパンが切断されているか、不完全である
ロードバランサのスパンがアプリケーションのトレースの一部ではなく、個別のルートトレースとして表示される場合は、次の操作を行います。
内部アプリケーション ロードバランサの場合、テレメトリー ポリシーで親ベースのサンプリングが有効（
parentBasedSampling.enabled: true）になっていることを確認します。クライアント ワークロードとバックエンド ワークロードのサービス アカウントに Cloud Trace エージェントのロール（
roles/cloudtrace.agent）が付与されていることを確認します。これにより、スパンを Cloud Trace にエクスポートできます。アプリケーションが W3C トレース コンテキストの伝播が有効になっている OpenTelemetry SDK を使用していることを確認します。これにより、
traceparentヘッダーがサービス境界を越えて伝播されます。詳細については、OpenTelemetry コンテキストの伝播に関するドキュメントをご覧ください。