排解分散式追蹤錯誤

本文說明如何使用 Cloud Trace 和遙測政策搭配 Secure Web Proxy，診斷及解決分散式追蹤問題。

Trace 中未顯示行跡

如果 Secure Web Proxy 產生的追蹤記錄時距未顯示在追蹤記錄探索器中，請檢查下列項目：

  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、區域或閘道名稱不符，Proxy 就無法接收政策設定。

  5. 檢查 Identity and Access Management (IAM) 權限：

    • 請確認您已將 Cloud Trace 使用者角色 (roles/cloudtrace.user) 授予使用者帳戶或服務帳戶，以便在 Google Cloud 控制台中查看範圍。
    • 請確認您已將 Cloud Trace 代理人角色 (roles/cloudtrace.agent) 授予下列服務帳戶：
      • service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com
      • service-PROJECT_NUMBER@gcp-sa-networksecurity.iam.gserviceaccount.com
      • 用戶端虛擬機器 (VM) 服務帳戶 (如果用戶端應用程式產生或傳播 span)

缺少子範圍或追蹤圖表損毀

如果 Secure Web Proxy 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。這項組合可確保 Proxy 只會對上游應用程式特別選取的要求進行取樣。
  3. 移除暫時的偵錯政策：如果在疑難排解期間套用了 100% 取樣 (samplingRate: 1.00)，請在偵錯程序完成後移除政策，或還原先前的設定。

後續步驟