为 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 API 和 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"

后续步骤