给日志写一份可读的说明书：让排查从三分钟缩短到三秒钟

凌晨两点，告警把人叫醒，真正耗时的往往不是修问题，而是找问题。日志翻了几十页，才发现关键信息藏在一句没有上下文的报错里。这篇文章想说一个朴素的观点：日志不是给机器看的流水账，而是给未来的自己和同事写的一份说明书。写的时候多想一步，排查时就能少走很多弯路。

第一，给每条日志一个身份。一次请求、一次任务、一次调用，应该有一个可以贯穿始终的标识。把这个标识打在入口、关键分支和出口上，出问题时按标识一搜，整条链路就串起来了。没有标识的日志就像没有页码的书，内容再全也难查。

第二，只记能推动下一步行动的信息。一条好的日志至少回答三个问题：发生了什么、在哪里发生、接下来该查什么。时间、模块、关键参数和错误码缺一不可，而把整个对象原样倾倒出来，往往只会淹没重点。敏感信息更要排除在外，密码、令牌和个人身份信息不应该出现在任何日志里。

第三，分清级别，别让所有信息都喊救命。如果一切都是错误，真正的错误就不再醒目。调试信息留给开发环境，信息级别记录正常的关键节点，警告留给可以稍后处理但需要关注的异常，错误只留给确实影响功能、需要人工介入的情况。级别定下来就要全团队遵守，否则告警很快就会被忽略。

第四，用稳定的结构代替随意的措辞。同一个事件在不同地方应该用同一种写法，字段顺序和命名保持一致，这样无论是人工搜索还是工具解析都更可靠。把可变内容放在参数位置，而不是拼进句子里，搜索时才能精准命中。

第五，日志要和指标、链路互相印证。单看日志容易以偏概全，结合请求量、耗时和成功率，才能判断这是一次偶发抖动，还是一次系统性故障。排查时先看趋势，再钻细节，顺序反过来常常会浪费时间。

最后，定期回看自己的日志。每个月抽半小时，把最近排查过的故障复盘一遍：哪些日志帮上了忙，哪些日志说了等于没说，哪些地方本该有日志却没有。把结论写进团队的日志规范，下一次值班的人就会轻松一点。好的日志写起来并不难，难的是在写代码的当下，愿意为读日志的人多想一步。