使用 Cloud Trace 跟踪入站流量

本文档介绍了如何使用 Cloud Trace 为应用负载均衡器配置分布式跟踪。您需要创建一个遥测政策，该政策以负载均衡器的转发规则为目标，然后在 Cloud Trace 中查看生成的跟踪记录。

本文档中的示例使用具有以下架构的电子商务应用：

  • 一个全球外部应用负载均衡器，用于接收网店的客户流量。
  • 一个区域级内部应用负载均衡器，用于将结账请求从店面路由到内部购物车、库存和支付服务。

如需了解分布式跟踪的工作原理（包括采样模式和跟踪记录上下文标头处理），请参阅分布式跟踪概览。

准备工作

  1. 在项目中启用 Cloud Trace API 和 Network Services API：

    gcloud services enable \
    cloudtrace.googleapis.com \
    networkservices.googleapis.com

  2. 确保您已部署受支持的负载均衡器。详情请参阅以下内容：

  3. 记下负载均衡器的转发规则的名称和范围。转发规则的范围取决于负载均衡器类型：

    • 全球转发规则：由全球外部应用负载均衡器和跨区域内部应用负载均衡器使用。
    • 区域级转发规则：由区域级外部应用负载均衡器和区域级内部应用负载均衡器使用。

    如需列出项目中的转发规则，请使用 gcloud compute forwarding-rules list 命令：

    gcloud compute forwarding-rules list

所需的角色

如需获得配置遥测政策和查看跟踪记录所需的权限，请让管理员为您授予项目的以下 Identity and Access Management (IAM) 角色：

  • 如需创建、更新或删除遥测政策，请执行以下操作：Compute Network Admin (roles/compute.networkAdmin) 或 Compute Admin (roles/compute.admin)
  • 如需在 Google Cloud 控制台中查看跟踪记录，请执行以下操作：Cloud Trace User (roles/cloudtrace.user)

如需让负载均衡器将跟踪 span 写入 Cloud Trace，请向以下服务账号授予项目的 Cloud Trace Agent 角色 (roles/cloudtrace.agent)：

  • Compute Engine 服务代理：service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com
  • Network Security 服务代理：service-PROJECT_NUMBER@gcp-sa-networksecurity.iam.gserviceaccount.com
  • 后端工作负载的服务账号（如果后端将自己的 span 导出到 Cloud Trace）。如果没有此角色，Cloud Trace 仅显示负载均衡器 span，并且跟踪记录不包含后端 span。

将 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

遥测政策的资源名称。替换以下内容：

  • PROJECT_ID：您的 Google Cloud 项目的 ID。
  • LOCATION：遥测政策的位置，必须与政策所针对的转发规则的范围一致。对于全球转发规则，请使用 global。 对于区域级转发规则，请使用转发规则的区域，例如 us-central1。
  • POLICY_NAME：遥测政策的名称。名称长度必须介于 4 到 63 个字符之间，以小写字母开头，只能包含小写字母、数字和连字符，并且以小写字母或数字结尾。
displayName 可选。遥测政策的人类可读名称 (DISPLAY_NAME)。
telemetryTarget.resources

政策适用的转发规则的完整资源名称 (FORWARDING_RULE_URI) 列表。您最多可以指定 50 个资源。请采用以下某种格式：

  • 全球转发规则：//compute.googleapis.com/projects/PROJECT_ID/global/forwardingRules/FORWARDING_RULE_NAME
  • 区域级转发规则：//compute.googleapis.com/projects/PROJECT_ID/regions/REGION/forwardingRules/FORWARDING_RULE_NAME
替换以下内容：
  • FORWARDING_RULE_NAME：转发规则的名称
  • REGION：转发规则所在的区域，例如 us-central1
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 会跟踪上游客户端或服务已采样的所有请求。

为外部负载均衡器配置跟踪

此示例在电子商务店面的全球外部应用负载均衡器的转发规则上配置概率采样。0.01 的采样率会跟踪 1% 的请求，这会捕获边缘延迟时间和错误，同时在流量较高时保持 Cloud Trace 注入费用可预测。

  1. 创建一个名为 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 项目的 ID
    • FORWARDING_RULE_NAME：负载均衡器的全局转发规则的名称

    对于区域级外部应用负载均衡器，请将政策名称中的 global 替换为转发规则的区域，并使用区域级转发规则格式。

  2. 使用 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%)，因此，已在店面或由任何上游服务采样的每个结账请求都会通过内部负载均衡器进行跟踪。

如需配置政策，请执行以下操作：

  1. 创建一个名为 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 项目的 ID
    • REGION：转发规则所在的区域，例如 us-central1
    • FORWARDING_RULE_NAME：负载均衡器的区域级转发规则的名称

    对于跨区域内部应用负载均衡器，请在政策名称中使用 global 作为位置，并使用全球转发规则格式。

  2. 导入遥测政策：

    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

更新遥测政策

