Cloud Trace 插桩

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

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

何时对应用进行插桩处理

如果系统未自动捕获轨迹数据，您需要对应用进行插桩以收集这些数据。

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

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

如何对应用进行插桩

如需对应用进行插桩 (instrument) 处理以收集轨迹数据，您可以执行以下任一操作：

何时创建 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 模式，或者启用 Workload Identity，则必须将应用配置为使用 Workload Identity。

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

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

如何强制跟踪请求

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

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

将跟踪信息记录到 Cloud Trace 的 Google Cloud 服务通常接受父级采样标志作为提示；但是，大多数服务也会限制采样率。每项 Google Cloud 服务都会确定其是否支持跟踪、父级采样标志的使用方式以及采样速率限制。

配置项目和平台

  1. 确保已启用 Cloud Trace API。

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

    启用 Cloud Trace API。

    启用 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 代理 (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 和其他开源代码库的链接，请前往您所用语言的设置页面。