日志规范实践

问题

这两天在整理现有模块的日志格式规范，以便于自己团队和其它团队更好的分析目前的产品。看了下，遗留的问题还真不少，问题主要集中在以下几点：

日志级别不正确

不是请求粒度的日志打成了NOTICE，用于排查的日志打成了WARNING、甚至打成了FATAL。这对于线上模块监控很不利，一方面很难从众多的WARNING和FATAL日志中找到有价值的信息，另一方面这些日志多了，难免让人产生“狼来了”的麻痹心理。

字段命名不统一

同样一个参数，比如说是请求ID，在不同的请求日志中，有logid、log_id、logId各种不同风格的写法，有的参数是用[]括起来的，有的则没有。这些问题会给日志解析程序带来很大的负担。

字段含义不一致

不同请求日志中的参数A，在一种请求中表示一种含义（比如触发出的商品数），在其它请求中则表示另一种含义（比如一页展现的商品数）。

日志被公共Lib污染

自己的模块依赖了其它公共lib，但是公共lib中的日志级别比较随意，结果污染了自身模块日志。

日志信息不足

许多NOTICE日志只打印出了给上游的返回数据，请求数据却不全。一些WARNING日志只能看出只在代码的哪一行出了问题，请求参数是什么、甚至请求ID，都没有。线上出现了问题，很难根据这条日志找到线索。

规范

因此，我们需要对现在的日志格式进行专项整治，总结出一些合理的、改动尽量小的日志规范。这两天和同事讨论了下，整理出了一些：

统一字段命名

对于不同请求中的同一含义的字段，只能有一个名字。

统一字段风格

字段一律使用xxx_yyy的下划线命名风格。

统一日志层级风格

日志中的信息均通过k=v形式表达，kv之间以,分割，表示第一层级；如果v还有第二层级，则用_分割；第三层级用|分割。ex: k1=v111|v112_v21_v22,k2=v2

统一字段顺序

统一使用请求ID/服务名/请求参数/响应数据/响应时间作为日志字段顺序。（当然，一般公司都有自己的日志工具，会将日志级别、时间、线程ID、函数、行号这些打印在最前面。）

日志必须有请求ID

请求粒度的日志中，必须包含请求ID；工具类的lib中，对于功能较小的函数，无需打日志；功能点较多的函数，需将请求ID通过参数传递进去。

只有请求粒度的日志，才能是NOTICE级别

其它公共lib中的代码，需要打到单独的日志文件中，不和本身模块的日志混淆。

---

日志实在是太重要了，一方面反映了用户的行为，另一方面也反映了模块的指标（召回率、响应时间等），怎么规范它估计都不为过。我们整理的这些规范也智能算是个迷你版本。

其实，我们制定的这些规范（以及其它规范），并没有谁一开始就能全部想到，正如TA一开始也想不到会有再上面的问题一样。每个人都很自信的认为其他人会和TA是一样的代码或者日志风格，如果所有关于打印日志的代码，都是由一个人来写的话，风格想必都是统一的，因为TA知道过去的代码是什么样的，为什么需要改成现在这样，哪些字段是后来因为什么原因而加上的。如果TA另外也负责对日志进行解析和统计的话，那么日志风格就会完全统一了。 :P

规范的制定，从某种意义上讲，也是一种被逼的结果，因为总会有人最终无法忍受由于种种问题而导致的心智负担，然后说道，“受不了了，我们还是搞个规范吧！”

-- EOF --