业务日志打印规范

业务日志打印规范

参考文档

1. Java开发手册 https://github.com/alibaba/p3c

内容

1. 【强制】应用中不可直接使用日志系统（Log4j、Logback）中的 API，而应依赖使用日志框架
   （SLF4J、JCL--Jakarta Commons Logging）中的 API，使用门面模式的日志框架，有利于维护和
   各个类的日志处理方式统一。
   说明：日志框架（SLF4J、JCL--Jakarta Commons Logging）的使用方式（推荐使用 SLF4J）
   使用 SLF4J：

   import org.slf4j.LoggerFactory;
   private static final Logger logger = LoggerFactory.getLogger(Test.class);
   使用 JCL：
   import org.apache.commons.logging.Log;
   import org.apache.commons.logging.LogFactory;
   private static final Log log = LogFactory.getLog(Test.class);
   

2. 【强制】所有日志文件至少保存 15 天，因为有些异常具备以“周”为频次发生的特点。对于
   当天日志，以“应用名.log”来保存，保存在/home/admin/应用名/logs/目录下，过往日志
   格式为: {logname}.log.{保存日期}，日期格式：yyyy-MM-dd
   正例：以 aap 应用为例，日志保存在/home/admin/aapserver/logs/aap.log，历史日志名称为
   aap.log.2016-08-01

3. 【强制】根据国家法律，网络运行状态、网络安全事件、个人敏感信息操作等相关记录，留存
   的日志不少于六个月，并且进行网络多机备份。

4. 【强制】应用中的扩展日志（如打点、临时监控、访问日志等）命名方式：
   appName_logType_logName.log。logType:日志类型，如 stats/monitor/access 等；logName:日志描
   述。这种命名的好处：通过文件名就可知道日志文件属于什么应用，什么类型，什么目的，也有利于归类查
   找。
   Java 开发手册
   说明：推荐对日志进行分类，如将错误日志和业务日志分开存放，便于开发人员查看，也便于通过日志对系
   统进行及时监控。
   正例：mppserver 应用中单独监控时区转换异常，如：mppserver_monitor_timeZoneConvert.log

5. 【强制】在日志输出时，字符串变量之间的拼接使用占位符的方式。
   说明：因为 String 字符串的拼接会使用 StringBuilder 的 append()方式，有一定的性能损耗。使用占位符仅
   是替换动作，可以有效提升性能。
   正例：logger.debug("Processing trade with id: {} and symbol: {}", id, symbol);

6. 【强制】对于 trace/debug/info 级别的日志输出，必须进行日志级别的开关判断。
   说明：虽然在 debug(参数)的方法体内第一行代码 isDisabled(Level.DEBUG_INT)为真时（Slf4j 的常见实现
   Log4j 和 Logback），就直接 return，但是参数可能会进行字符串拼接运算。此外，如果 debug(getName())
   这种参数内有 getName()方法调用，无谓浪费方法调用的开销。
   正例：
   // 如果判断为真，那么可以输出 trace 和 debug 级别的日志
   if (logger.isDebugEnabled()) {
   logger.debug("Current ID is: {} and name is: {}", id, getName());
   }

7. 【强制】避免重复打印日志，浪费磁盘空间，务必在日志配置文件中设置 additivity=false。
   正例：<logger name="com.taobao.dubbo.config" additivity="false">

8. 【强制】生产环境禁止直接使用 System.out 或 System.err 输出日志或使用
   e.printStackTrace()打印异常堆栈。
   说明：标准日志输出与标准错误输出文件每次 Jboss 重启时才滚动，如果大量输出送往这两个文件，容易
   造成文件大小超过操作系统大小限制。

9. 【强制】异常信息应该包括两类信息：案发现场信息和异常堆栈信息。如果不处理，那么通过
   关键字 throws 往上抛出。
   正例：
   logger.error("inputParams:{} and errorMessage:{}", 各类参数或者对象 toString(), e.getMessage(), e);

10. 【强制】日志打印时禁止直接用 JSON 工具将对象转换成 String。
    说明：如果对象里某些 get 方法被覆写，存在抛出异常的情况，则可能会因为打印日志而影响正常业务流
    程的执行。
    正例：打印日志时仅打印出业务相关属性值或者调用其对象的 toString()方法。

11. 【推荐】谨慎地记录日志。生产环境禁止输出 debug 日志；有选择地输出 info 日志；如果使用
    warn 来记录刚上线时的业务行为信息，一定要注意日志输出量的问题，避免把服务器磁盘撑
    爆，并记得及时删除这些观察日志。
    说明：大量地输出无效日志，不利于系统性能提升，也不利于快速定位错误点。记录日志时请思考：这些
    日志真的有人看吗？看到这条日志你能做什么？能不能给问题排查带来好处？

12. 【推荐】可以使用 warn 日志级别来记录用户输入参数错误的情况，避免用户投诉时，无所适
    从。如非必要，请不要在此场景打出 error 级别，避免频繁报警。
    说明：注意日志输出的级别，error 级别只记录系统逻辑出错、异常或者重要的错误信息。

13. 【推荐】尽量用英文来描述日志错误信息，如果日志中的错误信息用英文描述不清楚的话使用
    中文描述即可，否则容易产生歧义。
    说明：国际化团队或海外部署的服务器由于字符集问题，使用全英文来注释和描述日志错误信息。