良好的日志记录规范

昨天看到一篇文章,关于日志的也推荐给大家看看; 关于日志测试的Why和How 瞬间也在网上找了一些文章,以及之前系统中日志一起比较了一下,瞬间觉得弱爆了引用一段我们项目中的日志看看 从这个日志中几乎看不出任何东东。 综上,以及看到上面的文章对我的启发蛮大。开始我的计划之旅

  • 形成规范
  • 应用项目(首先Xdns项目)

今天在这简单介绍下规范,应用后续在讲,优化完成后给大家介绍介绍。

规范

日志记录是在软件开发过程中常常需要考虑的关键因素。当产品运行出错时,日志文件通常是我们进行错误分析的首要选择。而且,在很多情况下,它们是我们手上唯一可以用来查明发生状况和问题根本原因的信息。可见,正确记录需要的信息是极其重要的。

规则1、日志是面向读者的

日志消息不仅要对书写(日志)代码的人有意义,也应该对日志文件的读者有意义。 这似乎是一条很明显但却经常违背的规则。

ERROR: Save failure - SQLException …..

举个例子吧,我们来看看下面这条日志信息:

ERROR: Save failure - SQLException …..

保存什么呢?这条消息在开发者看来是能说明一些问题的,但是对于正在苦苦查看产品问题的可怜家伙来说,却毫无用处。

ERROR: Save failure- Entity=Person, Data=[id=123 surname=”Mario”] - SQLException….

更合适的信息是这样的:

ERROR: Save failure- Entity=Person, Data=[id=123 surname=”Mario”] - SQLException….

这就解释了你想要存储的东西(这里是一个 Person,是一个 JPA 实体)以及这个 Person 实例相关的内容。 请注意相关这个单词,并不是指泛泛的全体:我们不应该让无价值的信息使日志文件变得乱糟糟,比如说完整打印所有的实体字段。 通常,实体名字和其逻辑关键字足以识别在表格中的一条记录了。

规则2、匹配日志等级和执行环境

在 Java 系统中提供的所有日志管理工具和引擎都有日志等级(ERROR、INFO……)的概念,这将有可能过滤掉等级过低的消息。 例如,Java util logging使用如下的等级:SEVERE、WARN、INFO、FINE、FINER、FINEST(+ CONFIG 和 OFF)。相反,两个最受欢迎的日志管理工具, Apache Commons Logging 和 SLFJ 更倾向于如下的等级:FATAL、ERROR、WARN、INFO、DEBUG、TRACE。 日志过滤等级则需要取决于代码的开发阶段:成品与仍处在测试、集成环境下的代码日志等级就不能相同。 更具体的来说,日志等级也应该参考代码的归属情况。 一般而言,我们自己的应用程序代码应该比使用的任何第三方开发库拥有更详细的日志记录。 比如说,Apache 的通用调试消息出现在我们的日志文件中,就没有多大意义。 我通常像这样配置日志记录: 成品阶段: 我的代码是 INFO 等级,第三方库是 WARN。 测试、集成阶段:我的代码是 DEBUG 等级,第三方库是 WARN(或者如果需要的话是 INFO)。 开发阶段:任何有意义的信息。 注意:个人而言,我不建议使用 TRACE/FINEST 等级(我并不是唯一持这种观点的人,可以参考 这里 的例子)。 我并没有发现 DEBUG 和 TRACE 有多大的区别,而年轻团队的成员常常苦恼于到底是使用 DEBUG 还是 TRACE 。 根据 KISS 原则,我建议只使用 ERROR、WARN、INFO 和 DEBUG 等级。

规则3、提交前去除编码帮助日志

编码时,我们常常会使用 logger 或是 System.out 在代码中添加日志消息,来更好地掌握应用程序在执行、调试期间发生的状况。

void aMethod(String aParam) {
LOGGER.debug(“Enter in aMethod”); if (“no”.equals(aParam)) {
LOGGER.debug(“User says no”);
….

比如这样的代码:

void aMethod(String aParam) {
LOGGER.debug(“Enter in aMethod”); if (“no”.equals(aParam)) {
LOGGER.debug(“User says no”);
….

这些消息显示被调用的方法并且备份内部变量及方法参数值,主要是为了追踪应用程序的行为。这在非测试驱动开发中相当受欢迎。 但糟糕的是,一旦代码发布(测试之后成为成品)这些消息通常就无用武之地了。 所以,这条规则简单来说就是:一旦你已经完成开发工作,在将代码提交到使用中的 SCM 系统(git、svn……)之前,要去除所有临时的和不必要的日志消息。 这条规则并不是要求去除所有的 DEBUG 消息,只是针对那些在应用程序完成和发布后就没有意义的消息,或者是说当我们有理由相信应用程序能正确运行时就失去意义的那些消息。

规则4、log DEBUG消息之前检查日志等级

根据第2条规则,在产品日志中,我们只会显示 ERROR、WARN、INFO 等级的消息,但是在代码中我们也可以使用一些不会影响产品运行的 DEBUG 消息。

if ( LOGGER.isDebugEnabled((){
LOGGER.debug (…….)
}

每次你想要 log 一个 DEBUG 消息时(在使用了规则3后的留下的所有消息),需要在前面添加一个检查来明确是否启用了 DEBUG 日志:

if ( LOGGER.isDebugEnabled((){
LOGGER.debug (…….)
}

这种做法可以阻止代码去创建日志消息和调用 logger,提高产品运行程序的效率。 规则5、了解你的 logger 我们使用 logger 方法的方式可能会带来巨大的开销: 创建消息字符串 组织包含在消息字符串中的数据 我们应该查阅所选择的日志管理工具、引擎的 javadoc 文档,了解使用它们 logger 的最有效的方法。

LOGGER.info(“Person name is “ + person.getName());

例如,我们可以创建一条这样的消息:

LOGGER.info(“Person name is “ + person.getName());

这就创建了不必要的字符串实例。

LOGGER.info(“Person name is {}“, person.getName());

使用SLF4J,正确的用法应该是:

LOGGER.info(“Person name is {}“, person.getName());

这里的格式化字符串是常量,不可变消息只有在允许 logging 的情况下才会被创建。

规则5、日志必须有请求ID

请求粒度的日志中,必须包含请求ID;工具类的lib中,对于功能较小的函数,无需打日志;功能点较多的函数,需将请求ID通过参数传递进去。 qrcode_for_gh_1233eeff1166_430 文章同步发布公众号:duzhi

除特别注明外,本站所有文章均为duzhi原创,转载请注明出处来自https://www.duzhi.me/article/29.html

联系我们

******

在线咨询:点击这里给我发消息

邮件:ashang.peng#aliyun.com

QR code