访问轨迹和 span

本文档介绍了如何访问和查看 Gemini Enterprise 应用生成的跟踪记录和 span。跟踪记录和 span 可让您详细了解应用内请求的性能和执行流程，例如在使用助理或代理时。

您可以使用 Trace 探索器查看跟踪记录数据，也可以直接在各个智能体中使用智能体的跟踪记录标签页查看。

主要概念

本部分介绍了与 Gemini Enterprise 中的可观测性相关的关键概念。

概念 说明
Trace 跟踪记录是一组 span，表示单个请求或事务在流经不同服务和组件时的状态。

例如，跟踪记录表示请求的整个生命周期。这包括用户向 Gemini Enterprise 助理提问、Gemini Enterprise 助理回答，以及回答触发的任何后续操作（例如发送电子邮件）。
Span span 是跟踪记录中的单个计时工作单元。它表示特定操作，例如函数调用、API 请求或数据库查询。每个 span 都包含开始和结束时间、唯一 ID 以及与其他 span 的关系等详细信息。这些关系共同构成一个跟踪记录。
Span 日志 Span 日志是与特定 Span 关联的带时间戳的自由格式消息或事件。它们提供有关 span 执行的详细上下文信息，帮助用户调试问题并了解请求的流程。

准备工作

请确保您已备好：

  • Gemini Enterprise Admin 角色或 Google Cloud 控制台 Gemini Enterprise User 角色。

  • 现有的 Gemini Enterprise Web 应用。如需了解如何创建新应用，请参阅创建应用。

  • 如需访问跟踪记录，您必须拥有 Cloud Trace User 角色 (roles/cloudtrace.user)。

  • 启用启用 OpenTelemetry 跟踪记录和日志的插桩可观测性设置。具体启用方式取决于智能体类型：对于核心助理智能体，在应用级配置中启用；对于Workflow Builder员工自制智能体和 Deep Research 智能体，在智能体的配置标签页中启用。如需了解详情，请参阅管理可观测性设置。

数据保留

Gemini Enterprise 应用生成的跟踪记录和 span 存储在 Google Cloud 项目的 Cloud Trace 中，其保留期限由 Cloud Trace 管理。默认情况下，Cloud Trace 会将 span 数据保留 30 天；超过保留期限的数据会自动删除。如需了解权威且最新的保留值，请参阅 Cloud Trace 配额和限制文档中的 Cloud Trace 保留期限。

在 Trace 探索器中访问跟踪记录

如需使用 Trace Explorer 访问跟踪记录和 span，请按照以下步骤操作：

  1. 在 Google Cloud 控制台中，前往 Trace 探索器页面。

    前往 Trace 探索器

  2. 选择创建 Gemini Enterprise 应用的 Google Cloud 项目。您会看到项目的所有 span。

  3. 在表格中，点击 Span ID 可查看跟踪记录详情，包括 span 的时长和其他属性。

    Google Cloud 控制台中的 Trace Explorer 屏幕截图，其中显示了 span 列表，包含 span ID、跟踪记录 ID、开始时间、时长和服务等列。

过滤和搜索跟踪记录

在项目的 Trace 探索器中，您可以使用以下过滤条件、查询参数和属性来隔离和分析 Gemini Enterprise 代理和数据连接器执行情况：

  • 分面过滤条件：
    • 服务：按 AssistantService 或 connectorsexecution 过滤，以隔离平台代理和数据连接器请求路径。
    • Span：按 /AssistantService.StreamAssist 过滤，以找到根用户轮次 span，或搜索 execute_tool <tool_name> 和 invoke_connector <connector> 等子 span。
  • 直接跟踪 ID 查找：使用标准的 32 字符 W3C 跟踪 ID 直接查找跟踪，该 ID 可从 StreamAssist 的 x-cloud-trace-context 响应标头中提取。
  • 自定义属性：通过 execute_tool 或 invoke_connector span 上的 gemini_enterprise.assist_token 属性进行查询，将轮次级旧版辅助令牌映射到 W3C 跟踪瀑布图。
  • 资源属性：每个导出的 span 都带有 cloud.region，即
  • 资源属性：每个导出的 span 都带有 cloud.region 属性。此属性表示处理请求的 Gemini Enterprise 服务位置，例如 global、us 或 eu。您可以按此属性进行过滤，以比较不同区域的效果。当数据连接器在一个位置成功但在另一个位置失败时，此比较非常有用。此值表示应用所在的位置，而不是托管第三方数据源的区域。如需应用此过滤条件，请参阅应用 span 过滤条件。

