排查分布式跟踪错误

本文档介绍了在使用 Cloud Trace 和遥测政策与 Secure Web Proxy 时，如何诊断和解决分布式跟踪方面的问题。

轨迹未显示在 Trace 中

如果 Secure Web Proxy 生成的轨迹 span 未显示在轨迹探索器中，请检查以下各项：

  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 较低（例如，0.01 表示 1% 或 0.001 表示 0.1%），则可能不会对单个手动测试请求进行抽样。如需确认跟踪功能是否正常运行，请暂时将政策更新为使用 100% 抽样 (samplingRate: 1.00)，然后恢复生产速率。

  4. 验证目标网关资源 URI：验证遥测政策中的 telemetryTarget.resources 字段是否指定了 Secure Web Proxy 网关的确切完全限定资源网址或简称。

    //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) 权限：

    • 确保您已向自己的用户账号或服务账号授予 Cloud Trace User 角色 (roles/cloudtrace.user) 角色，以便在 Google Cloud 控制台中查看 span。
    • 请确保您已向以下服务账号授予 Cloud Trace Agent 角色 (roles/cloudtrace.agent)：
      • service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com
      • service-PROJECT_NUMBER@gcp-sa-networksecurity.iam.gserviceaccount.com
      • 客户端虚拟机 (VM) 服务账号（如果客户端应用生成或传播 span）

缺少子 span 或轨迹图损坏

如果 Secure Web Proxy 代理 span 显示为独立的或断开连接的根跟踪记录，而不是应用请求的子 span，请执行以下操作：

  1. 启用基于父级的抽样：在遥测政策 YAML 文件中，验证 parentBasedSampling.enabled 是否已设置为 true。

    tracingConfiguration:
  samplingRate: 0.01
  parentBasedSampling:
    enabled: true

    如果基于父级的抽样处于停用状态，Secure Web Proxy 可能会舍弃上游抽样的轨迹（如果这些轨迹与本地 samplingRate 不匹配）。

  2. 检查 OpenTelemetry 插桩：验证您的应用是否使用已启用分布式跟踪上下文传播的 OpenTelemetry SDK。如需了解详情，请参阅 OpenTelemetry TraceContext 传播器文档。

轨迹提取量意外偏高

如果您发现跟踪记录中的跟踪数据提取量或费用高于预期，请执行以下操作：

  1. 降低基准采样率：在高流量生产环境中，将 samplingRate 设置为较小的比例，例如 0.01 (1%) 或 0.001 (0.1%)。
  2. 依赖于基于父级的抽样：保持较低的网关基准值 samplingRate 并启用 parentBasedSampling。这种组合有助于确保代理仅对上游应用专门选择的请求进行抽样。
  3. 移除临时调试政策：如果您在问题排查期间应用了 100% 抽样 (samplingRate: 1.00)，请在调试过程完成后移除该政策或恢复到之前的配置。

后续步骤