某大型银行深化系统之十九：日志规范

传送门 ☞ 轮子的专栏 ☞ 转载请注明 ☞ http://blog.youkuaiyun.com/leverage_1229

        在应用程序中添加程序日志记录可以跟踪代码运行时轨迹，作为日后审计的依据；并且担当集成开发环境中的调试器的作用，向文件打印代码的调试信息。本规定Jave EE项目必须使用Commons-Logging作为日志接口封装，选用Apache提供的可重用组件Log4j作为底层实现。

1日志命名规范

        根日志（root logger）位于日志层次的最顶层，它的日志级别不能指派为空；不能通过使用它的名字直接得到它，而应该通过类的静态方法Logger.getRootLogger得到它（指root logger）。所有其他的日志可通过静态方法Logger.getLogger来实例化并获取，这个方法Logger.getLogger把所想要的logger的名字作为参数，一般取本类的名字作为参数。

2日志信息级别规范

        日志信息输出的优先级从高到低至少应分为五档，分别是Fatal、ERROR、WARN、INFO、DEBUG。这些级别用来指定这条日志信息的重要程度。在测试阶段可以打开所有级别的日志，系统上线后只允许输出INFO以上级别（含INFO）。各级别的日志信息作用规定如下：

2.1致命（Fatal）

        严重的错误，系统无法正常运行，如硬盘空间满等。这个级别很少被用，常暗含系统或者系统的组件迫近崩溃。

2.2错误（Error）

        系统可以继续运行，但最好要尽快修复的错误。这个级别用的较多，常常伴随Java异常，错误(Error)的环境不一定会造成系统的崩溃，系统可以继续服务接下来的请求。

2.3警告（Warn）

        系统可以正常运行，但需要引起注意的警告信息。这个级别预示较小的问题，由系统外部的因素造成的，比如用户输入了不符合条件的参数。

2.4信息（Info）

        系统运行的主要关键时点的操作信息，一般用于记录业务日志。但同时，也应该有足够的信息以保证可以记录再现缺陷的路径。这个级别记录了系统日常运转中有意义的事件。

2.5调试（Debug）

        系统运行中的调试信息，便于开发人员进行错误分析和修正，一般用于程序日志，关心程序操作(细粒度)，不太关心业务操作(粗粒度)。系统出现问题时，必须抛出异常，在处理异常时记录日志，且日志级别必须是前三个级别（Fatal\Error\Warning）中的一种。

3日志配置规范

        所有的日志配置文件放在src目录下，编译时随同.class文件一同拷贝到(%webapp_HOME%)\WEB-INF\classes\目录下，这些配置文件必须采用properties文件的编写方法， commons-logging.properties文件用来指定commons-logging的实现为log4j，log4j.properties文件用来配置log4j的所有参数，日志配置信息不得配置在这两个文件以外的文件中。

4日志对多线程的支持规范

        日志记录必须支持多线程。当应用程序同时处理多个客户的请求时，不同客户之间的日志信息写同一个日志文件时不应产生冲突，不同请求的日志信息能被显示并区分出来。在应用系统中，必须使用log4j NDC(Nested Diagnostic Contexts)来处理多线程的日志记录。当程序响应请求时，通过Log4J NDC(Nested Diagnostic Contexts)机制，将日志（logger）推入栈中，当程序完成处理或抛出异常时，NDC弹栈，以保证同一线程日志的一致性。

5日志输出规范

        应用程序禁止直接使用Log4J API，并且禁止使用JDK Console输出(System.out, System.err, ex.printStackTrace(), etc.)。所有的日志实例的属性都应从根日志（root logger）继承。日志信息必须支持输出到控制台（console）和文本文件（TextFiles）。输出到文本文件（TextFiles）的日志，必须提供日志文件分析脚本，以方便查询和阅读。

6日志文件组织与备份规范

6.1文件组织方式

        即日志文件名必须满足<系统名称>.log.yyyyMMddHH的命名规则。yyyyMMddHH表示每日整点时重新命名日志文件，以方便按时间定位日志信息；文件大小限制为最多20Mb，即当日志文件超过20Mb时，旧日志文件重命名为<系统名称>.log.yyyyMMddHH.n(n从1开始编号以步长1递增)，新日志写入<系统名称>.log.yyyyMMddHH。这里的<系统名称>表示各个实际项目的英文缩写，英文缩写必须遵循单位对系统英文缩写的统一规定。

6.2日志备份机制

        每天营业结束后，必须先对当天日志进行压缩，再做磁带备份，生产机上保留最近5个工作日的日志备份。
        日志的输出格式(不包括异常树信息)规定如下：
日期(yyyy-M-d) 时间(HH:mm:ss) NDC标志[级别](对应程序文件名:行号)定制信息。即，%d{yyyy-M-d HH:mm:ss}%x[%5p](%F:%L) %m%n

7日志内容规范

        对于“敏感”的单位信息，如客户密码、余额等信息，禁止使用debug以上级别的日志方法记录，在开发过程中，也应减少日志对该类信息的记录。
所有的异常（Exception）都必须写在日志中，当系统抛出异常时，除了使用log.error()记录定制信息外，还必须打印异常树信息，例如log.error(定制信息, e)。

8日志编写规范

        在输出日志之前完成字符串操作，禁止一些结构复杂的对象被直接放入日志中作字符串处理。如下方式的日志记录方法是不正确的：

logger.debug("Entry User: " + UserBO + " is " + String.valueOf(entry));

这种调用方式会引起过多的构建信息参数的花费。定制信息的组合必须在输出日志之前完成字符串的操作，可使用StringBuffer提高效率。
        为了防止因特殊情况需要关闭所有系统日志，而引起系统性能急剧下降。要在调用DEBUG时，必须判断DEBUG级别是否生效，其他级别无需判断。如直接调用log.debug(tmpString)是错误的，必须采用以下方法处理DEBUG级别的日志：

if (log.isDebugEnabled()){
    log.debug(tmpString);
}