Cloud Trace 概览

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

借助 Trace，您可以测量端到端请求延迟时间，比较一段时间内的性能趋势，并查明哪些下游依赖项导致了延迟。如需查看关联跟踪记录和日志的演示，请参阅将跟踪记录和日志结合使用以进行根本原因分析。

环境支持

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

组件

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

跟踪客户端

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

跟踪界面

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

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

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

自动跟踪配置

以下配置会自动捕获跟踪记录数据：

  • App Engine 标准环境

    • 第一代运行时会自动拦截跟踪 span 并将其发送到 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 客户端库，因为它们更简单，并且会以 OpenTelemetry 定义的 OTLP 格式导出跟踪记录数据。如需了解详情，请参阅对 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 会舍弃发送到特定于跟踪记录的 Telemetry 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 支持的一项服务。Trace 服务名称为 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 存储桶中的 span 30 天

IAM 角色

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

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

后续步骤