spring boot项目中使用logback日志详解

 

最近做了一个小项目，上线时发现前端调用接口后，后端返回的数据与预期不符，一时也查不出什么原因，突然意识到项目使用日志的重要性。

目录

一、谈一谈spring boot中的默认日志

1.1 日志门面slf4j与日志实现logback

1.2 日志输出的形式

1.2.1 application.properties中的日志通用配置

1.2.2 控制台输出配置

1.2.3 文件输出

二、不得不说的自定义日志配置

1. logback-spring.xml详解

1.1 元素

1.2：元素

1.3：元素

1.4：元素

1.5：元素

1.6：元素

 2 .logback.xml详

 

一、谈一谈spring boot中的默认日志

SpringBoot为Java Util Logging，Log4J2和Logback提供了默认配置。SpringBoot默认配置日志输出到控制台，同时还提供可选文件输出。
SpringBoot默认采用SLF4j（日志抽象层）+ Logback（日志实现）的组合。

1.1 日志门面slf4j与日志实现logback

SLF4J——Simple Logging Facade For Java，它是一个针对于各类Java日志框架的统一Facade抽象。Java日志框架众多——常用的有log4j, logback，java.util.logging,，commons-logging, Spring框架使用的Jakarta Commons Logging API (JCL)。而SLF4J定义了统一的日志抽象接口，而真正的日志实现则是在运行时决定的——它提供了各类日志框架的binding。

Logback是log4j框架的作者开发的新一代日志框架，它效率更高、能够适应诸多的运行环境，同时天然支持SLF4J。默认情况下，Spring Boot会用Logback来记录日志，并用INFO级别输出到控制台。在运行应用程序和其他例子时，你应该已经看到很多INFO级别的日志了。

我们每次启动项目时，总会看到控制台打印如此内容：

从上图可以看到，日志输出内容元素具体如下：

时间日期：精确到毫秒
日志级别：ERROR, WARN, INFO, DEBUG or TRACE
进程ID
分隔符：--- 标识实际日志的开始
线程名：方括号括起来（可能会截断控制台输出）
Logger名：通常使用源代码的类名
日志内容

可以看到，在不做任何配置的情况下，控制台已经有日志输出了。这也印证了我们前面所说的。 

1.2 日志输出的形式

日志输出无非就两种方式：控制台输出、文件输出。无论哪一种输出方式，都要在application.properties中配置。文件输出还需要另外书写logback.xml配置文件。

1.2.1 application.properties中的日志通用配置

控制台常用配置详解

配置	解释	实例
logging.config	通过在类路径的根目录中或在Spring Environment属性logging.config指定的位置中提供适当的配置文件来进一步自定义各种日志记录系统	logging.config=classpath:logback-spring.xml 指定logback配置文件的路径
logging.level	作为package（包）的前缀来设置日志级别	logging.level.hpu.edu.xingsi.mapper=dubug 指定hpu.edu.xing.mapper包下的所有类的日志级别为dubug
logging.file.name	指定输出的日志文件的文件名	logging.file.name=xingsi.log
logging.file.path=	指定输出的日志文件的文件路径	logging.file.path=E:/xingsi
logging.exception-conversion-word	定义当日志发生异常时的转换字	logging.exception-conversion-word=%wEx
logging.file.max-size	默认当日志文件最大为10M，可以通过logging.file.max-size属性来调整大小	logging.file.max-size=20MB
logging.file.total-size-cap=	日志档案的总大小可以通过设置logging.file.total-size-cap的值来限定	logging.file.total-size-cap=1MB
logging.file.clean-history-on-start	当日志归档文件的总大小超过该阈值时，将删除备份。要在应用程序启动时强制进行日志归档清理，请使用logging.file.clean-history-on-start属性。	logging.file.clean-history-on-start=ture
logging.pattern.console=	指定日志输出到控制台的格式	logging.pattern.console="%d{yyyy-MM-dd HH:mm:ss.SSS} >>> [%thread] >>> %-5level >>> %logger{50} >>> %msg%n"

（1）logging.file.name与logging.file.path

