你的 Agent 在生产环境里到底在干什么？
Agent 系统跑着跑着就不知道它在干什么了——问题定位靠猜、成本算不清、质量没数据。这篇文章从实战角度聊怎么给 Agent 加上可观测性，让黑盒变透明。
传统后端出 bug，你翻日志、查链路、看监控，大概率能在半小时内定位根因。Agent 系统出问题了，你翻到的可能是满屏的 token 消耗、几十轮工具调用、以及一个暧昧的"我无法完成这个请求"。你甚至连它是哪一步开始跑偏的都看不出来。
我在做多 Agent 系统的初期就被这个问题折磨得不轻。一开始觉得"模型足够聪明，让它自己跑就行"，结果每次排查都要把整条 trace 翻出来一行行对。更糟的是，有些问题你根本复现不了——同样的输入、同样的配置，Agent 第二次跑可能就走了一条完全不同的路径。非确定性输出，是 Agent 可观测性最核心的敌人。
传统 APM 在 Agent 系统面前就是瞎子
如果你试图用 Datadog 或者 Prometheus 来监控 Agent，你会发现大部分指标都没用。请求耗时？Agent 的延迟分布取决于 LLM 响应时间、工具调用次数、上下文长度，每一轮都不一样。HTTP 状态码？Agent 的主要交互对象是 LLM API 和工具接口，200 OK 只代表请求发出去了，不代表模型做了正确的事。
Agent 系统需要的是另一套东西：
- 不是请求耗时，是每轮 LLM 调用的 token 消耗和首 token 时间
- 不是错误率，是工具调用成功率和失败模式
- 不是响应码，是模型的推理路径和每一步的决策依据
换句话说，传统 APM 关注的是"系统跑没跑崩"，Agent 可观测性要回答的是"Agent 做没做对"。这是两个完全不同的问题。
三大支柱：Trace、Metric、Log，但内涵变了
可观测性的经典三件套在 Agent 场景下都有了新的含义。
分布式追踪不再只追踪 HTTP 调用链。 Agent 的 trace 要记录的是：用户输入→LLM 推理→工具选择→工具执行结果→下一轮 LLM 推理→最终输出。每一步 span 都要带上前因后果——尤其要记录"模型当时的上下文是什么"、"它看到了哪些工具描述"、"为什么选择了这个工具而不是另一个"。这些信息决定了你能不能从 trace 里看懂 Agent 的决策过程。
指标的重点从 QPS 转向了成本和质量。 每轮对话的 input/output token 分布、按模型划分的成本占比、工具调用的重试率、幻觉检测评分。这些指标比 QPS 更能反映 Agent 系统的健康度。我见过一个 research agent，它的 web_search 工具在每条短查询上都抓取了完整页面，结果 token 消耗是预期的 3 倍——如果没有 token 用量追踪，这个问题可能永远不会被发现。
结构化日志的原则是"可复现"。 出 bug 的时候，你得能精确重现当时的情况——模型版本、system prompt、上下文状态、工具的输入输出，缺一个你都没法复现。要是你的日志只记了"Agent 返回错误"而没记当时的输入和上下文，这个日志就等于没记。
OpenTelemetry 目前是最靠谱的基础设施
2026 年，业界正在把 OpenTelemetry 当作 Agent 遥测数据的标准。选择 OTel 的理由很硬：厂商中立，不被任何可观测平台绑定；生态丰富，主流后端基本都支持；一次埋点，可以同时导出到多个后端。
OTel 的 GenAI 语义约定定义了标准的属性名，比如 gen_ai.system、gen_ai.request.model、gen_ai.usage.input_tokens。用这套标准，你从 Langfuse 切到 Arize 或者 Datadog 都不需要重写数据结构。这不是锦上添花——在生产环境中，可观测后端是经常要换的。
具体到实现，几个关键点值得注意：
-
Span 层级设计要合理。 入口 span 是整个请求，下一层是 LLM 调用 span 和工具执行 span 并行，工具内部再拆成更细的 span。层级太浅（整个 Agent 就一个 span）导致没法定位问题，太深（把每个函数调用都打 span）导致性能开销和存储成本飙升。经验值是：每次 LLM 调用打一个 span，每个工具调用打一个 span，足够了。
-
工具调用的输入输出必须记录完整。 这是 Agent trace 里最有价值但也最容易出问题的地方。工具参数可能包含敏感信息，输出可能巨大（比如 API 返回的完整 JSON 响应）。需要在采集和存储之间做平衡——记录参数结构但不记录具体值，或者对敏感字段做脱敏处理。
-
采样策略不能一刀切。 正常执行的 request 可以低比例采样（10% 足够），但错误 trace 必须全量采集。否则你会在定位问题时发现自己根本没有数据。
工具选型：按阶段选，别一上来就全上
做可观测性最忌讳的事就是一开始架一个大而全的平台，然后发现大部分功能都用不上。
我的建议分三步走：
第一周：先把结构化日志和成本追踪跑起来。 Langfuse 自托管或者 Helicone 都可以，主要目的是知道"每轮对话花了多少钱"以及"出错了当时的上下文是什么"。这是最低成本的保底方案，两三个小时就能搭好。
第二周：标准化追踪。 接入 OpenTelemetry SDK，把 Agent 执行链路完整 trace 出来。这一步的目的是把"黑盒"变成"半透明盒"——至少你能看到 Agent 走了哪些步骤、每一轮调用了什么工具。
第四周：搭指标仪表盘和告警。 核心指标就那几个：执行成功率、平均 token 消耗、工具调用失败率、延迟分布。把这三个指标放到一个页面上，每天扫一眼，基本能覆盖 90% 的异常发现。
季度级别的规划：评估（Eval）流水线。 把生产流量里的 sample 抽出评估集，用 LLM-as-judge 或者用户反馈评分来持续监控质量漂移。这一步不是必须一开始就做，但想在质量上持续提升，早晚得建。
几个被低估的坑
讲两个我在实战里踩过的。
第一个坑：工具输出的膨胀。 Agent 每轮调用工具后，工具返回的结果会被塞回上下文，既是下一轮推理的输入，也被 trace 记录。结果就是 trace 的存储量呈指数级增长。解决方案是对工具输出做截断和摘要——记录关键字段和结果的长度统计，不做全量存储。
第二个坑：循环检测。 两个 Agent 互相触发，在特定条件下可能产生无限循环。传统监控靠超时来兜底，但超时之后你连发生过循环都不知道。Span 深度监控可以解决这个问题——为 trace 设置最大深度，超过阈值自动触发 circuit breaker 并告警。
可观测性不是锦上添花
这是这个领域最被低估的事实。很多人觉得"先让 Agent 跑起来再说，监控后面再上"，但 Agent 系统的非确定性本质决定了没有可观测性你就没法迭代——你不知道改了一个 prompt 之后质量是变好了还是变差了，你也没法判断一次异常是你的代码 bug 还是模型行为变化。
生产环境 AI 系统的可靠性，不是从更好的模型开始的，是从更好的观察开始的。
评论
发表评论