Cloud Trace 概览

Cloud Trace 是一款适用于 Google Cloud的分布式跟踪系统，可跟踪请求延迟时间，并帮助您排查服务和生成式 AI 应用中的性能瓶颈。通过从Google Cloud 服务和已插桩的应用收集延迟数据，Trace 可帮助您了解请求在微服务架构中是如何处理的，并确定相关日志。

轨迹可帮助您解答以下问题：

  • 您的应用处理某特定请求需要多长时间？
  • 为什么请求需要很长时间才能完成？
  • 为什么有些请求花费的时间比其他请求长？
  • 我的应用请求的整体延迟是多少？
  • 应用延迟是否随着时间的推移而增加或减少？
  • 如何缩短应用延迟时间？
  • 您的应用的依赖项有哪些？

如需了解如何将跟踪记录和日志结合使用以进行根本原因分析，请参阅博文排查分布式应用问题：将跟踪记录和日志结合使用以进行根本原因分析。

如需了解如何分析应用，请参阅 Cloud Profiler。

环境支持

在以下环境中，Trace 在 Linux 上运行：

组件

Trace 包含一个跟踪客户端，该客户端会收集跟踪记录并将其发送到您的 Google Cloud 项目。然后，您可以使用Google Cloud 控制台查看和分析跟踪客户端收集的数据。如需了解数据模型，请参阅轨迹和 span。

跟踪客户端

跟踪客户端会从您的应用中收集延迟时间和 span 数据，并将其导出到您的 Google Cloud 项目。您可以根据环境和要求，通过对应用代码进行插桩处理来自动或手动收集轨迹数据。

跟踪界面

如需查看和分析 span 数据，您可以使用Google Cloud 控制台中的 Trace 探索器和可观测性分析页面：

  • Trace 探索器：显示有关跟踪记录数据的汇总信息，并可让您详细检查各个跟踪记录。汇总的延迟时间数据会显示在热图上，您可以使用指针探索该热图。如需限制显示哪些数据，您可以添加过滤条件。 您还可以查看和探索各个 span 和 trace：

  • Observability Analytics：提供 SQL 查询界面。您的查询可以联接轨迹数据和日志数据，并且您可以表格或图表的形式查看查询结果。如果您创建了关联的 BigQuery 数据集，则可以使用 BigQuery 分析您的轨迹数据。如需了解详情，请参阅查询和分析轨迹。

具有自动跟踪功能的配置

以下配置会自动捕获轨迹数据：

  • App Engine 标准环境

    • 第一代运行时会自动拦截跟踪区间并将其发送到 Cloud Trace。如需了解详情，请参阅旧版捆绑服务概览。

    • 第二代运行时会自动捕获总体请求延迟时间，并将 X-Cloud-Trace-Context HTTP 标头添加到请求中。如需了解详情，请参阅运行时支持时间表。

  • Cloud Run functions 和 Cloud Run

    对于传入和传出的 HTTP 请求，延迟时间数据会自动发送到 Trace。

对应用进行插桩

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

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

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

虽然您可以使用 Cloud Trace 客户端库对应用进行插桩，但我们建议您使用 OpenTelemetry。OpenTelemetry 库比 Trace 客户端库更可取，因为它们更简单，并且以 OTLP 格式导出跟踪记录数据，而 OTLP 格式是由 OpenTelemetry 定义的。如需了解详情，请参阅对 Trace 进行插桩和 Cloud Trace 的客户端库。

Cloud Trace 和智能体应用

为了解代理应用的运行情况，请将它们配置为在调用远程 Google Cloud MCP 服务器时收集提示和回答或生成 span。提示和回答有助于您了解代理应用使用的推理。记录工具调用的 span 可帮助您确认工具调用、调用状态和请求延迟时间。

多个插桩示例展示了如何配置应用以收集提示和回答。这些示例依赖于 OpenTelemetry。如需了解详情，请参阅如何对生成式 AI 应用进行插桩处理。