如需更改采样设置，或将同一政策应用于其他转发规则，请执行以下操作：

  1. 修改 YAML 格式的政策文件。例如，如需将 storefront 政策应用于多个全球转发规则，请将每个转发规则添加到 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"

  2. 导入更新后的政策：

    gcloud beta network-services telemetry-policies import POLICY_NAME \
    --source=POLICY_FILE \
    --location=LOCATION

    将 POLICY_FILE 替换为政策 YAML 文件的路径。

查看跟踪记录

配置跟踪记录并通过负载均衡器发送流量后，在 Google Cloud 控制台中查看跟踪记录：

  1. 在 Google Cloud 控制台中，前往 Trace 探索器页面。

    前往 Trace 探索器

  2. 选择您的 Google Cloud 项目。

  3. 在过滤条件字段中，输入过滤条件以查找要检查的跟踪记录。例如，属性 ID 或延迟时间阈值。

  4. （可选）如需探索特定跟踪记录，请前往工具栏，点击跟踪记录 ID，然后输入跟踪记录 ID。

  5. 点击某个跟踪记录，即可在时间轴和图表视图中查看其 span。

  6. 检查负载均衡器 span，查看总时长和处理请求的后端等详细信息。

如需详细了解如何使用 Trace 探索器，请参阅查找和探索跟踪记录。

将跟踪记录与日志和指标相关联

您可以将负载均衡器跟踪记录 span 与请求日志和指标相关联，以找出延迟时间或错误的来源。

将跟踪记录与日志相关联

如果您在后端服务上启用日志记录，负载均衡器会为采样请求的每个请求日志条目添加 trace 字段。该字段采用以下格式：

projects/PROJECT_ID/traces/TRACE_ID

查看负载均衡器日志条目中的跟踪记录

  1. 在 Google Cloud 控制台中，前往 Logs Explorer 页面。

    转到 Logs Explorer

  2. 展开负载均衡器日志条目。

  3. 在日志条目摘要中，点击跟踪记录图标。

    Logs Explorer 中日志条目摘要旁边的跟踪记录图标。

  4. 选择查看跟踪记录详情。

跟踪记录会在 Trace 探索器页面中打开。

从跟踪记录中查看负载均衡器日志

  1. 在 Google Cloud 控制台中，前往 Trace 探索器页面。

    前往 Trace 探索器

  2. 点击跟踪记录以打开详细信息窗格。

  3. 点击查看日志。

系统会显示该请求的负载均衡器日志条目。

将跟踪记录与指标相关联

将负载均衡器指标中的延迟时间峰值与跟踪记录 span 细分进行比较，以确定延迟时间是源自负载均衡器还是源自后端。您可以在 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

停用跟踪功能

如需停止跟踪负载均衡器的请求，请执行以下操作之一：

最佳做法

配置分布式跟踪时，请考虑以下最佳实践：

  • 根据流量大小调整采样率：对于高流量生产工作负载，请使用 0.01 (1%) 或 0.001 (0.1%) 的 samplingRate，以平衡可观测性与 Cloud Trace 注入费用。
  • 对多层架构使用基于父级的采样：在内部应用负载均衡器上，启用基于父级的采样，以便在每个内部跃点中跟踪上游采样的请求。
  • 对后端进行插桩：在后端服务中使用带有 W3C 跟踪记录上下文传播器的 OpenTelemetry SDK，以便后端 span 加入负载均衡器启动的跟踪记录。

问题排查

本部分介绍了常见问题及其解决方法。

跟踪记录未显示在 Cloud Trace 中

如果跟踪记录未显示在 Cloud Trace 中，请执行以下操作：

  1. 确保您的项目中已启用 Cloud Trace API：

    gcloud services enable cloudtrace.googleapis.com \
    --project=PROJECT_ID

  2. 验证是否已向所需角色中列出的服务账号授予 Cloud Trace Agent 角色 (roles/cloudtrace.agent)。

  3. 验证遥测政策是否存在于正确的位置，以及是否定位到正确的转发规则。如需了解详情，请参阅验证遥测政策。

  4. 检查配置的 samplingRate。如果流量或采样率较低，负载均衡器可能不会立即捕获跟踪记录。如需确认跟踪是否正常运行，请暂时将 samplingRate 设置为 1.0，然后在完成测试后恢复生产速率。

跟踪 span 已断开连接或不完整

如果负载均衡器 span 显示为单独的根跟踪记录，而不是应用跟踪记录的一部分，请执行以下操作：

  1. 对于内部应用负载均衡器，请验证遥测政策中是否已启用基于父级的采样 (parentBasedSampling.enabled: true)。

  2. 验证客户端和后端工作负载的服务账号是否具有 Cloud Trace Agent 角色 (roles/cloudtrace.agent)，以便将其 span 导出到 Cloud Trace。

  3. 验证您的应用是否使用启用了 W3C 跟踪记录上下文传播的 OpenTelemetry SDK，以便 traceparent 标头跨服务边界传播。如需了解详情，请参阅 OpenTelemetry 上下文传播文档。

后续步骤