默认情况下Spring Boot将日志输出到控制台，不会写到日志文件。如果要编写除控制台输出之外的日志文件，则需在application.properties中设置logging.path或logging.file属性。二者不能同时使用，如若同时使用，则只有logging.file生效。不过现在这两个配置已经被弃用。非常有趣的是 logging.file.name, logging.file.path 这两个spring 官方推荐的最新配置也不能同时生效，看似前者指定文件名称，后者指定文件路径，实则不然。

看一下spring的官网方文档

logging.file.name	logging.file.path	Example	Description
(none)	(none)		Console only logging.
Specific file	(none)	my.log	Writes to the specified log file. Names can be an exact location or relative to the current directory.
(none)	Specific directory	/var/log	Writesspring.logto the specified directory. Names can be an exact location or relative to the current directory.

logging.file.name 可以指定路径和log文件的名字

logging.file.path 只可以只当log的路径, 不能指定log的名字, 使用缺省值spring.log

二者只可以存在一个。

（2）上面只是对常用的配置进行解释说明，还有许多没有涉及。下面是spring boot官方对日志配置的详细说明文档：

Spring Environment	System Property	Comments
logging.exception-conversion-word	LOG_EXCEPTION_CONVERSION_WORD	The conversion word used when logging exceptions.
logging.file.clean-history-on-start	LOG_FILE_CLEAN_HISTORY_ON_START	Whether to clean the archive log files on startup (if LOG_FILE enabled). (Only supported with the default Logback setup.)
logging.file.name	LOG_FILE	If defined, it is used in the default log configuration.
logging.file.max-size	LOG_FILE_MAX_SIZE	Maximum log file size (if LOG_FILE enabled). (Only supported with the default Logback setup.)
logging.file.max-history	LOG_FILE_MAX_HISTORY	Maximum number of archive log files to keep (if LOG_FILE enabled). (Only supported with the default Logback setup.)
logging.file.path	LOG_PATH	If defined, it is used in the default log configuration.
logging.file.total-size-cap	LOG_FILE_TOTAL_SIZE_CAP	Total size of log backups to be kept (if LOG_FILE enabled). (Only supported with the default Logback setup.)
logging.pattern.console	CONSOLE_LOG_PATTERN	The log pattern to use on the console (stdout). (Only supported with the default Logback setup.)
logging.pattern.dateformat	LOG_DATEFORMAT_PATTERN	Appender pattern for log date format. (Only supported with the default Logback setup.)
logging.pattern.file	FILE_LOG_PATTERN	The log pattern to use in a file (if LOG_FILE is enabled). (Only supported with the default Logback setup.)
logging.pattern.level	LOG_LEVEL_PATTERN	The format to use when rendering the log level (default %5p). (Only supported with the default Logback setup.)
logging.pattern.rolling-file-name	ROLLING_FILE_NAME_PATTERN	Pattern for rolled-over log file names (default ${LOG_FILE}.%d{yyyy-MM-dd}.%i.gz). (Only supported with the default Logback setup.)
PID	PID	The current process ID (discovered if possible and when not already defined as an OS environment variable).

(3)总结
在使用SpringBoot时收集日志时，如果你对日志的显示格式以及日志文件的输出内容没有特殊的要求时，我们都甚至不需要定义日志实现框架的配置文件，只需在SpringBoot的配置文件中添加基本日志配置即可满足我们的需求，当然这些配置项有些只是针对默认的logback才生效，基础配置项列表如下 ：

debug=false
trace=false
​# LOGGING
logging.config=
logging.exception-conversion-word=%wEx
logging.file=
logging.file.max-history=0
logging.file.max-size=10MB
logging.group.*=
logging.level.*=
logging.path=
logging.pattern.console=
logging.pattern.dateformat=yyyy-MM-dd HH:mm:ss.SSS
logging.pattern.file=
logging.pattern.level=%5
plogging.register-shutdown-hook=false

 

1、debug、trace属性

默认false，如果为true，则表示打开调试或跟踪模式，调试或跟踪模式只针对SpringBoot系统内部日志，并不是所有的日志都以debug级别显示，比如我们手动通过api输出的日志就不受影响。

2、logging.config属性