Google Cloud MCP 服务器可以生成轨迹 span。如需了解详情，请参阅使用 Trace 调查 MCP 调用。

可注入轨迹数据的 API

您可以使用 Telemetry API 或 Cloud Trace API 将跟踪记录数据发送到您的项目。我们建议使用 Telemetry API，原因如下：

  • 此 API 可与开源 OpenTelemetry 生态系统兼容，并且其限制通常比 Cloud Trace API（一种专有 Google Cloud API）的限制更宽松。

  • 您的跟踪记录数据以通常与 OTLP 定义的 proto 文件一致的格式存储。在存储之前，某些字段可能会从 OpenTelemetry 特定的数据类型转换为 JSON 数据类型。如需了解存储格式，请参阅跟踪记录数据的架构。

  • 对于基于收集器的轨迹数据导出，您的插桩不依赖于特定于 Google Cloud的导出器。

  • 某些功能（如“应用监控”）依赖于仅在您将跟踪记录数据发送到 Telemetry API 时才可用的信息。

如需防止 Google Cloud 项目存储跟踪记录数据，请停用 Cloud Trace API。停用 Cloud Trace API 会产生以下影响：

  • Google Cloud 服务不会将跟踪记录数据发送到您的项目。
  • Google Cloud 使用错误代码回复发送到 Cloud Trace API 端点的请求。
  • Google Cloud Observability 会舍弃发送到特定于跟踪记录的遥测 API 端点的跟踪记录数据。请勿停用 Telemetry API，因为该 API 可以接收日志、指标和跟踪记录数据。

如果您管理某个组织，并希望阻止使用 Cloud Trace，请创建组织政策限制条件。

VPC Service Controls 支持

Google Cloud 服务和应用可以使用 Cloud Trace API 或 Telemetry API 将跟踪记录数据发送到您的项目。Cloud Trace 提供的可视化服务使用 Cloud Trace API 来提取其显示的跟踪记录数据：

  • Cloud Trace 是 VPC Service Controls 支持的一项服务。轨迹服务名称为 cloudtrace.googleapis.com。 如需了解详情和限制，请参阅支持的产品：Cloud Trace。

  • Telemetry API 是 VPC Service Controls 支持的一项服务。服务名称为 telemetry.googleapis.com。如需了解详情和限制，请参阅支持的产品 - Telemetry API。

如需设置默认值以指定存储轨迹数据的 Google Cloud 区域以及客户管理的密钥是否对数据进行加密，请使用 Observability API。您还可以使用此 API 配置关联的 BigQuery 数据集，以便使用 BigQuery 服务查询轨迹数据；以及配置轨迹范围，以便汇总存储在多个项目中的轨迹数据。

  • Observability API 是 VPC Service Controls 支持的一项服务。服务名称为 observability.googleapis.com。如需了解详情和限制，请参阅支持的产品：Observability API。

详情请参阅以下内容：

Cloud Trace 和数据驻留

如果您因数据驻留或影响级别 4 (IL4) 要求而使用 Assured Workloads，则不应使用 Cloud Trace API 发送跟踪记录 span。

如需防止 Google Cloud 项目存储跟踪记录数据，请停用 Cloud Trace API。请勿停用 Telemetry API，因为该 API 可以接收日志、指标和跟踪记录数据。

Trace 保留

类别 保留期限
存储在 _Trace 存储桶中的 span 30 天

IAM 角色

Cloud Trace 使用 Identity and Access Management (IAM) 来控制对资源的访问权限。如需查看 Cloud Trace API 和 Telemetry API 角色的列表，请参阅使用 IAM 控制访问权限。

由于 Telemetry API 是一个使用方 API，因此向 Telemetry API 发送数据需要您指定配额项目，并授予应用的服务账号使用该配额的权限。如需了解详情，请参阅 Telemetry API：身份验证。

后续步骤