为 Cloud Trace 插桩

本文档概述了如何对 Cloud Trace 应用进行插桩处理。如需详细了解如何设置 Cloud Trace，请参阅特定语言的设置页面。

Cloud Trace 会为您的应用提供分布式跟踪数据。对应用进行插桩处理后，您可以检查单个请求的延迟时间数据，并在 Cloud Trace 控制台中查看整个应用的总体延迟时间。

何时对应用进行插桩处理

如果系统未自动捕获轨迹数据，您需要对应用进行插桩处理才能收集此类数据。

您可以对应用进行插桩处理，以便其收集应用专用信息。有几种开源检测框架可让您从应用收集指标、日志和跟踪记录，并将这些数据发送给任何供应商，包括 Google Cloud。如需对应用进行插桩，我们建议您使用开源且与供应商无关的插桩框架（例如 OpenTelemetry），而不是供应商和产品专用 API 或客户端库。

如需了解如何使用供应商中立的插桩框架对应用进行插桩，请参阅 插桩和可观测性。

如何对应用进行插桩

如需对应用进行插桩以收集跟踪记录数据，您可以执行以下任一操作：

何时创建 Span

Cloud Trace 客户端库通常会维护一个全局跟踪上下文，其中包含有关当前 span 的信息（包括其跟踪记录 ID 以及是否对跟踪记录进行采样）。这些库通常在 RPC 边界上创建 span。但是，如果默认创建算法不足以满足您的需求，您可能需要创建 span。

当前活跃 span 可由全局跟踪上下文访问，后者有时封装在跟踪器对象中。您可以通过对现有 span 使用自定义注释和标记来添加与应用相关的信息，也可以创建具有各自注释和标记的新子 span，从而更精细地跟踪应用的行为。由于上下文是全局性的，因此更新上下文的多线程应用必须使用适当的隔离。

何时提供身份验证凭据

在 Google Cloud 上运行应用时，您通常无需为应用提供身份验证凭据，也无需在应用中指定 Google Cloud 项目 ID。对于某些语言，即使您在 Google Cloud 上运行，也需要指定 Google Cloud 项目 ID。此外，如果您使用 Google Kubernetes Engine 的 Autopilot 模式，或者启用了适用于 GKE 的工作负载身份联合，则必须将应用配置为使用适用于 GKE 的工作负载身份联合。

如果您在 Google Cloud 之外运行，则需要向应用提供身份验证凭据。您还需要在应用中指定 Google Cloud 项目 ID。

有关详情，请转到特定语言的设置页面。

如何强制跟踪请求

除非您的应用始终对每个跨度进行采样，否则通常无法强制对请求进行端到端跟踪，因为端到端请求中的每个组件都会做出自己的采样决策。不过，您可以通过向轨迹标头添加 sampled 标志（并将此标志设置为 true）来影响此决定。此设置是对子组件进行请求抽样的提示。如需详细了解跟踪标头，请参阅用于上下文传播的协议。

对于代码归您所有的下游组件，您必须确定您的插桩逻辑是否遵循 sampled 标志。例如，在使用 OpenTelemetry 进行插桩时，您可以使用 ParentBased 采样器来确保遵循父级采样标志。

将跟踪信息记录到 Cloud Trace 的 Google Cloud 服务通常会接受父级采样标志作为提示；不过，大多数服务还会对采样进行速率限制。每项 Google Cloud 服务都会确定自己是否支持跟踪、如何使用父级抽样标志，以及抽样的速率限制。

如何将指标数据与跟踪记录数据相关联

您可以通过将范例附加到指标数据点，将分布值指标数据与轨迹相关联。只要您完成必要的配置步骤，推荐的插桩库 OpenTelemetry 就会自动添加这些范例。如需了解详情，请参阅使用范例将指标和跟踪记录相关联。

配置项目和平台

  1. 确保已启用 Cloud Trace API。

    默认情况下，Google Cloud 项目已启用 Cloud Trace API，因此您无需执行任何操作。不过，贵组织定义的安全限制条件可能会导致该 API 被停用。如需了解问题排查信息，请参阅在受限的 Google Cloud 环境中开发应用。

    Enable the Cloud Trace API.

    Enable the API

  2. 配置您的平台。

    您可以在 Google Cloud 和其他平台上使用 Cloud Trace。

    • Google Cloud：当您的应用在 Google Cloud 上运行时，您无需向客户端库提供服务账号形式的身份验证凭据。不过，您必须确保 Google Cloud Platform 已启用 Cloud Trace API 访问权限范围。

      对于以下配置，默认的访问权限范围设置包含 Cloud Trace API 访问权限范围：

      如果您使用自定义访问权限范围，则必须确保已启用 Cloud Trace API 访问权限范围。例如，如果您使用 Google Cloud CLI 创建 GKE 集群，并指定 --scopes 标志，请确保范围包含 trace.append。以下命令演示了如何设置 --scopes 标志：

      gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

    • 在本地和其他位置运行：如果您的应用在 Google Cloud 之外运行，则必须向客户端库提供服务账号形式的身份验证凭据。必须向该服务账号授予 Cloud Trace Agent (roles/cloudtrace.agent) 角色。如需了解角色，请参阅使用 IAM 控制访问权限。

      Google Cloud 客户端库会使用应用默认凭据 (ADC) 查找应用的凭据。您可以通过以下三种方式之一提供这些凭据：

      • 运行 gcloud auth application-default login

      • 将服务账号放置在操作系统的默认路径中。以下列出了 Windows 和 Linux 的默认路径：

        • Windows：%APPDATA%/gcloud/application_default_credentials.json

        • Linux：$HOME/.config/gcloud/application_default_credentials.json

      • 将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为服务账号的路径：

        Linux/macOS

          export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

        Windows

          set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

        PowerShell：

          $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

后续步骤

如需详细的配置信息、示例以及指向 GitHub 和其他开源代码库的链接，请前往您所用语言的设置页面。