用 Elastic Agent Builder 的 OTel 追踪构建 Token 成本仪表板

引言

每一个由 Elastic Agent Builder 驱动的对话，都会自动生成一条完整的OpenTelemetry（OTel）追踪。其中记录了每一次 LLM 调用、每一次工具执行、以及每一个环节的 Token 消耗量——所有这些数据默认都会被写入 Elasticsearch 的数据流中，您可以直接使用 ES|QL 进行查询。

然而，大多数团队只在系统出问题时才会翻看这些数据。这意味着他们错过了大量可以提前洞察的信息：用量趋势、延迟瓶颈、以及成本信号。本文旨在帮助您充分利用这些追踪数据，具体包括：

• 在 Kibana 中构建Token 成本仪表板；
• 设置阈值警报，当单次对话的 Token 消耗超过 256,000 时自动通知；
• 使用瀑布时间线精确定位智能体的耗时环节。

---

什么是 Agent Builder OTel 追踪？它捕获了哪些信息？

当您的智能体运行时，Agent Builder 会将整个执行过程记录为一条OpenTelemetry（OTel）追踪。您可以把这条追踪想象成一次对话回合的“电子收据”。

核心概念：Trace 与 Span

一条 Trace 由多个Span组成，每个 Span 代表一个有明确起止时间的操作单元。在 Agent Builder 中，每个 Span 都对应一个具体的动作：

• 一次 LLM 请求（调用 ChatGPT、Claude 等）
• 一次工具调用（执行某个函数或 API）
• 一次智能体的推理决策（ReAct 循环中的“思考”环节）

默认捕获的信息

默认情况下，每个 Span 会记录：

• 操作类型（例如chat、execute_tool）
• 开始和结束时间戳
• 耗时（Duration）
• Token 使用量（输入/输出 Token 数）
• 状态（成功/失败）
• 关联的对话 ID（经过哈希处理，保护隐私）

可选捕获的详细内容（需显式开启）

如果启用了高级隐私控制，还可以额外捕获：

• 用户输入的提示词（User Prompts）
• LLM 的完整回复（LLM Responses）
• 工具调用的参数和输出（Tool Details）
• 系统提示词（System Prompt）
• 真实的智能体/工具名称（而非匿名化后的名称）
• 真实的对话 ID（可用于关联用户会话，但涉及 PII）

重要提醒：仅在充分了解数据治理要求并确认合规的前提下，再启用上述详细捕获选项。

所有追踪数据的作用域都限定在您的Kibana 空间（Space）内，确保多团队间的数据隔离。

---

在 Kibana 中启用追踪与隐私控制

要开始采集追踪数据，请进入 Kibana 的Gen AI Settings（生成式 AI 设置），找到Agent Traces（智能体追踪）区域。

基础开关

确保以下开关处于开启状态（默认即为开启）：

• agentBuilder:tracing:enabled
  控制是否采集追踪数据。开启后，所有 Agent Builder 会话都会自动生成 OTel 追踪。

高级隐私控制（默认关闭）

在基础开关下方，您可以按需开启以下选项，以捕获更丰富的上下文信息：

配置项	作用
includeUserPrompts	记录用户的原始输入
includeLlmResponses	记录 LLM 的完整输出
includeToolDetails	记录工具调用的参数和返回值
includeSystemPrompt	记录系统级提示词
includeRealNames	保留真实的智能体/工具名称（否则会匿名化）
includeRealIds	保留真实的对话 ID（否则使用哈希值，可关联 PII）

开启这些选项后，追踪数据中会包含更多敏感信息，请务必确保有适当的数据治理策略。

---

Agent Builder 将 OTel 追踪数据存储到 Elasticsearch

Agent Builder 遵循OpenTelemetry 语义约定（Semantic Conventions），因此生成的 Span 具有标准的字段名称和层级结构。

Span 层级结构

一次典型的智能体对话追踪，其 Span 层级如下所示：

Span 名称	类型	捕获内容
invoke_agent <name>	CHAIN	整个对话回合的完整生命周期（从用户输入到最终回复）
invoke_agent <name>	AGENT	单次智能体执行循环：推理、工具调用、生成回复
chat <model>	LLM	单次 LLM 请求：模型名称、延迟、输入/输出 Token 数
execute_tool <toolName>	TOOL	单次工具调用：参数、执行耗时、返回结果

数据存储位置

追踪数据会写入每个 Kibana 空间专属的数据流，命名规则为：

traces-agent_builder.otel-<space-id>

例如，默认空间（default）的数据流为：

traces-agent_builder.otel-default

最佳实践：在查询时务必指定完整的数据流名称，避免使用通配符（如*），防止意外混合不同空间的数据。

使用 ES|QL 直接查询

您可以在 KibanaDiscover中直接运行 ES|QL 查询，例如查看最近 1 小时的所有 LLM 调用：

FROM traces-agent_builder.otel-default | WHERE @timestamp > NOW() - 1 HOUR | WHERE gen_ai.operation.name == "chat" | KEEP @timestamp, gen_ai.conversation.id, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens

