04-可观测性与Trace
核对日期：2026-05-13。
不稳定项：OpenTelemetry 语义约定、各 provider usage 字段、模型 trace 工具、评测平台和日志治理能力持续变化；接入前必须核对当前版本。
1. 学习目标
本专题关注 AI 系统如何被观察、解释和复盘。普通服务只看错误率和延迟不够，LLM 系统还要看 token、成本、模型、Prompt、RAG、工具、质量和安全。
学完后你应该能做到：
- 设计一次 AI 请求的 trace span 结构。
- 定义模型调用、RAG、工具调用和输出解析的关键日志字段。
- 区分 metrics、logs、traces 和 eval 结果的职责。
- 建立质量、成本、延迟和安全的监控面板。
- 设计脱敏、采样和访问控制，避免观测系统变成泄漏源。
2. 为什么普通观测不够
传统服务常看：
- QPS。
- 错误率。
- 延迟。
- CPU / 内存。
AI 系统还必须看：
- 使用了哪个模型和 provider。
- Prompt 版本是什么。
- 输入输出 token 多少。
- 是否命中缓存。
- 是否 fallback。
- RAG 检索到了什么。
- 工具调用了几步。
- 输出是否通过 schema。
- 引用是否有效。
- 安全策略是否拦截。
- 用户反馈如何。
没有这些字段，线上问题会变成“模型今天好像不太行”。
3. Trace 结构
推荐 span：
request
auth.check
input.guard
prompt.build
rag.retrieve
rag.rerank
model.route
model.call
output.parse
citation.check
tool.call
feedback.record
不是每个请求都有所有 span。关键是每个阶段能记录输入摘要、输出摘要、耗时、错误和版本。
4. 模型调用字段
| 字段 | 说明 |
|---|---|
trace_id | 全链路 ID |
span_id | 当前 span ID |
tenant_id | 租户 |
feature | 功能 |
task_type | 任务 |
model | 模型 |
provider | 供应商 |
route_reason | 路由原因 |
prompt_version | Prompt 版本 |
input_tokens | 输入 token |
output_tokens | 输出 token |
cached_tokens | 缓存 token |
estimated_cost | 估算成本 |
latency_ms | 总延迟 |
first_token_ms | 首 token 延迟 |
retry_count | 重试次数 |
fallback_used | 是否 fallback |
finish_reason | 结束原因 |
error_type | 错误类型 |
provider_request_id | 上游请求 ID |
这些字段让你能把质量、成本、延迟和故障串起来。
5. RAG 观测字段
RAG 失败经常不是模型失败，而是检索失败。
| 字段 | 说明 |
|---|---|
query_rewrite_version | 查询改写版本 |
rag_index_version | 索引版本 |
retrieval_strategy | keyword / vector / hybrid |
top_k | 召回数量 |
rerank_model | 重排模型 |
retrieved_doc_ids | 文档 ID 摘要 |
permission_filtered_count | 权限过滤数量 |
empty_retrieval | 是否空召回 |
citation_check_passed | 引用是否通过 |
注意：日志中不要保存完整敏感文档正文。通常记录 doc id、chunk id、hash、标题和权限范围即可。
6. Agent 观测字段
Agent 需要轨迹观测：
| 字段 | 说明 |
|---|---|
agent_run_id | Agent 执行 ID |
step_count | 步数 |
max_steps | 最大步数 |
tool_calls | 工具调用摘要 |
tool_error_count | 工具错误数 |
human_interrupt | 是否人工介入 |
stop_reason | 完成、超步数、错误、人工停止 |
state_snapshot_id | 状态快照 |
Agent 没有轨迹就无法解释为什么它做了某个动作。
7. Metrics 面板
至少包含：
| 类别 | 指标 |
|---|---|
| 可用性 | success rate、error rate、provider status |
| 延迟 | p50/p95/p99、first token latency |
| 成本 | daily cost、cost by feature、cost by tenant |
| token | input/output/cached tokens |
| 路由 | model distribution、fallback rate、retry rate |
| RAG | empty retrieval、citation pass、rerank latency |
| Agent | step count、tool error、HITL rate |
| 质量 | eval pass rate、user feedback、adoption |
| 安全 | injection blocked、permission denied、DLP hit |
监控面板要能回答：现在系统是否可用、是否变贵、是否变慢、是否变差、是否变危险。
8. 日志脱敏和访问控制
AI 日志容易包含敏感信息。
不要记录：
- 密钥、token、密码。
- 原始个人身份信息。
- 未授权文档正文。
- 完整系统提示词。
- 高敏工具返回结果。
推荐：
- user id hash。
- 输入摘要或 hash。
- 文档 id 和 chunk id。
- 工具参数摘要。
- 错误类型而非完整堆栈。
- 对调试采样设置权限和过期时间。
观测系统本身也需要权限、审计和保留周期。
9. Eval 与线上观测
线上 metrics 不能替代 eval，eval 也不能替代线上观测。
| 机制 | 作用 |
|---|---|
| 离线 eval | 发布前发现回归 |
| 线上抽样 eval | 发现真实分布变化 |
| 用户反馈 | 发现体验和业务问题 |
| Trace | 定位单次失败根因 |
| Metrics | 发现系统级趋势 |
完整闭环：
线上失败 -> trace 定位 -> 加入失败样例库 -> 离线 eval 回归 -> 灰度发布
10. 工程案例
10.1 引用错误排查
现象：用户反馈回答引用不支持结论。
排查字段：
rag_index_version。retrieved_doc_ids。rerank_model。citation_check_passed。prompt_version。
可能根因：
- 检索召回错文档。
- rerank 排序错误。
- Prompt 没要求逐条引用。
- citation checker 缺失。
10.2 成本异常排查
现象：某功能成本突然上涨。
排查字段：
- feature cost。
- prompt_version。
- input_tokens。
- top_k。
- retry_count。
- fallback_used。
可能根因：
- Prompt 变长。
- RAG top_k 增大。
- provider 频繁失败导致重试。
- fallback 到更贵模型。
11. 常见反模式
| 反模式 | 表现 | 后果 | 修正 |
|---|---|---|---|
| 只看接口错误率 | 模型胡说也算成功 | 质量问题不可见 | 加 eval 和引用指标 |
| 日志全量明文 | 调试方便 | 隐私和合规风险 | 脱敏、摘要、采样 |
| 不记录版本 | 无法复现问题 | 回滚困难 | prompt/model/index 版本化 |
| trace 无业务维度 | 只知道慢 | 不知道谁慢 | feature/tenant/task 入 trace |
| Agent 无轨迹 | 只看最终答案 | 无法解释动作 | 记录 step 和 tool |
12. 练习
为一个客服草稿生成系统设计观测方案：
- trace span。
- 模型调用字段。
- RAG 字段。
- 成本指标。
- 质量指标。
- 安全指标。
- 日志脱敏策略。
13. 验收题
- AI 系统为什么不能只看错误率和延迟？
- 一次模型调用应该记录哪些字段？
- RAG 系统需要哪些额外观测字段？
- Agent 为什么必须记录轨迹？
- 日志脱敏和问题排查之间如何平衡？
- 离线 eval、线上 eval、用户反馈和 trace 各自解决什么问题？