该属性指定日志配置文件的所在位置，默认会从classpath的根路径加载，如果两种方式都没有指定，则根据日志框架实现类型加载默认的日志配置文件（在框架内部）。

3、logging.exception-conversion-word属性

默认值“%wEx”，主要用彩色异常日志的格式化，不常用。

4、logging.file属性

只有在SpringBoot默认的日志配置下此属性才有意义，它指定日志文件生成的完整路径或相对路径。如果是ide运行项目则相对路径以src为基准，如果是可执行jar包，则以jar包为基准。

5、logging.path属性

只有在SpringBoot默认的日志配置下此属性才有意义，它指定生成的日志文件所在的文件夹的完整路径或相对路径，相对路径的基准目录同上。如果使用此属性，则生成的日志文件名称固定，为spring.log，而且如果同时配置了logging.file属性，则以logging.file属性配置位为准。

6、logging.file.max-size属性

此属性只在默认日志实现为logback并且loggin.file属性启用之后才生效，表示日志文件的大小，单位MB。如果日志文件超过此设置的之后，会自动生成一个压缩包，压缩包的命名规则：日志文件名称.log.xxxx-xx-xx.num。

7、logging.file.max-history属性

此属性只在默认日志实现为logback并且loggin.file属性启用之后才生效，表示生成的日志文件压缩包的存档时间，默认是0，表示永远存档，如果大于0表示最多保留x天。该属性只在6属性存在的情况下才有意义。

8、logging.group属性

此属性表示的是一个日志组，它的作用在于方便的控制某个组下的日志级别，例如：

#定义com.icypt.controller包下的日志，统一由controller组管理
logging.group.controller=com.icypt.controller
#控制日志组日志级别
loggin.level.contoller=info

 

SpringBoot也预定义了一些日志组，如下：

logging.group.web=org.springframework.core.codec, org.springframework.http, org.springframework.web, org.springframework.boot.actuate.endpoint.web, org.springframework.boot.web.servlet.ServletContextInitializerBeans
logging.group.sql=org.springframework.jdbc.core, org.hibernate.SQL

所以我们在以后调试SpringBoot项目时可以通过这些预定义组来临时修改日志级别，是很方便的。

9、logging.level属性

此属性用于指定日志级别，其后可以跟root、组名称、包名称、包.类名等，例如：

logging.level.root=warn
logging.level.org.springframework.web=debug
logging.level.org.hibernate=error

这里有个优先级的问题需要注意一下：logging.level后跟的路径越详细优先级越高：

logging.level.包.类 > logging.level.包 > logging.level.组 > logging.level.root

10、格式化属性

logging.pattern.console= #格式化控制台打印的日志
logging.pattern.dateformat=yyyy-MM-dd HH:mm:ss.SSS #格式化日志日期时间
logging.pattern.file= #格式化输出到文件的日志
logging.pattern.level=%5p #格式化日志级别

11、logging.register-shutdown-hook属性

此属性默认值false，目前还未使用过此属性，不知其使用场景是什么，各位学友有谁知道，在公众号留言告诉我一下。
那么，如果你对日志记录要求不是很高，采用SpringBoot默认的logback日志框架再加上一些自定义的属性配置就可以完成日志的搜集工作了。如果以上这些设置还不能满足你的需求，就得自定义logback的配置文件了，当然也可以集成其他日志框架。

1.2.2 控制台输出配置

（1）修改控制台中日志输出格式

application.properties中配置：

logging.pattern.console=%d{yyyy-MM-dd HH:mm:ss.SSS} >>> [%thread] >>> %-5level >>> %logger{50} >>> %msg%n

控制台输出： 

（2）修改控制台日志输出级别 

logging.level.hpu.edu.xingsi.mapper=error

1.2.3 文件输出

(1)指定输出格式

application.properties中配置：

logging.pattern.file=%d{yyyy-MM-dd HH:mm:ss.SSS} >>> [%thread] >>> %-5level >>> %logger{50} >>> %msg%n

解释一下上面配置的格式：

• %d{yyyy-MM-dd HH:mm:ss.SSS}——日志输出时间
• %thread——输出日志的进程名字
• %-5level——日志级别，并且使用5个字符靠左对齐
• %logger——日志全类名长度限定为50
• %msg——日志消息
• %n——平台的换行符

