引言每一个由 Elastic Agent Builder 驱动的对话都会自动生成一条完整的OpenTelemetryOTel追踪。其中记录了每一次 LLM 调用、每一次工具执行、以及每一个环节的 Token 消耗量——所有这些数据默认都会被写入 Elasticsearch 的数据流中您可以直接使用 ES|QL 进行查询。然而大多数团队只在系统出问题时才会翻看这些数据。这意味着他们错过了大量可以提前洞察的信息用量趋势、延迟瓶颈、以及成本信号。本文旨在帮助您充分利用这些追踪数据具体包括在 Kibana 中构建Token 成本仪表板设置阈值警报当单次对话的 Token 消耗超过 256,000 时自动通知使用瀑布时间线精确定位智能体的耗时环节。什么是 Agent Builder OTel 追踪它捕获了哪些信息当您的智能体运行时Agent Builder 会将整个执行过程记录为一条OpenTelemetryOTel追踪。您可以把这条追踪想象成一次对话回合的“电子收据”。核心概念Trace 与 Span一条 Trace 由多个Span组成每个 Span 代表一个有明确起止时间的操作单元。在 Agent Builder 中每个 Span 都对应一个具体的动作一次 LLM 请求调用 ChatGPT、Claude 等一次工具调用执行某个函数或 API一次智能体的推理决策ReAct 循环中的“思考”环节默认捕获的信息默认情况下每个 Span 会记录操作类型例如chat、execute_tool开始和结束时间戳耗时DurationToken 使用量输入/输出 Token 数状态成功/失败关联的对话 ID经过哈希处理保护隐私可选捕获的详细内容需显式开启如果启用了高级隐私控制还可以额外捕获用户输入的提示词User PromptsLLM 的完整回复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 追踪数据存储到 ElasticsearchAgent Builder 遵循OpenTelemetry 语义约定Semantic Conventions因此生成的 Span 具有标准的字段名称和层级结构。Span 层级结构一次典型的智能体对话追踪其 Span 层级如下所示invoke_agent 智能体名invoke_agent 智能体名 - AGENTchat 模型名execute_tool 工具名chat 模型名execute_tool 工具名chat 模型名Span 名称类型捕获内容invoke_agent nameCHAIN整个对话回合的完整生命周期从用户输入到最终回复invoke_agent nameAGENT单次智能体执行循环推理、工具调用、生成回复chat modelLLM单次 LLM 请求模型名称、延迟、输入/输出 Token 数execute_tool toolNameTOOL单次工具调用参数、执行耗时、返回结果数据存储位置追踪数据会写入每个 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内置 Skillagent-builder-tracesAgent Builder 自带一个名为agent-builder-traces的 Skill技能当agentBuilder:tracing:enabled开启后会自动安装。您可以直接用自然语言向它提问例如“过去 24 小时内哪个对话消耗的 Token 最多”它会自动转换成相应的 ES|QL 查询并返回结果大幅降低上手门槛。用 OTel 追踪瀑布图调试智能体行为当您需要深入排查某个智能体会话的性能问题或逻辑错误时瀑布图Waterfall View是最直观的工具。打开瀑布图在 Agent Builder 的对话界面中找到您感兴趣的对话回合Turn点击回合旁边的追踪图标形如“连线”的按钮系统会跳转到 Kibana APM 或 Observability 的 Trace 详情页以瀑布图形式展示该回合的所有 Span。瀑布图顶层 Spaninvoke_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 追踪数据流创建图表。示例 1Token 消耗最多的对话Top 10数据源traces-agent_builder.otel-space-id图表类型水平条形图Horizontal BarX 轴gen_ai.conversation.id按降序排列限制前 10 条Y 轴使用公式计算总 Token 数sum(gen_ai.usage.input_tokens) sum(gen_ai.usage.output_tokens)这个图表可以让您快速定位哪些对话消耗了最多的 Token便于进一步审查或优化。示例 2LLM 往返次数最多的对话使用 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 阈值规则进入 Kibana →Observability→Alerts→Manage Rules点击Create rule选择Elasticsearch query类型输入以下 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方便您直接定位到具体的对话进行审查。
