结构化日志与可观测性：个人项目也值得做对

日志的价值不在「打得多」，而在「出事时能把一条请求从头追到尾」。个人博客体量小，但这恰好是养成好习惯的窗口：等流量上来再补，往往会在压力下补出一堆噪音字段和不一致约定。可观测性听起来像大厂词，拆开后不过是日志、指标、追踪三类信号；个人项目先把日志做对，收益已经很大。

为什么要结构化

纯文本日志对人读友好，对机器不友好。排查时你需要按 request_id、路径、状态码过滤，文本拼接很难稳定解析。JSON 一行一条事件，字段固定，后期接 Loki、Elastic 或哪怕本地 jq 都更轻松。

最小字段建议：

• time：ISO8601 或 Unix ms
• level：info/warn/error
• msg：短描述
• request_id：单次请求关联
• path / method / status / latency_ms
• error：失败时的错误字符串（注意脱敏）

业务日志再补 article_id、user_id 等，但不要把 Token、密码、Cookie 整段落盘。字段名一旦定下就少改；改名等于让历史查询全部失效。

格式统一比库选择更重要。Go 里用标准库 slog 或 zap 都可以，关键是全项目一致：别有的包打印纯文本，有的包打印 JSON，最后谁也搜不动。

请求相关性

在中间件入口生成或透传 X-Request-Id，写入上下文，后续日志、错误返回都可以带上。用户反馈「发表失败」时，只要给你一个 request id，你就能在日志里精确落地，而不是翻时间段猜。

前后端分离时，最好让网关或后端生成该 ID，并在响应头返回。前端控制台网络面板也能直接抄给你。如果还有异步任务，把同一 id 或由其衍生的 correlation id 传下去，异步失败才不会变成「孤立的 error 一行」。

指标与日志分工

日志回答「某次发生了什么」；指标回答「整体是否变差」。个人项目至少可以有：

• 接口请求量、错误率、延迟（即便先用访问日志统计）
• 容器健康检查状态
• 磁盘与数据库连接是否耗尽

不一定上完整 Prometheus。能分清「偶发 500」和「错误率从 0.1% 飙到 8%」就已经能做决策。发布前后对比这些数字，比只看「我点了点好像没事」可靠。

追踪（tracing）对微服务更有价值；单体博客可以用「日志 + 少量指标」先撑住。等你真的有多服务调用链，再引入 tracing，避免过早复杂化。

常见反模式

• 在循环里打 debug，把磁盘打满
• 同一错误层层包装却只打印最外层
• info 级别刷业务流水，真正的 error 被淹没
• 没有留存策略，一周后才发现日志被轮转光了
• 在日志里打印整篇 Markdown 或上传文件二进制

约定级别：info 记录关键业务节点；warn 记录可恢复异常；error 记录需要介入的失败。调试完成就关掉噪声。错误要保留足够上下文（输入 ID、关键参数摘要），但不要「全量 request dump」。

与博客栈结合

Gin 中间件记录访问日志；GORM 可在慢查询阈值以上打印 SQL；Nginx access log 保留 upstream 状态。三层日志时间对齐，才能判断问题在浏览器、网关还是应用。时钟不同步时，先确认机器 NTP，再比时间线。

上 Umami 一类统计解决的是产品访问分析，不能替代错误日志。两者服务的问题不同：一个看内容效果，一个看系统健康。访问量上涨却错误率也涨，才是你该立刻查日志的信号。

落地的最小方案

1. 访问日志结构化，含 request_id
2. 业务错误带同一 request_id
3. 慢 SQL 单独采样
4. 日志轮转与保留天数明确
5. 发布后花三分钟扫一眼 error 是否新增

这五步不需要新服务器，却能把「个人玩具站」抬到「可以认真维护」的水平。

小结

可观测性不是大厂专属仪式。结构化字段、请求 ID、合理级别、脱敏与留存，这四件事做完，个人项目的排障体验会立刻接近「像样的线上系统」。等你日后加更多服务，这套约定可以直接平移，而不必推倒重来。先让失败变得可定位，再谈优化性能。