Loading...
墨滴

舒米勒

2021/05/18  阅读:50  主题:橙心

规范总结篇(一):代码日志打印规范分享

大家好,我是杰哥

日志打印往往在一个时间较为紧急的项目中被忽视,而你可能会发现,我们遇到的项目,周期都不怎么松。而且实际上有没有日志,功能照样能实现,还节省了很多时间,正如单元测试的性质一样,它可能会延长项目时间

但是,正所谓,慢就是快,想想,我们的维护时间往往是项目周期的两三倍以上,而维护的对象本质上是什么呢?就是我们写好的代码,若代码中缺少必要的日志打印,或者打印的日志过多过频繁,不仅不好定位问题,还有磁盘存储爆满的问题出现

那么,什么时候需要打印日志呢?

一、什么时候需要打印日志?

简单来说,分为如下几种场景:

  • 代码调试

  • 问题定位

  • 用户行为日志(记录操作日志)

  • 根因分析

对于日志的打印,我们有几个基本的规范要求:

二、日志打印的基本要求规范

  • 对程序运行情况能够进行记录和监控
  • 在必要时可详细了解程序内部的运行状态
  • 对系统性能的影响尽量小(代码中打印方式、打印的日志量与日志存储等方面)

三、在哪些场景下需要打日志呢?

  • 系统初始化流程

  • 编程语言提示异常

  • 业务流程预期不符

  • 系统核心角色,组件关键动作

  • 作为服务提供方(打印入参、出参)

  • 作为服务提供方(打印入参)

  • 定时任务运行相关记录

四、日志级别

常用的分为以下几种:

1、ERROR

影响到程序正常运行、当前请求正常运行的异常情况。如:

1)打开配置文件失败

2)所有第三方对接的异常(包括第三方返回错误码)

3)所有影响功能使用的异常,包括:SQLException 、空指针异常以及业务异常之外的所有异常

2、WARN

告警日志。不应该出现但是不影响程序、当前请求正常运行的异常情况。

但是一旦出现了也需要关注,因此一般该级别的日志达到一定的阈值之后,就得提示给用户或者需要关注的人了。如:

1)有容错机制的时候出现的错误情况

2)找不到配置文件,但是系统能自动创建配置文件

3)即将接近临界值的时候,如 cpu 存储已经超过阈值的 80%,就需要打印 warn 级别的日志

3、INFO

记录输入输出、程序关键节点等必要信息。平时无需关注,但出问题时可根据INFO日志诊断出问题

1)Service方法中对于系统/业务状态的变更

2)调用第三方时的调用参数和调用结果(入参和出参)

3)提供方,需要记录入参

4)定时任务的开始执行与结束执行

4、DEBUG

调试信息,对系统每一步的运行状态进行精确的记录。

5、TRACE

特别详细的服务调用流程各个节点信息。业务代码中,除非涉及到多级服务的调用,否则不要使用(除非有特殊用意,否则请使用DEBUG级别替代)

我呢,根据相关资料以及本人在项目中的经验,梳理了其中比较重要的 15 条日志打印规范

五、日志打印规范

1、增删改操作需要打印参数日志(以便定位一些异常业务问题);

2、条件分支需要打印日志:包括条件值以及重要参数;

3、明确日志打印级别与包含的信息

1)提供方服务,建议以 INFO 级别记录入参,出参可选

2)消费队列消息,务必打印消息内容

3)调用方服务,建议以 INFO 级别记录入参和出参

4)运行环境问题,如网络错误、建议以 WARN 级别记录错误堆栈

5)定时任务,务必打印任务开始时间、结束时间。涉及扫描数据的任务,务必打印扫描范围

4、异常信息应该包括两类信息案发现场信息异常堆栈信息。如果不处理,那么通过关键字throws/throw 往上抛出,由父级方法处理

5、谨慎地记录日志

1)生产环境禁止输出 debug 日志

2)有选择地输出 info 日志

3)如果使用 warn 来记录刚上线时的业务行为信息,一定要注意日志输出量的问题,避免把服务器磁盘撑爆,并记得及时删除这些观察日志

6、可以使用 warn 日志级别来记录用户输入参数错误的情况,避免用户投诉时,无所适从

注意日志输出的级别,error 级别只记录系统逻辑出错、异常等重要的错误信息。如非必要,请不要在此场景打出 error 级别。(上述已经说明了 errorwarn 级别日志的区别)

7、对 trace/debug/info级别的日志输出,必须使用条件输出形式或者使用占位符的方式

说明:

logger.debug("Processing trade with id: " + id + " symbol: " + symbol);

对于上述代码,如果日志级别是 warn,日志不会打印,但是会执行字符串拼接操作,如果 symbol 是对象, 会执行 toString() 方法,浪费了系统资源,执行了上述操作,最终日志却没有打印

正例:(条件)

if (logger.isDebugEnabled()) {
    logger.debug("Processing trade with id: " + id + " symbol: " + symbol);
}

正例:(占位符)

logger.debug("Processing trade with id: {} symbol : {} ", id, symbol);

8、不允许记录日志后又抛出异常,因为这样会多次记录日志,只允许记录一次日志

反例:

if (virtualIpPortCrash) {
            log.error("接入虚拟IP端口冲突");
            throw new BusinessException("接入虚拟IP端口冲突");
        }
        

9、不允许出现System print(包括System.out.println和System.error.println)语句作为日志的打印

10、不允许出现 e.printStackTrace

11、日志性能的考虑。如果代码为核心代码,执行频率非常高,则输出日志建议增加判断,尤其是低级别的输出

12、【强制】应用中不可直接使用日志系统(Log4j、Logback)中的 API,而应依赖使用日志框架 SLF4J 中的 API,使用门面模式的日志框架,有利于维护和各个类的日志处理方式统一

import lombok.extern.slf4j.Slf4j;
//1-在类上添加注解
@Slf4j 

//2-直接使用log.info()进行日志的打印(还支持error、warn、trace以及debug等级别)
log.info("service update success:{}................",serviceEntity.getName());

13、【强制】日志文件推荐至少保存 15 天,因为有些异常具备以“周”为频次发生的特点

14、【强制】应用中的扩展日志(如打点、临时监控、访问日志等)命名方式: appName_logType_logName.log

logType:日志类型,推荐分类有 stats/desc/monitor/visit 等

logName:日志描述。这种命名的好处:通过文件名就可知 道日志文件属于什么应用,什么类型,什么目的,也有利于归类查找。 正例:mppserver 应用中单独监控时区转换异常,如: mppserver_monitor_timeZoneConvert.log

15、【强制】避免重复打印日志,浪费磁盘空间。务必在 log4j.xml 中设置 additivity=false

六、总结

好了,由于日志打印的确很重要,因此杰哥 最近找寻了很多相关资料,并根据自己的项目经验,特此列出比较重要的 15 条日志打印规范,分享给诸位~

需要注意一点, error 级别和 warn 级别的日志的区别。error 日志表示的是程序因出错,已经无法正常执行业务操作了。而 warn 则表示,并不会影响程序的正常运行,但是也需要适当关注的一些日志信息。

慢就是快代码中合理地打印日志,将会起到事半功倍的效果。否则呢,不仅会影响维护质量,还可能会引起一些意想不到的问题

所以,大家在平常开发中,为了项目的长远发展,一定要注意好好打日志哦~

舒米勒

2021/05/18  阅读:50  主题:橙心

作者介绍

舒米勒

深信服-架构师