模式矩阵 /模式白皮书/G5

G5 · Observability Harness · 可观测性

它解决什么问题

LLM Agent 没有可读的源码，模型权重是黑盒，唯一能看清它做了什么的窗口是 trace。可观测性没做好的 Agent 系统等于黑盒：监管不接、运维不敢、出事抓瞎。而且 Agent 的故障方式跟传统软件不同——传统软件在某个时间戳抛异常、stack trace 一目了然，Agent 是慢慢漂移：完全正确、仍然正确、看起来正确、自信但错、沉默灾难化，没有一个 crash point。

可观测性给 Agent 装上飞行数据记录器。它在每个 LLM call、每个 tool call、每个 sub-agent step 上采集遥测，把分散的 span 用同一个 trace id 串成完整调用链。监管来审能给完整 trace，出事能 root-cause 到具体哪一刀，产品和客服在做日常决策时能几分钟拿到证据，长期还能拿来优化。

为什么坐标是「治理 × 编排」

• 纵轴 · 治理：可观测性管的是所有 Agent 操作可观测、可重放，是治理的可追溯基础。审批门、爆炸半径、渐进承诺这三件事的记录都要靠它兑现，否则审批 log 没人看、爆炸半径出事没法复盘、信任档位变化没法解释。
• 横轴 · 编排：监控本质上是中心化协调问题——没有任何单个组件能看到完整 trajectory。tool 看不到 LLM 的 reasoning，LLM 看不到 tool 的副作用，sub-agent 看不到主 Agent 的 plan，只有 orchestrator 能拼出完整画面。它横切在所有 agent / tool / step 上，不属于某一条具体的 chain / route / loop，是跨切的编排。

核心机制

可观测性把 Agent 的遥测做成五个维度，缺一维就是盲点：

五维不是平铺的。log / metric / trace 是底层的事实记录层，cost / quality 是上层的斜率分析层。因为 Agent 故障是漂移不是阶跃，关键判断是监控 trajectory slope（变化率）而不是 threshold crossing（阈值穿越）——质量在转弯处下降、每个结果消耗的 token 在 cycle 间膨胀，这些斜率信号才是真正的故障征兆。跨进程靠 W3C Trace Context 的 traceparent 串联所有 span 到同一个 trace id，配合 OpenTelemetry GenAI Semantic Conventions 的标准 attribute，其中 gen_ai.request.model 与 gen_ai.response.model 分开记录，专治"请求 Sonnet 实际跑了 Haiku"这类传统 APM 看不见的 fallback。

适合的生产场景

• 任何企业 production Agent：合规与客户审计要求顶在那里，五维 telemetry 是底线。
• 多租户 SaaS：per-tenant cost attribution 是计费基础，也是跨租户隔离审计的入口。
• 多 model 系统：model swap 不可见就会变成长时间盲查，request.model != response.model 一查就暴露。
• 多 sub-agent 或长 conversation 系统：跨 Agent 不串 trace 就是黑盒，200K context 的演化必须可回放。

容易出错的地方

• Volume Overwhelms Signal（信号被淹）：一个忙碌的 Agent 每小时产生上千 span，dashboard 上两千条绿色里藏着三条红色没人看到。修正方式是 structured alerting——只对少数几个 production metric 做斜率告警（success rate、cost per task、tool accuracy、human override rate、latency p99），dashboard 看趋势不看个体 event，其余走采样加 query-on-demand。
• Trace Sampling Bias（采样偏差）：quality 评估有成本，10% 随机采样常见，但某些租户 case 偏向简单端时采到的全是简单 case，dashboard 显示 0.95 完美而困难 case 早已跌到 0.6。修正方式是 stratified sampling 加 SLA-tier 全采，按难度分层强制采样，Enterprise tier 100% 全采。
• Schema Drift（schema 漂移）：OpenTelemetry GenAI conventions 仍在演进，今天写死的字段明年被改名，dashboard、alert、cost engine 全部 broken。修正方式是 schema versioning 加 dual-write 加 migration window，stable convention 出来之前不写死任何字段。
• 自造 observability backend：trace store 加 query engine 加 dashboard 这套基础设施造一遍要数个工程师做一年。2026 年的工程纪律是直接接 Langfuse / Phoenix 这类成熟工具加一层薄业务扩展。

关键指标