（2）指定日志文件的路径 

logging.file.name=e:/log/xingsi.log

（3）滚动输出

logging.file.max-size:单个日志文件的最大大小(大于此大小时，保留日志存档，并创建一个新的日志文件)，默认10M
logging.file.max-history:设置最大存档数，如果不设置此项，则会无限存档(SpringBoot 2.1+默认为7)。
logging.file.total-size-cap:配置日志的总大小，超过此大小将删除备份

 

基本上在spring boot的配置文件application.properties中能够使用的配置也就那么多了，在很大层度上都可以满足日常项目的使用，但是当SpringBoot提供的日志功能满足不了我们的需求时，就需要用到自定义日志配置了（比如高并发环境下，为了尽可能的不让日志拖慢程序运行速度，需要将Logback配置成异步日志记录器）

 

二、不得不说的自定义日志配置

1. logback-spring.xml详解

Spring Boot官方推荐优先使用带有-spring的文件名作为你的日志配置（如使用logback-spring.xml，而不是logback.xml），命名为logback-spring.xml的日志配置文件，将xml放至 src/main/resource下面。

也可以使用自定义的名称，比如logback-config.xml，只需要在application.properties文件中使用logging.config=classpath:logback-config.xml指定即可。

在讲解 log'back-spring.xml之前我们先来了解三个单词：Logger, Appenders and Layouts（记录器、附加器、布局）：Logback基于三个主要类：Logger，Appender和Layout。 这三种类型的组件协同工作，使开发人员能够根据消息类型和级别记录消息，并在运行时控制这些消息的格式以及报告的位置。首先给出一个基本的xml配置如下：

 
  
    
    
      %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n
    
  
 
  
 
  
  
            
    
    
  

 

1.1 元素

 

logback.xml配置文件的基本结构可以描述为元素，包含零个或多个元素，后跟零个或多个元素，后跟最多一个元素(也可以没有)。下图说明了这种基本结构：

1.2：元素

元素只接受一个必需的name属性，一个可选的level属性和一个可选的additivity属性，允许值为true或false。 level属性的值允许一个不区分大小写的字符串值TRACE，DEBUG，INFO，WARN，ERROR，ALL或OFF。特殊于大小写不敏感的值INHERITED或其同义词NULL将强制记录器的级别从层次结构中的较高级别继承，元素可以包含零个或多个元素; 这样引用的每个appender都被添加到指定的logger中，(注：additivity属性下面详说)，logger元素级别具有继承性。

例1：示例中，仅为根记录器分配了级别。 此级别值DEBUG由其他记录器X，X.Y和X.Y.Z继承

Logger name	Assigned level	Effective level
root	DEBUG	DEBUG
X	none	DEBUG
X.Y	none	DEBUG
X.Y.Z	none	DEBUG

例2：所有记录器都有一个指定的级别值。 级别继承不起作用

Logger name	Assigned level	Effective level
root	ERROR	ERROR
X	INFO	INFO
X.Y	DEBUG	DEBUG
X.Y.Z	WARN	WARN

例3：记录器root，X和X.Y.Z分别被分配了DEBUG，INFO和ERROR级别。 Logger X.Y从其父X继承其级别值。

Logger name	Assigned level	Effective level
root	DEBUG	DEBUG
X	INFO	INFO
X.Y	none	INFO
X.Y.Z	ERROR	ERROR

例4：在示例4中，记录器root和X分别被分配了DEBUG和INFO级别。 记录器X.Y和X.Y.Z从其最近的父X继承其级别值，该父级具有指定的级别。

Logger name	Assigned level	Effective level
root	DEBUG	DEBUG
X	INFO	INFO
X.Y	none	INFO
X.Y.Z	none	INFO

1.3：元素

元素配置根记录器。 它支持单个属性，即level属性。 它不允许任何其他属性，因为additivity标志不适用于根记录器。 此外，由于根记录器已被命名为“ROOT”，因此它也不允许使用name属性。 level属性的值可以是不区分大小写的字符串TRACE，DEBUG，INFO，WARN，ERROR，ALL或OFF之一元素可以包含零个或多个元素; 这样引用的每个appender都被添加到根记录器中(注：additivity属性下面详说)。

