为 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，从而更精细地跟踪应用的行为。由于上下文是全局性的，因此更新上下文的多线程应用必须使用适当的隔离。

何时提供身份验证凭据

通常，在运行应用时，您无需为应用提供身份验证凭证，也无需在应用中指定项目 ID。 Google Cloud Google Cloud对于某些语言， 即使您在 运行应用 Google Cloud，也需要指定项目 ID Google Cloud 。此外，如果您为 Google Kubernetes Engine 使用 Autopilot 模式，或者为 GKE 启用 Workload Identity Federation，则必须 将应用配置为使用 Workload Identity Federation for GKE。

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

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

如何强制跟踪请求

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

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

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

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

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

配置项目和平台

  1. 确保已启用 Cloud Trace API。

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

    启用 Cloud Trace API。

    启用 API 所需的角色

    如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。

    启用 API

  2. 配置您的平台。

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

    • Google Cloud：当您的应用在 运行应用时，您无需向客户端库提供服务帐号形式的身份验证凭据 。Google Cloud不过，必须 确保您的 Google Cloud 平台已启用 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 和其他开源代码库的链接，请转到您所用语言的设置页面。