AI智能体可观测性：日志、追踪与调试详解
内容提要
AI智能体可能无报错却答错，传统监控因此失效，需引入可观测性。核心手段包括结构化日志、OpenTelemetry追踪与调试：日志须带trace ID；追踪用gen_ai.*跨度构建父子瀑布图，定位重复工具调用；指标跟踪token成本与延迟。采集器可采样并脱敏。常用工具如Langfuse、LangSmith。
延伸解读
传统监控为何对AI智能体失效
传统监控依赖错误码和异常，但AI智能体可能无报错却给出错误答案，如客服智能体重复调用退款查询工具后基于第二次结果自信回复，全程无异常。这种“看似成功”的失败不会触发告警，健康检查也显示正常。因此，仅靠请求数、错误率等指标无法发现语义错误，必须引入可观测性来捕获模型调用、工具执行和推理步骤的结构化数据。
结构化日志与追踪的协同
结构化日志记录工具调用参数、结果长度和耗时，并附加trace ID，将分散日志关联到具体运行。追踪则通过OpenTelemetry的gen_ai.*跨度构建父子瀑布图，展示步骤嵌套关系。例如，瀑布图中同一chat跨度下出现两次refund_lookup调用，能直观暴露冗余工具调用。日志提供时间点细节，追踪揭示步骤连接，两者结合才能定位“为什么智能体这样做”。
令牌成本与延迟的指标监控
智能体的成本与延迟不再与请求数相关，而是与令牌消耗挂钩。应使用gen_ai.client.token.usage计数器分别记录输入和输出令牌，用gen_ai.client.operation.duration直方图跟踪每次模型调用耗时。分开记录输入输出令牌能发现系统提示词膨胀等问题。可设置告警：令牌使用率超基线两倍、操作时长p99超30秒、错误率超2%等，以捕捉失控循环或配额耗尽。
采集器管道：采样与隐私脱敏
OpenTelemetry采集器作为中间层，可在不修改应用代码的情况下处理采样和隐私。生产环境可对常规成功调用采样5-10%，但对错误、高令牌请求和完整智能体运行100%捕获。隐私方面，提示和补全内容应放在跨度事件而非属性中，便于在采集器层过滤或删除。例如，通过transform处理器删除gen_ai.prompt.content等键，避免敏感数据进入存储后端，满足合规要求。
Q&A
AI智能体可观测性是什么？为什么传统监控工具不够用？
AI智能体可观测性是指将智能体的每次模型调用、工具执行和推理步骤捕获为结构化数据，以便在出错时能精确重建发生了什么。传统监控工具不够用，因为智能体可能以看似成功的方式失败，例如输出格式正确但内容错误、不必要的工具调用或语义错误，这些都不会触发错误处理器，健康检查显示正常也无法反映智能体是否真正做对了。
如何为AI智能体实现结构化日志记录？
为AI智能体实现结构化日志记录，需要记录工具调用及其参数、返回结果、令牌消耗、每步耗时和错误，并以结构化格式而非自由文本记录。关键是将每条日志关联到具体的运行，通过附加当前trace ID实现，OpenTelemetry在设置追踪后会自动完成。例如使用Python的logging模块，在日志中附加trace_id、tool_name等字段。
OpenTelemetry的gen_ai.*跨度有哪些类型？如何用于追踪智能体？
OpenTelemetry GenAI语义约定定义了gen_ai.*跨度类型，包括：create_agent（定义智能体）、invoke_agent（单次智能体运行）、invoke_workflow（多智能体编排）、execute_tool（工具调用）和chat（模型推理调用）。每个跨度携带标准属性如gen_ai.request.model、gen_ai.usage.input_tokens等。通过嵌套这些跨度，可以构建父子关系，形成追踪瀑布图，展示智能体运行的完整步骤。
如何通过追踪瀑布图调试AI智能体的失败？
调试时，从用户报告的错误输出开始，获取产生该输出的trace ID，打开瀑布图，扫描异常宽的跨度、重复的工具调用或错误状态。例如，两个refund_lookup调用作为兄弟节点出现在同一个chat跨度下，表明存在冗余工具调用。找到问题步骤后，查看跨度的属性和事件，了解传递的参数和返回结果，通常无需重新运行即可理解错误。
如何跟踪AI智能体的令牌成本和延迟指标？
使用OpenTelemetry指标跟踪令牌成本和延迟，关键指标是gen_ai.client.token.usage（计数器）和gen_ai.client.operation.duration（直方图）。记录时，将输入和输出令牌分开记录，以保留成本结构。可设置警报条件，如令牌使用率超过基线两倍、操作持续时间p99超过30秒、错误率超过2%等。
在遥测管道中如何处理采样和隐私问题？
在OpenTelemetry Collector中，采样策略：开发环境全量捕获，生产环境对常规成功调用采样5-10%，对错误、高令牌请求和完整智能体运行100%捕获。隐私方面，将提示和补全内容放在跨度事件而非属性中，因为属性总是被索引和导出。可在Collector配置中删除或哈希敏感内容，无需修改应用代码。
有哪些常用的AI智能体可观测性工具？如何选择？
常用工具包括：自托管平台如Langfuse和Arize Phoenix，适合有数据驻留要求或成本控制需求的团队；托管SDK如LangSmith和Braintrust，提供快速集成和评估工具；代理网关如Helicone，零代码更改记录成本和用量；其他如AgentOps（时间旅行重放调试）和Datadog LLM Observability。选择时首先考虑部署模型，再考虑功能。
