为 Cloud Trace 插桩

您可以针对 Cloud Trace 对应用进行插桩处理，以捕获分布式跟踪数据、检查各个请求的延迟时间，并在 Trace 控制台中查看各项服务的汇总延迟时间。

本文档简要介绍了插桩方法和配置选项。如需查看特定编程语言的分步说明，请参阅特定于语言的设置页面。

何时对应用进行插桩处理

如果系统未自动捕获用于验证性能或排查问题的轨迹数据，请对应用进行插桩。

对应用进行插桩，以收集有助于您了解其性能并排查故障的特定信息。 有几种开源插桩框架可收集日志、指标和跟踪记录数据，并将这些数据发送给任何供应商，包括 Google Cloud。对于智能体应用，某些框架可以收集您的提示和回答，或传递上下文，以便跟踪某些远程 Google Cloud MCP 服务器 调用。

如需对应用进行插桩，我们建议您使用不受制于供应商的开源插桩框架（例如 OpenTelemetry），而不是使用供应商和产品特有的 API 或客户端库。如需了解这些框架，请参阅 插桩和可观测性以及选择插桩方法。

如何对应用进行插桩处理

您可以使用多种方法来检测应用：

  • 建议：使用 OpenTelemetry，为应用配置一个 OTLP 导出器，该导出器会将跟踪记录数据发送到收集器，并配置收集器以使用 Telemetry (OTLP) API 将跟踪记录数据发送到您的 Google Cloud 项目。如需详细了解我们的建议，请参阅选择插桩方法。

  • 使用 OpenTelemetry 并使用 OTLP 导出器配置应用，该导出器会使用 Telemetry API 将跟踪记录数据发送到您的 Google Cloud 项目。

  • 如果您编写的应用在 Compute Engine 上运行，则可以使用 Ops Agent 和 OpenTelemetry 协议 (OTLP) 接收器从应用中收集跟踪记录和指标。Ops Agent 也可以收集日志，但不能使用 OTLP。如需了解详情，请参阅使用 Ops Agent 和 OTLP 以及 Ops Agent 概览。

  • 直接调用 Telemetry API 或 Cloud Trace API。

  • 对于 Spring Boot 应用，请将其配置为将收集的跟踪记录数据转发到 Cloud Trace。如需了解此过程，请参阅 Spring Cloud for Google Cloud：Cloud Trace。

  • 使用 Cloud Trace 客户端库或使用适用于 OpenTelemetry 的 Cloud Trace 导出器。

插桩示例

我们提供的插桩示例使用 OpenTelemetry：

创建自定义 span

虽然 OpenTelemetry 和客户端库允许您创建自定义 span，但您可能不需要手动创建，因为这些库会在 RPC 边界自动创建 span。

您还可以通过向现有 span 添加自定义注释和标记来添加与应用相关的信息，或者创建具有自己的注释和标记的新子 span，以更精细地跟踪应用的行为。

库通常会维护一个全局跟踪上下文，其中包含有关当前 span 的信息，包括其跟踪 ID 和采样状态。应用可以通过全局跟踪上下文访问当前 span。由于上下文是全局性的，因此请确保多线程应用在线程之间传播上下文，以保持跟踪数据的准确性。

强制跟踪记录采样

您无法强制对 span 进行抽样，因为请求路径中的每个组件都会做出独立的抽样决策。不过，您可以通过将轨迹标头中的 sampled 标志设置为 true 来影响下游组件。此设置用于向子级组件提示对请求进行抽样。 如需详细了解跟踪标头，请参阅上下文传播协议。

  • 您的应用：您可以配置插桩逻辑如何遵循 sampled 标志。例如，使用 OpenTelemetry 时，您可以使用 ParentBased 采样器来确保父级的采样标志得到遵守。

  • Google Cloud 服务：每项服务都会自行确定其跟踪支持。 一般来说，服务会接受父级抽样标志作为提示，同时强制执行自己的抽样率限制。

使用范例将指标和跟踪记录相关联

您可以使用范例将指标数据与跟踪记录相关联。范例是与指标测量相关联的代表性样本请求或 span。例如，范例可以包含指向跟踪记录的链接，以便您可以将指标与跟踪记录数据相关联。如需查看基于 OpenTelemetry 的示例，请参阅使用范例将指标和跟踪记录相关联。

您可能会在显示轨迹数据的 SQL 查询结果的信息中心图表中看到系统生成的示例。这些示例将特定查询结果直接关联到轨迹。如需了解详情，请参阅生成和显示轨迹范例。

配置项目和平台

本部分介绍了所需的 API 和 Identity and Access Management (IAM) 角色，并说明了如何为平台配置身份验证凭据。

启用 API

默认情况下， Google Cloud 项目已启用 Cloud Trace API 和 Telemetry API，您无需采取任何行动。不过，您的组织定义的安全限制条件可能已停用其中一个或全部这两个 API。如需了解相关问题排查信息，请参阅在受限的 Google Cloud 环境中开发应用。

启用 Telemetry 和 Cloud Trace API（如果尚未启用）。

启用 API 所需的角色

如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获取此权限。 了解如何授予角色。

启用 API

授予 IAM 角色

所需的 IAM 角色取决于您是在 Google Cloud 控制台中查看跟踪记录数据，还是将跟踪记录数据写入项目：

  • 如需获得使用 Google Cloud 控制台查看跟踪记录数据所需的权限，请让您的管理员为您授予项目的 Cloud Trace User (roles/cloudtrace.user) IAM 角色。

  • 如需获得使用 Cloud Trace API 写入跟踪记录数据所需的权限，请让您的管理员为您授予项目的 Cloud Trace Agent (roles/cloudtrace.agent) IAM 角色。

  • 如需获得使用 Telemetry API 写入跟踪数据所需的权限，请让您的管理员为您授予项目的 Cloud Telemetry Writer 角色 (roles/telemetry.writer) IAM 角色。

身份验证

本部分介绍了当应用在Google Cloud 上运行时以及在其他位置运行时如何进行身份验证。

在 Google Cloud上运行

当您的应用在 Google Cloud上运行时，通常不需要提供身份验证凭据。不过，即使托管在 Google Cloud上，某些语言客户端库也需要项目 ID。

验证您的 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"

后续步骤