• 五维采集完整度（健康区：cost 与 quality 两维不缺）：是否采了 AI-native 的成本与质量维度。少这两维，故障的斜率信号就消失，事后回放只剩"看起来一切正常"。
• trajectory slope 告警 vs threshold 告警的比例（健康区：以斜率告警为主）：是否在监控变化率。纯阈值告警在 Agent 时代基本失效，因为故障是漂移不是越线。
• 跨进程 trace 串联率（健康区接近 100%）：sub-agent 的 span 能否挂回父 trace id。串不上就只剩一堆孤立 span，无法 reconstruct 完整调用链。
• 采样的难度分布偏差（健康区：采样分布贴近实际分布）：采到的 case 难度是否代表整体。偏向简单端会让 quality dashboard 系统性高估真实质量。

最小骨架

每个 LLM call / tool call / sub-agent step 产出一个 span：
    填 OTel GenAI attribute（含 request.model 与 response.model 分开）
    cost = compute_cost(span)                 # 按 token 与实际 model 算
    若命中采样 → quality = llm_judge(span)     # hallucination / refusal / scope_creep
    emit 到 OTel pipeline（五维同时打）

跨 sub-agent：主 Agent inject W3C traceparent 到 carrier，
             sub-agent extract 后继续同一个 trace_id

trajectory_slope(tenant, metric, window)：返回变化率，不是阈值
query_for_audit(trace_id)：一个 trace_id 串起所有 span 供监管回放

工程落地三处必改：PRICING 换成实际 model 价格；llm_judge 换成真实的便宜 judge 调用（如 Haiku）而非 mock；business 槽里加 tenant_id / user_id / workflow_id，并把 emit 接到真实的 collector 或 Langfuse endpoint。

企业落地一例

2026 年 2 月一家月活 12 万中学生的 Edtech 公司，某个周二早上九点起作业反馈质量突然崩溃，投诉雪片般来——"AI 写错解题步骤"、"AI 拒答物理基础问题"。团队查 application log 正常、查 metric（request count / latency / error rate）正常、查 Datadog APM 显示一切 OK，卡了 6 个小时。最后一个工程师偶然打开 Anthropic Console，发现周一凌晨一次为了省成本的部署，把 main agent 的 model 从 Sonnet 4.6 切到了 Haiku 4.5，routing 配错导致所有题都路由到了 Haiku。复盘那段话很扎心："我们有 log 加 metric 加 trace，但所有这些都不告诉我 task 用的是哪个 model。LLM agent 的可观测性需要传统三大支柱再加 cost 和 quality 两个 AI-native 维度，少一个都查不出来。"传统 APM 看不到 cost per call 在 model swap 当时从 0.03 跌到 0.001（看起来是好事），也看不到 quality score 同一时刻从 0.92 跌到 0.71（这才是事），两条曲线一对照 model swap 立刻暴露。这就是为什么五维 telemetry 是底线。

在执行型 Agent 的工程实现里，可观测性可以用统一的活动事件抽象落地：把智能体的每一个活动事件用 Activity 加 Frame 统一表达，开发者就能看到执行过程的完整时间线（如 SSE 实时推送）。需要注意区分一件事——这里的"可观测"是让执行过程对开发者可见，不等于"Agent 对世界的感知"。前者是治理端的 telemetry，后者是感知模块的事。

与其他模式的关系

• 审批门（G1）/ 爆炸半径（G2）/ 渐进承诺（G3）：被依赖的基础设施。这三件事的记录——审批 log、爆炸半径触发、信任档位变化——都通过 trace_id 在 G5 收口。没有 G5，前三件都是没法兑现的承诺。
• 钩子流水线（G4）：互补。hook 本身要留痕，Stop hook 常用来挂审计 commit，是 G5 数据采集的入口之一。
• 推理 / 反思模块的 trace：CoT trace 是 reasoning 维度的可观测性，reflection 讲过的 silent correctness 正是 G5 用 trajectory slope 应对的对象。

一句话记住它

可观测性的最大用户不是 Agent，是人——它把"某个改动会影响哪些客户"这类占工程师大半时间的沟通与影响分析，从花两周开会压缩到花一小时查 trace，让被治理的 Agent 反而拿到更多自主权，因为组织知道最坏情况是被框住的。

本页属于 ADPS 33 模式白皮书。返回 模式矩阵与白皮书目录， 或查看配套 可运行代码目录。