访问轨迹和 span

本文档介绍了如何访问和查看 Gemini Enterprise 应用生成的跟踪记录和 span。跟踪记录和 span 可提供有关应用内请求的性能和执行流程的详细洞见，例如在使用助理或智能体时。

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

主要概念

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

概念 说明
跟踪记录 跟踪记录是一组 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)。

  • 启用 Enable instrumentation of OpenTelemetry traces and logs 可观测性设置。根据智能体类型，您可以在应用级配置中（对于 Core Assistant 智能体）或在智能体的配置 标签页内（对于 Workflow Builder 员工自制智能体和 Deep Research 智能体）启用此设置。如需了解详情，请参阅 管理可观测性设置。

数据保留

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

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

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

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

    前往 Trace 探索器

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

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

    Google Cloud 控制台中 Trace Explorer 的屏幕截图，显示了 span 列表，其中包含“Span ID”“Trace ID”“开始时间”“时长”和“服务”列。

过滤和搜索跟踪记录

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

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

访问智能体的跟踪记录

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

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

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

跟踪记录摘要表

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

  • 状态：跟踪记录的当前状态（目前显示 Unset）。
  • 跟踪记录 span ID：跟踪记录 span 的唯一标识符。点击 span ID 链接可深入查看其详细信息。
  • Span 名称：对 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 中的提示和响应内容（例如提示文本和生成的回答）才会显示。否则，内容会被修订或省略。如需更改这些设置，请参阅 管理可观测性设置。