内置 Skill：agent-builder-traces

Agent Builder 自带一个名为agent-builder-traces的 Skill（技能），当agentBuilder:tracing:enabled开启后会自动安装。您可以直接用自然语言向它提问，例如：

“过去 24 小时内，哪个对话消耗的 Token 最多？”

它会自动转换成相应的 ES|QL 查询并返回结果，大幅降低上手门槛。

---

用 OTel 追踪瀑布图调试智能体行为

当您需要深入排查某个智能体会话的性能问题或逻辑错误时，瀑布图（Waterfall View）是最直观的工具。

打开瀑布图

1. 在 Agent Builder 的对话界面中，找到您感兴趣的对话回合（Turn）；
2. 点击回合旁边的追踪图标（形如“连线”的按钮）；
3. 系统会跳转到 Kibana APM 或 Observability 的 Trace 详情页，以瀑布图形式展示该回合的所有 Span。

瀑布图

• 顶层 Span（invoke_agent）：整个回合的总耗时，帮助您快速判断本次调用是否超时。
• 嵌套的 chat Span：每个 LLM 请求的单独耗时，您可以对比不同模型或不同提示词下的响应速度。
• 嵌套的 execute_tool Span：每次工具调用的执行时间，以及传入的参数和返回结果（如果启用了隐私控制）。

通过瀑布图，您可以：

• 定位最慢的环节（例如某次工具调用耗时过长）；
• 检查调用顺序（智能体是否按预期先后调用了多个工具）；
• 发现错误 Span（状态码非 0 或包含异常信息）。

瀑布图是调试智能体“思维链”的绝佳利器，尤其适合排查 ReAct 循环中的异常中断或死循环问题。

---

如何基于追踪数据构建 Token 成本仪表板

开箱即用的仪表板

Elastic 提供了一个预置仪表板 ——[Elastic] Agent Builder Overview。您可以在 Gen AI Settings 的 Agent Traces 区域右上角点击“安装”按钮一键导入。

该仪表板包含以下核心面板：

• Token 用量与预估成本（按模型、按对话）
• 对话量（Conversation Volume）与平均延迟
• 智能体执行次数统计
• 工具调用频率与错误率

自定义仪表板（更灵活）

如果您想针对自己的业务指标做更精细的可视化，可以在 KibanaLens中直接基于 OTel 追踪数据流创建图表。

示例 1：Token 消耗最多的对话（Top 10）

• 数据源：traces-agent_builder.otel-<space-id>
• 图表类型：水平条形图（Horizontal Bar）
• X 轴：gen_ai.conversation.id（按降序排列，限制前 10 条）
• Y 轴：使用公式计算总 Token 数：

  sum(gen_ai.usage.input_tokens) + sum(gen_ai.usage.output_tokens)

这个图表可以让您快速定位哪些对话消耗了最多的 Token，便于进一步审查或优化。

示例 2：LLM 往返次数最多的对话

使用 ES|QL 直接创建 Lens 查询：

FROM traces-agent_builder.otel-<space-id> | WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend | WHERE gen_ai.operation.name == "chat" | STATS `Chat Span Count` = COUNT(*) BY `Conversation ID` = gen_ai.conversation.id, `Span Name` = span.name | SORT `Chat Span Count` DESC | LIMIT 100

该查询统计每个对话中包含的chatSpan 数量，即 LLM 往返次数。往返次数越多，说明智能体的推理链越长，成本也相应更高。

使用 Skill 辅助创建

您也可以借助agent-builder-tracesSkill，直接用自然语言描述想要的图表，它会帮您生成对应的 ES|QL 或 Lens 配置。

---

为 Agent Builder 对话设置 Token 成本警报

Token 消耗是 LLM 成本最直接的驱动因素。一次失控的对话（例如陷入死循环的 ReAct 推理）可能在几分钟内消耗掉数万甚至数十万 Token，远超预期。

创建 ES|QL 阈值规则

1. 进入 Kibana →Observability→Alerts→Manage Rules；
2. 点击Create rule，选择Elasticsearch query类型；
3. 输入以下 ES|QL 查询（以默认空间为例）：

FROM traces-agent_builder.otel-default WHERE @timestamp > NOW() - 15 minutes | STATS total_tokens = SUM(gen_ai.usage.input_tokens) + SUM(gen_ai.usage.output_tokens) BY gen_ai.conversation.id | WHERE total_tokens > 256000 | KEEP gen_ai.conversation.id, total_tokens

• 筛选最近 15 分钟内的追踪数据；
• 按对话 ID 聚合，计算每个对话的总 Token 消耗（输入+输出）；
• 仅保留总 Token 超过256,000的对话；
• 输出对话 ID 和 Token 总数。

配置执行频率与通知动作

• 执行频率：建议每 15 分钟运行一次；
• 通知动作：配置Slack 消息或PagerDuty 事件，将告警信息推送给运维团队。告警载荷中会包含gen_ai.conversation.id，方便您直接定位到具体的对话进行审查。