追踪你的 Agent 账单：将Elastic Agent Builder 内置的 OTel 追踪数据转化为 Kibana 中的 Token 成本仪表

每次 Elastic Agent Builder 对话都会自动生成完整的 OpenTelemetry 追踪数据。LLM 调用、工具执行、Token 计数等所有信息，默认都会记录到 Elasticsearch 的数据流中，您可以使用 ES|QL 进行查询。大多数团队通常只在出现问题时才查看这些数据，这意味着他们错过了本可以更早发现的使用趋势、延迟瓶颈和成本信号。本文将介绍如何在 Kibana 中构建 Token 成本仪表板，设置当对话 Token 数量超过 256,000 时触发的警报，并利用瀑布时间线精确查看您的 Agent 将时间花费在了何处。

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

当您的 Agent 运行时，Agent Builder 会将发生的一切记录为 OpenTelemetry (OTel) 追踪。您可以将追踪理解为一次对话轮次的“收据”。每个 LLM 请求、工具调用和 Agent 动作都被记录为 Elasticsearch 中的一个独立 Span，Span 代表一个工作单元或操作。在选择启用后，用户提示、LLM 响应、工具输出和对话 ID 等额外详细信息将作为结构化的 Span 属性，捕获在聊天 Span 上。所有这些数据都限定在您的 Kibana 空间内。

如何在 Kibana 中启用 Agent 追踪和隐私控制

Kibana 中 Agent Builder 追踪设置，显示了追踪开关和 OTel 追踪数据的高级隐私控制

要开始捕获追踪数据，请确保您的环境中 Gen AI 设置的 Agent Traces 下的以下开关处于活动状态：

• agentBuilder:tracing:enabled — 此 Gen AI 设置管理追踪数据的收集，默认已启用。

位于默认追踪开关下方的高级隐私控制还允许您收集消息内容。虽然提示和工具输出默认会被屏蔽，但您可以选择启用它们以支持更强大的追踪：

• agentBuilder:tracing:includeUserPrompts
• agentBuilder:tracing:includeLlmResponses
• agentBuilder:tracing:includeToolDetails
• agentBuilder:tracing:includeSystemPrompt
• agentBuilder:tracing:includeRealNames: 保留真实的 Agent/工具名称，而不是匿名化为自定义名称。
• agentBuilder:tracing:includeRealIds: 保留实际的对话标识符，而不是默认的哈希版本。这意味着追踪数据会收集原始 ID，这可以将追踪与特定的用户会话（个人身份信息 PII）关联起来。

仅当您了解 Agent 处理的数据类型并已实施适当的数据治理时，才应启用这些功能。

Agent Builder 如何在 Elasticsearch 中存储 OTel 追踪数据

Agent Builder OTel 追踪数据的瀑布视图，显示了 Span 层次结构、LLM 调用持续时间和工具执行

Agent Builder 利用 OpenTelemetry 语义约定，生成了一个结构化的 Span 层次结构，提供了 Agent 内部逻辑的细粒度视图：

追踪数据被写入每个 Kibana 空间的专用数据流，从而使对话数据保持清晰隔离。要在 Discover 中查询您的追踪数据，请直接针对您空间的索引：

FROM traces-agent_builder.otel-<space-id>

对于默认空间，索引是 traces-agent_builder.otel-default。如果高级隐私控制已开启，那么这些 Span 属性也将随原始 Span 一起发送到追踪数据流。此索引允许您查询原始消息内容，以查看对话中实际说了什么。最佳实践是避免使用通配符，以防止混合来自无关空间的数据。

Agent Builder 附带一个名为 agent-builder-traces 的内置技能，当 agentBuilder:tracing:enabled 开启时会自动安装。您可以使用它直接询问有关追踪数据的问题，从而轻松探索 Agent 行为，而无需从头编写 ES|QL。

如何使用 OTel 追踪瀑布视图调试 Agent 行为

追踪瀑布视图以时间线的形式显示了 Agent Builder 会话的每个步骤。要打开它，请导航到对话 UI 中的特定轮次，然后选择追踪图标。

Agent Builder 对话 UI 中的追踪图标，用于打开 OTel 追踪瀑布视图

这将启动一个瀑布时间线，详细分解 Agent 执行的每个步骤。在最顶层，您将看到 invoke_agent 父 Span，其中包含 Agent 运行的完整端到端持续时间。在其下方嵌套的是聊天 Span，每个代表一个 LLM 请求，并精确显示模型响应所需的时间。与此同时，还有 execute_tool Span，每个工具调用对应一个，您可以在其中查看调用了哪个工具、接收了哪些参数以及运行了多长时间。这使您能够追踪 Agent 遵循的精确序列，找出时间瓶颈，并查看错误发生的位置。

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

Discover 为您提供原始追踪数据，但大多数团队希望获得操作问题的答案，例如“我们今天消耗了多少 Token？”、“哪个工具调用最频繁？”以及“本周有多少独立用户与 Agent 互动？”。这些问题需要直接针对追踪数据构建仪表板。

有一个名为 [Elastic] Agent Builder Overview 的 Elastic 托管的开箱即用仪表板，可以通过点击 GenAI 设置中 Agent Traces 部分的右上角进行安装。

它包含 Token 使用和成本、对话量和延迟、Agent 执行以及工具调用频率和错误等基本详细信息。

Elastic Agent Builder Overview 仪表板显示了 Token 使用、成本指标和 LLM 请求计数

然而，自定义仪表板可能更高效。如果您想要更定制化的内容，可以直接针对 OTel 追踪索引构建 Lens 面板。一些有用的起始面板包括：

1. 按 Token 消耗量计算最活跃的对话

创建一个针对 traces-agent_builder.otel-<space-id> 的水平条形图。将 x 轴设置为 gen_ai.conversation.id，并按降序排序，限制为前 10 个。将 y 轴设置为 gen_ai.usage.input_tokens 加上 gen_ai.usage.output_tokens 的总和。输入公式为：

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

1. LLM 往返次数最多的对话

可以使用一个简单的 ES|QL 查询来创建此可视化，查询如下所示：

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

还有一个 dashboard-management 技能，可用于帮助使用自然语言创建追踪可视化。

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

Token 消耗是基于 LLM 的 Agent 最直接的成本杠杆。一次失控的对话可能会在任何人注意到之前就耗尽您一个月的预算。

Elastic 警报允许您直接针对追踪数据定义阈值规则。导航到 Observability > Alerts > Manage Rules > Create Rule，并选择 Elasticsearch query 作为规则类型。

一个当任何单个对话超过 256,000 Token 时触发的规则，其 ES|QL 形式如下：

FROM traces-agent_builder.otel-<space-id>
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 分钟运行一次，并配置操作以发送 Slack 通知或打开 PagerDuty 事件。警报负载中的 gen_ai.conversation.id 值将为您提供要检查的确切对话。

Agent Builder 可观测性的未来展望

Agent 追踪为您提供了超越调试的可见性。一旦您根据 Agent Builder 追踪数据构建了仪表板并配置了警报，您就可以实时了解 Agent 在生产环境中的行为。如果您还没有这样做，请在您的 Kibana 空间中启动 Agent Builder，确保追踪已启用，并进行几次对话。检查 Discover，调出瀑布视图，看看您的 Agent 到底在幕后做了些什么。

这是关于 Agent Builder 可观测性系列文章的第一篇。接下来，我们将深入探讨如何使用 agent-builder-traces 技能进行会话式数据查询，从追踪数据构建自定义评估管道，以及使用追踪数据将对话历史反馈给 Agent。您的 Agent 一直保守着秘密。现在是时候让它们“开口说话”了。