用途：为 LLM 智能体建立可观测性，让失败可诊断、轨迹可回放、评估可基于生产数据运行。核心观点是：无法回放失败轨迹，就无法修复智能体；仅记录“模型返回了 X”不算可观测性。
主要能力与要求：一次用户请求生成一条 trace，内部为嵌套 span，覆盖图、循环、工具调用、重试、子智能体等结构。每个 span 应包含：名称（如 agent.plan、agent.tool_call.search_docs、agent.model_call、agent.reflect）；逐字输入输出（写入时脱敏 PII）；属性（模型名、模型版本、提示版本、token 数含 prompt/completion/cached、延迟、成本）；状态（OK、error、fallback-taken）；trace 与 span ID 以关联子智能体调用。
五条规则：每个用户请求一条 trace，子智能体与重试作为内部 span；输入输出逐字记录，截断会隐藏 bug；span 命名标准化为 <component>.<action>；每次模型调用记录 token 与成本；错误需分型，如 error.kind = tool_timeout 而非“tool failed”。
OpenTelemetry GenAI 约定：gen_ai.system（提供商）、gen_ai.request.model（请求模型）、gen_ai.response.model（实际使用模型）、gen_ai.usage.input_tokens/output_tokens/cached_tokens、gen_ai.operation.name（chat、embeddings、tool_call）。
使用方式：判断是否已过原型阶段，若是则立即埋点；若框架输出兼容 OpenTelemetry 的 span 则直接使用；需要回放则记录输入及所有随机种子、温度、模型版本与工具响应；需要生产评估则采样真实 trace 并离线打分；需要成本归因则在每个 span 记录 token 数并汇总到 trace。
适用场景：智能体从笔记本迁移到服务、报告无复现器的间歇性失败、采用 OpenTelemetry/LangSmith/Langfuse/Arize 等、希望用真实生产流量而非固定集做评估。
限制与反模式：仅用 print 调试、不捕获输入、每次运行只一个 span、对错误采样、trace 数据无评估友好 schema、无基数纪律（如用每用户 ID 作 span 名）。硬性要求：每次生产调用都要有 trace，错误零覆盖不可接受，成本可采样但错误不可。
参考资料：references/span-shape.md、references/otel-genai.md、references/eval-from-traces.md。相关技能：agent-evaluation-harness、agent-cost-modeling、latency-budgeting、guardrails-and-safety、agent-architecture-patterns。