Java 日志规范

前言

一个在生产环境里运行的程序如果没有日志是很让维护者提心吊胆的，有太多杂乱又无意义的日志也是令人伤神。程序出现问题时候，从日志里如果发现不了问题可能的原因是很令人受挫的。本文想讨论的是如何在Java程序里写好日志。

一般来说日志分为两种：业务日志和异常日志，使用日志我们希望能达到以下目标：

1. 对程序运行情况的记录和监控；
2. 在必要时可详细了解程序内部的运行状态；
3. 对系统性能的影响尽量小

Java日志框架

Java的日志框架太多了。。。

1. Log4j 或 Log4j 2 - Apache的开源项目，通过使用Log4j，我们可以控制日志信息输送的目的地是控制台、文件、GUI组件、甚至是套接口服务器、NT的事件记录器、UNIX Syslog守护进程等；用户也可以控制每一条日志的输出格式；通过定义每一条日志信息的级别，用户能够更加细致地控制日志的生成过程。这些可以通过一个配置文件（XML或Properties文件）来灵活地进行配置，而不需要修改程序代码。Log4j 2则是前任的一个升级，参考了Logback的许多特性；
2. Logback - Logback是由log4j创始人设计的又一个开源日记组件。logback当前分成三个模块：logback-core,logback- classic和logback-access。logback-core是其它两个模块的基础模块。logback-classic是log4j的一个改良版本。此外logback-classic完整实现SLF4J API使你可以很方便地更换成其它日记系统如log4j或JDK14 Logging；
3. java.util.logging - JDK内置的日志接口和实现，功能比较简；
4. Slf4j - SLF4J是为各种Logging API提供一个简单统一的接口），从而使用户能够在部署的时候配置自己希望的Logging API实现；
5. Apache Commons Logging - Apache Commons Logging （JCL）希望解决的问题和Slf4j类似。

 Java日志最佳实践

日志分级

Java的日志框架一般会提供以下日志级别，缺省打开info级别，也就是debug，trace级别的日志在生产环境不会输出，在开发和测试环境可以通过不同的日志配置文件打开debug级别。

1. fatal - 严重的，造成服务中断的错误；
2. error - 其他错误运行期错误；
3. warn - 警告信息，如程序调用了一个即将作废的接口，接口的不当使用，运行状态不是期望的但仍可继续处理等；
4. info - 有意义的事件信息，如程序启动，关闭事件，收到请求事件等；
5. debug - 调试信息，可记录详细的业务处理到哪一步了，以及当前的变量状态；
6. trace - 更详细的跟踪信息；

在程序里要合理使用日志分级:

LOGGER.debug("entering getting content");
String content =CacheManager.getCachedContent();
if(content == null){

        //使用warn，因为程序还可以继续执行，但类似警告太多可能说明缓存服务不可用了，值得注意
        LOGGER.warn("Got empty content from cache,need perform database lookup");

        Connection conn = ConnectionFactory.getConnection();
        if (conn=null) {
        LOGGER.error("Can't get database connection, failed to return content");//尽量提供详细的信息，知道错误的原因，而不能简单的写logger.error("failed")       
        }else{
          try{    
        　　　content = conn.query(...);    
     　　　　}catch ( IOException e ){
                       //异常要记录错误堆栈
                       LOGGER.error("Failed to perform database lookup", e );
                    }finally{
                       ConnectionFactory.releaseConnection(conn);
                     }
               }
}  
//调试的时候可以知道方法的返回了
LOGGER.debug("returning content: "+ content);
return content;

基本的Logger编码规范

1.在一个对象中通常只使用一个Logger对象，Logger应该是static final的，只有在少数需要在构造函数中传递logger的情况下才使用private final

2.输出Exceptions的全部Throwable信息，因为logger.error(msg)和logger.error(msg,e.getMessage())这样的日志输出方法会丢失掉最重要的StackTrace信息

3.不允许记录日志后又抛出异常，因为这样会多次记录日志，只允许记录一次日志

4.不允许出现System print(包括System.out.println和System.error.println)语句

5.不允许出现printStackTrace

6.日志性能的考虑，如果代码为核心代码，执行频率非常高，则输出日志建议增加判断，尤其是低级别的输出<debug、info、warn>。

debug日志太多后可能会影响性能，有一种改进方法是：

if (LOGGER.isDebugEnabled ()) {
    LOGGER.debug("returning content: "+ content);
}

但更好的方法是Slf4j提供的最佳实践:

LOGGER.debug("returning content: {}", content);

一方面可以减少参数构造的开销，另一方面也不用多写两行代码

7.有意义的日志

通常情况下在程序日志里记录一些比较有意义的状态数据：程序启动，退出的时间点；程序运行消耗时间；耗时程序的执行进度；重要变量的状态变化。

除此之外，在公共的日志里规避打印程序的调试或者提示信息

8.使用[]进行参数变量隔离

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

什么时候应该打日志

1. 当你遇到问题的时候，只能通过debug功能来确定问题，你应该考虑打日志，良好的系统，是可以通过日志进行问题定为的。

2. 当你碰到if…else 或者 switch这样的分支时，要在分支的首行打印日志，用来确定进入了哪个分支

3. 经常以功能为核心进行开发，你应该在提交代码前，可以确定通过日志可以看到整个流程

阿里日志规范

记录日志时思考三个问题：日志是否有人看、看到这条日志能做什么、能不能提升问题排查效率

1. 【强制】应用中不可直接使用日志系统（Log4j、Logback）中的API，而应依赖使用日志框架

SLF4J中的API，使用门面模式的日志框架，有利于维护和各个类的日志处理方式统一

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

private static final Logger logger = LoggerFactory.getLogger(Abc.class);

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

3. 【强制】应用中的扩展日志（如打点、临时监控、访问日志等）命名方式：appName_logType_logName.log。logType:日志类型，推荐分类有stats/desc/monitor/visit

等；logName:日志描述。这种命名的好处：通过文件名就可知道日志文件属于什么应用，什么

类型，什么目的，也有利于归类查找。

4. 【强制】对 trace/debug/info级别的日志输出，必须使用条件输出形式或者使用占位符的方式。

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

<logger name="com.taobao.ecrm.member.config" additivity="false">

6. 【强制】异常信息应该包括两类信息：案发现场信息和异常堆栈信息。如果不处理，那么往上抛。

7. 输出的 POJO类必须重写 toString方法，否则只输出此对象的 hashCode值（地址值），没啥参考意义。

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

9. 【推荐】谨慎地记录日志。生产环境禁止输出 debug日志；有选择地输出 info日志；如果使用 warn来记录刚上线时的业务行为信息，一定要注意日志输出量的问题，避免把服务器磁盘撑爆，并记得及时删除这些观察日志

10.【参考】如果日志用英文描述不清楚，推荐使用中文注释。对于中文 UTF-8的日志，在 secureCRT中，setencoding=utf-8；如果中文字符还乱码，请设置：全局>默认的会话设置>外观>字体>选择字符集 gb2312；如果还不行，执行命令：set termencoding=gbk，并且直接使用中文来进行检索