为 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 权限。如果您创建了项目，则可能已通过所有者角色 (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上运行时， 通常无需提供身份验证凭据。 不过，某些语言客户端库需要项目 ID，即使 托管在 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"

后续步骤