访问智能体的跟踪记录

您还可以在智能体的跟踪记录标签页中直接查看各个智能体的跟踪记录 span，该标签页会按时间顺序详细汇总 span 跟踪记录和父子执行结构。

如需访问智能体的跟踪记录，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往您的应用，然后点击代理。
  2. 选择要检查的智能体，然后点击跟踪记录标签页。

跟踪记录摘要表

跟踪记录标签页中的主表会显示每个跟踪记录 span 的以下信息：

  • 状态：跟踪记录的当前状态（目前显示为未设置）。
  • 跟踪 span ID：跟踪 span 的唯一标识符。点击 span ID 链接以深入了解其详细信息。
  • Span Name：对 span 正在执行的工作的简要说明。Gemini Enterprise 数据连接器的 span 示例包括：
    • execute_tool <tool_name>：在 Agent Runtime 中的工具分派层期间发出（例如 execute_tool federated_search）。
    • invoke_connector <connector>：由连接器执行层生成，用于表示对特定连接器（例如 invoke_connector jira 或 invoke_connector servicenow）的请求逻辑，该逻辑会替换默认的服务端 RPC span。
  • Span 类型：Span 的类型。选项包括：
    • Agent to Tool：从代理到外部工具的调用（可重复用于 execute_tool 和 invoke_connector 操作）。
    • Invoke Agent：智能体的调用。
    • Agent to Model：从代理到大语言模型的请求。
  • 时长：完成跟踪 span 所需的时间（以分钟为单位）。
  • 输入：发送到 span 的输入数据或消息（如有）。
  • 输出：span 返回的输出结果（如果有）。
  • 开始时间：span 开始执行的确切时间戳。

详细跟踪视图

点击跟踪 span ID 会打开一个详情页面，其中包含：

  1. 摘要：查看基准元数据，包括开始时间、时长和 span 总数。您可以点击在 Cloud Trace 中查看，或在图表和时间轴视图按钮之间切换。
  2. 可视化：在图形层次结构或时间轴视图之间切换，显示所有跟踪 span 的父子关系。
  3. 所选 span 的详细信息：选择单个 span 即可显示详细信息部分，其中可能包括：
    • 摘要：显示 span 的名称、目标服务、具有此操作的 span 总数以及总时长（以秒为单位）。
    • 日志：查看相关事件详情（如果已配置）。点击查看日志可直接前往标准日志。
    • 评估：显示所有评估结果（如果已配置）。
    • 输入和输出：完整的请求和响应载荷。
    • 日志和事件：此 span 执行期间发生的事件列表。
    • 堆栈轨迹：span 执行失败时的错误详情。
    • 元数据和链接：引用相关 Cloud Explorer 实体的链接。
    • 属性：资源标记和其他键值对可观测性参数。

Google Cloud 控制台中“跟踪记录”标签页的屏幕截图，其中显示了 span 的时间轴和 span 摘要

父子 span 层次结构

对于数据连接器执行，单个 W3C 跟踪记录中的父子 span 嵌套有助于精确定位延迟时间或错误发生的位置：

  1. /AssistantService.StreamAssist：发起请求的根 C++ 平台 span。
  2. invoke_agent core_assistant：智能体执行 span。
  3. execute_tool <tool_name>：活跃工具执行 span（例如 execute_tool federated_search）。
  4. invoke_connector <connector_name>（例如 invoke_connector jira 或 invoke_connector servicenow）：连接器执行 span，表示对第三方端点的请求生命周期。

实验性生成式 AI 语义惯例遥测

除了稳定的遥测数据之外，Gemini Enterprise 跟踪 span 还包含基于 OpenTelemetry 生成式 AI 语义惯例的更丰富的元数据。OpenTelemetry 将这些惯例归类为开发状态。该状态适用于可能发生更改或被移除的早期规范，不应在生产环境中依赖这些规范。由于这些惯例尚不稳定，因此此 Gemini Enterprise 遥测功能处于实验阶段。这些 span 包含描述智能体、模型和工具活动的 gen_ai.* 属性，例如智能体和工具执行以及提示和回答步骤。

只有在可观测性设置允许记录提示输入和回答输出时，跟踪 span 中的提示和回答内容（例如提示文本和生成的回答）才会显示。否则，内容会被隐去或省略。如需更改这些设置，请参阅管理可观测性设置。