用途：为生产环境的 AI 智能体或 LLM 功能定义可观测性规范。核心观点是 LLM 系统观测的基本单位是 trace（模型看到的与做的一切），因为失败的是行为而非在线率。若需要先定义智能体应做什么，应改用 agent-spec。
主要能力：产出 trace schema，规定每请求的 span 及必填字段；定义健康、质量、成本、行为四类指标并附阈值与责任人；给出采样与保留策略；给出隐私说明。
必要输入：系统形态（单次 LLM 调用、RAG 或带工具的多步智能体）；流量与成本敏感度；本场景下“行为异常”的 2–3 个主要失败模式；现有可观测性栈（Datadog、Langfuse、OTel 或自建），规范应融入而非绕开。
Trace schema：每请求一个 trace，每次模型调用、检索、护栏检查、工具执行各为一个 span。根 span 记录请求 id、用户/会话（假名）、功能与提示版本、模型 id、总 token、总成本、延迟、终态；模型调用记录完整输入上下文（或内容寻址引用）、输出、结束原因、输入输出 token、缓存 token 占比、temperature；检索记录 query、top-k id 与分数、进入上下文的 chunk；工具调用记录名称、参数、结果（或引用）、时长、错误；护栏记录检查名、判定及动作（拦截/改写/标记）；用户信号记录编辑、重新生成、点赞、放弃，关联到 trace id。检验标准：仅凭 trace 即可回放任意事故。
指标与告警：健康类（错误率、p50/p95 延迟、超时率、429/5xx 率）触发呼叫；成本类（每请求成本 p50/p99、每请求 token、缓存命中率、日支出对预算）对 p99 与预算消耗告警；质量代理类（格式/模式违规率、拒答率、有据性检查失败率、抽样 judge 分数、重生成/编辑率）以滚动基线的漂移告警；行为类（每任务步数、工具错误率、循环检测、被护栏拦截的未授权动作尝试）对最后一项呼叫。
采样与保留：100% 请求记录元数据；错误、护栏命中、负面用户信号保留完整内容 100%，其余随机抽 1–10%；完整内容保留 30–90 天，元数据 12 个月以上，事故 trace 永久固定。隐私需说明日志内容所在位置、可访问者、删除请求路径，广泛共享前需脱敏或限制访问。
限制与反模式：不要只记录输入输出；不要对平均成本或平均延迟告警；不要对 100% 流量跑 judge 评分；不要视可观测性为上线期脚手架；智能体能执行动作时必须同时记录护栏判定。