日志、指标与排错

学习目标

读完本课你能：用「类别 + 关联标识 + 指标」三件套组织可观测数据；沿一条真实失败路径完成从症状到原因的诊断；给日志系统立下「错误必须可枚举」的纪律。

问题场景

用户（就是你自己）报了个障：「AI 回答到一半断了」。你打开代码开始从头读——这是最慢的排错方式。五分钟后你想起来：服务端有 ai_call 表记着每次调用，消息表里有状态字段，前端错误事件带着类别。两分钟定位：cancelled，是你自己上周点过一次停止。排错的速度取决于记录的质量，本课把本站的记录系统串成一条诊断路径。

核心解释

可观测性三件套在本站的对应物（全部真实存在）：

1. 结构化日志 = 带类别的记录。 错误不是一段文案，是一个可枚举的类别。AI 链路七类（not_configured / unreachable / quota / rate_limit / model_error / cancelled / unknown），代码执行五类（ok / timeout / tool_missing / syntax_error / runtime_error）。类别可枚举，才能聚合出「哪类失败最多」；自由文本只能人肉翻。

2. 关联标识 = 把散落的记录串成一条线。 一次对话有 conversation_id，一条消息有 message_id，一次模型调用记账时两个都带上（ai_call 表有这两列）。症状（「那条回答断了」）→ 消息 → 调用记录，一条标识跳到底。

3. 指标 = 面向问题的聚合。 日志回答「发生了什么」，指标回答「总体怎么样」：

-- 失败类别分布：排错的第一张图
SELECT COALESCE(error, '(ok)') AS err, COUNT(*) AS n, ROUND(AVG(latency_ms)) AS avg_ms
FROM ai_call
WHERE created_at > datetime('now', '-7 days')
GROUP BY err ORDER BY n DESC;

一条真实诊断路径（从症状到原因）：

症状：回答中断，界面显示错误提示
 ↓ 前端 error 事件带 category（A10 协议：错误是控制信号不是正文）
 ↓ 按 message_id 查 ai_message：status 是 error / cancelled / 卡在 streaming？
 ↓ 按 message_id 查 ai_call：这条消息的调用记了什么类别？created_at 是几点？
 ↓ 对齐时间点查服务端日志（npm run start 的终端输出）
 ↓ 结论落进三个桶之一：本机问题（unreachable）/ 上游问题（rate_limit、quota）/
   预期内行为（cancelled 是用户自己停的，不算故障）

注意最后一步的纪律：cancelled 是正常分支（A12 的结论），混进故障统计会把「用户主动停止」算成事故，污染下一轮复盘（A40）。

示例拆解

复现并诊断一次真实失败（本机可做，五分钟）：

# 1. 制造故障：把 .env.local 的 AI_BASE_URL 改成不存在的端口，重启
npm run dev

# 2. 发一条消息 → 界面出现错误提示（读类别：unreachable）

# 3. 查记录：这条消息和调用留下了什么？
#    ai_message：该 assistant 消息 status='error'（或因无内容被删除）
#    ai_call：无记录——请求没到模型就失败，账本如实反映「没有调用」

# 4. 修复：改回正确地址重启，重发消息 → done 事件 + ai_call 新记录

关键点：「ai_call 无记录」本身就是有效观测——它证明失败发生在连接层而非模型层，两层的修法完全不同（本机网络配置 vs 上游额度限流）。数据之间能互相印证，观测系统才算立住了：前端类别、消息状态、调用账本三者对得上，诊断才算闭环。

动手任务

1. 按示例复现一次 unreachable，走完四步诊断路径，把每一层看到的内容记下来。
2. 跑上面的聚合 SQL，报告最近 7 天的失败类别分布；如果有 cancelled，确认它被你排除在故障外。
3. 挑一次历史失败，用关联标识把消息、调用、日志串成完整时间线，写成一段排错笔记。

常见错误

• 错误只存文案不存类别：文案改一个字统计就断，类别才是稳定的统计键。
• 排错先读代码：代码告诉你「可能怎么错」，数据告诉你「这次是什么错」——先看数据。
• cancelled 算进故障率：用户主动停止是产品行为，算故障会误触发「优化」。
• 日志与库对不上：改了落库字段忘了同步日志输出，时间线断链，诊断退化成猜测。

检查与复盘

• 能报出 AI 链路七类错误和执行五类，并说出各自的处理方向
• 沿「症状 → 消息 → 调用 → 日志」的路径完成过至少一次真实诊断
• 失败统计里 cancelled 被正确排除

参考资料

• The Twelve-Factor App：日志 —— 「日志是事件流」的原始论述（官方中文版）
• MDN：Console API —— 浏览器侧结构化输出的标准
• OpenTelemetry 官方文档 —— 业界通用的日志/指标/追踪模型，读概念即可