1.4：元素

appender使用元素配置，该元素采用两个必需属性name和class。 name属性指定appender的名称，而class属性指定要实例化的appender类的完全限定名称。 元素可以包含零个或一个元素，零个或多个元素以及零个或多个元素，下图说明了常见的结构：

重要：在logback中，输出目标称为appender，addAppender方法将appender添加到给定的记录器logger。给定记录器的每个启用的日志记录请求都将转发到该记录器中的所有appender以及层次结构中较高的appender。换句话说，appender是从记录器层次结构中附加地继承的。例如，如果将控制台appender添加到根记录器，则所有启用的日志记录请求将至少在控制台上打印。如果另外将文件追加器添加到记录器（例如L），则对L和L的子项启用的记录请求将打印在文件和控制台上。通过将记录器的additivity标志设置为false，可以覆盖此默认行为，以便不再添加appender累积。

Appender是一个接口，它有许多子接口和实现类，具体如下图所示：

其中最重要的两个Appender为：ConsoleAppender 、RollingFileAppender。

1.4.1：ConsoleAppender

ConsoleAppender，如名称所示，将日志输出到控制台上。

1.4.2：RollingFileAppender

RollingFileAppender，是FileAppender的一个子类，扩展了FileAppender，具有翻转日志文件的功能。 例如，RollingFileAppender 可以记录到名为log.txt文件的文件，并且一旦满足某个条件，就将其日志记录目标更改为另一个文件。

有两个与RollingFileAppender交互的重要子组件。 第一个RollingFileAppender子组件，即 RollingPolicy 负责执行翻转所需的操作。 RollingFileAppender的第二个子组件，即 TriggeringPolicy 将确定是否以及何时发生翻转。 因此，RollingPolicy 负责什么和TriggeringPolicy 负责什么时候。

作为任何用途，RollingFileAppender 必须同时设置 RollingPolicy 和 TriggeringPolicy。 但是，如果其 RollingPolicy 也实现了TriggeringPolicy 接口，则只需要显式指定前者。

1.4.3：滚动策略

TimeBasedRollingPolicy：可能是最受欢迎的滚动策略。 它根据时间定义翻转策略，例如按天或按月。 TimeBasedRollingPolicy承担滚动和触发所述翻转的责任。 实际上，TimeBasedTriggeringPolicy实现了RollingPolicy和TriggeringPolicy接口。

SizeAndTimeBasedRollingPolicy：有时您可能希望按日期归档文件，但同时限制每个日志文件的大小，特别是如果后处理工具对日志文件施加大小限制。 为了满足此要求，logback 提供了 SizeAndTimeBasedRollingPolicy ，它是TimeBasedRollingPolicy的一个子类，实现了基于时间和日志文件大小的翻滚策略。

1.5：元素

 encoder中最重要就是pattern属性，它负责控制输出日志的格式，这里给出一个我自己写的示例：

%d{yyyy-MM-dd HH:mm:ss.SSS} %highlight(%-5level) --- [%15.15(%thread)] %cyan(%-40.40(%logger{40})) : %msg%n

使用后的输出格式如下图所示

其中：%d{yyyy-MM-dd HH:mm:ss.SSS}：日期

          %-5level：日志级别

          %highlight()：颜色，info为蓝色，warn为浅红，error为加粗红，debug为黑色

          %thread：打印日志的线程

          %15.15():如果记录的线程字符长度小于15(第一个)则用空格在左侧补齐,如果字符长度大于15(第二个),则从开头开始截断多余的字符 

          %logger：日志输出的类名

          %-40.40()：如果记录的logger字符长度小于40(第一个)则用空格在右侧补齐,如果字符长度大于40(第二个),则从开头开始截断多余的字符

         %cyan：颜色

         %msg：日志输出内容

         %n：换行符

1.6：元素

filter中最重要的两个过滤器为：LevelFilter、ThresholdFilter。

