日志记录规范总结

然而，日志记录的好坏直接关系到系统出现问题时定位的速度。同时，我们可以通过对日志的观察和分析，提前发现系统可能的风险，避免线上事故的发生。对于服务端开发人员来说，线上日志的监控尤其重要，能够帮助我们第一时间发现线上问题并及时解决。

碰巧这周也翻译了一篇《日志记录最佳实践》[1]，作者在文章的最后分享了技术分享的 PPT，大家可以按需食用。

下面对日志规范做一下总结。

日志记录总则

1. 日志中不要记录无用信息，防止无用日志淹没重要信息
2. 要明确不同日志的用途，对日志内容进行分类
3. 日志信息要准确全面，努力做到仅凭日志就可以定位问题
4. 日志格式要统一规范
5. 日志要不断优化、完善

日志级别

遵循 RFC 5424[2]，将日志级别分为以下 8 种等级：

各级日志等级信息记录内容如下：

Emergency

• 导致系统不可用的事故，属于最严重的日志级别，因此该日志级别必须慎用
• 通常情况下，一个进程的声明周期中应该只记录一次 Emergency 级别的日志

Alert

• 必须马上处理的问题，紧急程度低于 Emergency
• Alert 错误发生时，已经影响了用户的正常访问
• 与 Emergency 的区别是，Alert 状态下系统依旧是可用的。例如：DB / Cache 无法连接。

Critical

紧急情况，程序组件不可用，需要立刻进行修复。例如：用户注册逻辑模块不能发送邮件。

Error

• 运行时出现的错误，不必要立即进行修复
• 错误不影响整个逻辑的运行，但需要记录并做检测。

Warning

• 可能影响系统功能，需要提醒的重要事件
• 该日志标识系统可能出现问题，也可能没有（比如网络波动）。对于那些目前还不是错误，然而不及时处理也会变为错误的情况，也可以记为 Warning 日志。例如一个存储系统的磁盘使用量超过阀值，或者系统中某个用户的存储配额快用完等等
• 对于 Warining 级别的日志，虽然不需要马上处理，但也需要及时查看并处理

Notice

• 不影响正常功能，但需要注意的消息
• 执行过程中较 Infomational 级别更为重要的信息。

Infomational

• 用于记录系统正常运行情况下的一般信息，强调应用程序的运行过程。例如：某个子模块的初始化、某个请求的成功执行等
• 通过查看 Infomational 级别的日志，可以很快对系统中出现的 0~5 级别的错误进行定位

Debug

帮助开发、测试、运维人员对系统进行诊断的信息。

日志分类

日志从功能来说，可分为诊断日志、统计日志、审计日志。

诊断日志

• 请求入口和出口
• 外部服务调用和返回
• 资源消耗操作: 打开文件等
• 容错行为：譬如云硬盘的副本修复操作
• 程序异常：譬如数据库无法连接
• 后台操作：清理程序
• 启动、关闭、配置加载
• 抛出异常时，不记录日志

统计日志

• 用户访问统计
• 计费日志（如记录用户使用的网络资源或磁盘占用，格式较为严格，便于统计）

审计日志

• 管理操作

日志格式规范

• 统一字段命名：对于不同请求中的同一含义的字段，只能有一个名字
• 统一字段风格：例如字段一律使用 xxx_yyy 的下划线命名风格
• 统一日志层级风格
• 统一字段顺序：例如统一使用 请求ID/服务名/请求参数/响应数据/响应时间 作为日志字段顺序
• 每个请求需要加入请求 ID request_id

日志中记录什么

推荐记录的日志内容

• 在系统启动或初始化时记录重要的系统初始化参数
• 记录系统运行过程中的所有的错误
• 记录系统运行过程中的所有的警告
• 在持久化数据修改时记录修改前和修改后的值
• 记录系统各主要模块之间的请求和响应
• 重要的状态变化
• 系统中一些长期执行的任务的执行进度

不推荐记录的日志内容

• 函数入口信息：除非该函数入口表示了一个重要事件的开始，或者将该信息记入 DEBUG 级别日志
• 文件内容或者一大段消息的内容：如果实在需要记录，则可以截取其中一些重要的信息来记入日志
• “良性”错误：有时候虽然出现了错误，然而错误处理的流程可以正确解决这种情况，例如插入数据库时有重复的记录，尽管是个错误，然而错误处理流程可以对这种情况进行处理

总结

• 没有绝对正确/错误的日志记录方式，适合个人/团队的才是最好的
• 好的习惯尽早养成，受益终身

If a dog is a man’s best friend, logs are software engineer’s best friend.

References

参考资料

• stackoverflow - When to use the different log levels: https://stackoverflow.com/questions/2031163/when-to-use-the-different-log-levels
• 最佳日志实践（v2.0）: https://zhuanlan.zhihu.com/p/27363484
• Logger Interface: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
• 日志规范实践: https://blog.goquxiao.com/posts/2014/03/18/ri-zhi-gui-fan-shi-jian/
• SeasLog 之企业级日志行为规范发布: https://juejin.im/post/5abba33cf265da239b417fb4

文内引用

• [1] 日志记录最佳实践: http://jalan.space/weekly-translation/other/follow-these-logging-best-practices-to-get-the-most-out-of-application-level-logging-slides.html
• [2] RFC 5424: https://tools.ietf.org/html/rfc5424