LevelFilter 根据精确的级别匹配过滤事件。 如果事件的级别等于配置的级别，则筛选器接受或拒绝该事件，具体取决于onMatch和onMismatch属性的配置。 例如下面配置将只打印INFO级别的日志，其余的全部禁止打印输出：

  
    
      INFO
      ACCEPT
      DENY
    
    
      
        %-4relative [%thread] %-5level %logger{30} - %msg%n
      
    
  
  
    
  

 
ThresholdFilter 过滤低于指定阈值的事件。 对于等于或高于阈值的事件，ThresholdFilter将在调用其decision（）方法时响应NEUTRAL。 但是，将拒绝级别低于阈值的事件，例如下面的配置将拒绝所有低于INFO级别的日志，只输出INFO以及以上级别的日志：

  
    
    
      INFO
    
    
      
        %-4relative [%thread] %-5level %logger{30} - %msg%n
      
    
  
  
    
  

2.2 logback.xml详解

以上介绍了xml中重要的几个元素，下面将我配置的xml贴出来以供参考（实现了基于日期和大小翻滚的策略，以及经INFO和ERROR日志区分输出，还有规范日志输出格式等）：

 
    
    
    
        
        
        
            
            
            
            
            
            
            
            %d{yyyy-MM-dd HH:mm:ss.SSS} %highlight(%-5level) --- [%15.15(%thread)] %cyan(%-40.40(%logger{40})) : %msg%n
            
            UTF-8
        
    
 
    
    
    
    
    
        
        logs/project_info.log
        
        true
        
            ERROR
            DENY
            ACCEPT
        
        
        
            
            
            
            logs/project_info.%d.%i.log
            
            30
            
            20GB
            
            10MB
        
        
        
            
            %d{yyyy-MM-dd HH:mm:ss.SSS} %-5level --- [%15.15(%thread)] %-40.40(%logger{40}) : %msg%n
            
            UTF-8
        
    
 
    
    
    
    
    
        
        logs/project_error.log
        
        true
        
        
            ERROR
        
        
        
            
            
            
            logs/project_error.%d.%i.log
            
            30
            
            20GB
            
            10MB
        
        
        
            
            %d{yyyy-MM-dd HH:mm:ss.SSS} %-5level --- [%15.15(%thread)] %-40.40(%logger{40}) : %msg%n
            
            UTF-8
        
    
 
    
    
    
        
    
 
    
    
    
        
        
    
 
    
    
        
        
    
 
    
    
        
        
    
 

三、项目中使用日志时的注意事项

这里再说下log日志输出代码，一般有人可能在代码中使用如下方式输出：

Object entry = new SomeObject(); 
logger.debug("The entry is " + entry);

上面看起来没什么问题，但是会存在构造消息参数的成本，即将entry转换成字符串相加。并且无论是否记录消息，都是如此，即：那怕日志级别为INFO，也会执行括号里面的操作，但是日志不会输出，下面是优化后的写法：

if(logger.isDebugEnabled()) { 
    Object entry = new SomeObject(); 
    logger.debug("The entry is " + entry);
}

 上面的写法，首先对设置的日志级别进行了判断，如果为debug模式，才进行参数的构造，对第一种写法进行了改善。不过还有最好的写法，使用占位符：

Object entry = new SomeObject(); 
logger.debug("The entry is {}.", entry);

 只有在评估是否记录之后，并且只有在决策是肯定的情况下，记录器实现才会格式化消息并将“{}”对替换为条目的字符串值。 换句话说，当禁用日志语句时，此表单不会产生参数构造的成本。

logback作者进行测试得出：第一种和第三种写法将产生完全相同的输出。 但是，在禁用日志记录语句的情况下，第三个变体将比第一个变体优于至少30倍。

如果有多个参数，写法如下：

logger.debug("The new entry is {}. It replaces {}.", entry, oldEntry);

如果需要传递三个或更多参数，则还可以使用Object []变体：

Object[] paramArray = {newVal, below, above};
logger.debug("Value {} was inserted between {} and {}.", paramArray);

 记录日志的时候我们可能需要在文件中记录下异常的堆栈信息，经过测试，logger.error(e) 不会打印出堆栈信息，正确的写法是：

logger.error("程序异常, 详细信息:{}", e.getLocalizedMessage() , e);