Spring Boot 参考指南（日志记录）

26. 日志记录

Spring Boot为所有内部日志记录使用Commons Logging，但开放底层日志实现，提供了Java Util Logging、Log4J2和Logback的默认配置，在每种情况下，日志记录器都被预先配置为使用控制台输出，可选的文件输出也可用。

默认情况下，如果使用“Starter”，则使用Logback进行日志记录，还包括适当的Logback路由，以确保使用Java Util Logging、Commons Logging、Log4J或SLF4J的依赖库都能正确工作。

Java有很多日志框架可用，如果上面的列表看起来很混乱，不要担心。一般情况下，你不需要更改日志依赖项，Spring Boot缺省值也可以正常工作。

26.1 日志格式

Spring Boot的默认日志输出类似于以下示例:

2014-03-05 10:57:51.112  INFO 45469 --- [           main] org.apache.catalina.core.StandardEngine  : Starting Servlet Engine: Apache Tomcat/7.0.52
2014-03-05 10:57:51.253  INFO 45469 --- [ost-startStop-1] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2014-03-05 10:57:51.253  INFO 45469 --- [ost-startStop-1] o.s.web.context.ContextLoader            : Root WebApplicationContext: initialization completed in 1358 ms
2014-03-05 10:57:51.698  INFO 45469 --- [ost-startStop-1] o.s.b.c.e.ServletRegistrationBean        : Mapping servlet: 'dispatcherServlet' to [/]
2014-03-05 10:57:51.702  INFO 45469 --- [ost-startStop-1] o.s.b.c.embedded.FilterRegistrationBean  : Mapping filter: 'hiddenHttpMethodFilter' to: [/*]

下面是输出项：

• 日期和时间：毫秒精度，易于分类。
• 日志级别：ERROR、WARN、INFO、DEBUG或TRACE。
• 进程ID。
• ---分隔符，用于区分实际日志消息的开始。
• 线程名称：用方括号括起来（可能被截断用于控制台输出）。
• 记录器名称：这通常是源类名称（通常缩写）。
• 日志消息。

Logback没有FATAL级别，它被映射为ERROR。

26.2 控制台输出

默认的日志配置会在消息被写入时向控制台回显，默认情况下，ERROR-级别、WARN-级别和INFO-级别的消息将被记录下来，还可以通过使用--debug标志启动应用程序来启用“debug”模式。

$ java -jar myapp.jar --debug

你还可以在application.properties中指定debug=true。

启用调试模式时，将配置核心日志记录器（嵌入式容器、Hibernate和Spring Boot）的选择，以输出更多信息，启用调试模式不会将应用程序配置为使用DEBUG级别记录所有消息。

或者，你可以启用“trace”模式，通过使用--trace标志启动应用程序（或在application.properties中trace=true），这样做可以使trace日志记录用于选择核心日志记录器（嵌入式容器、Hibernate模式生成和整个Spring组合）。

26.2.1 彩色编码输出

如果你的终端支持ANSI，则使用颜色输出来帮助提高可读性，你可以将spring.output.ansi.enabled设置为支持的值，以覆盖自动检测。

颜色编码是通过使用%clr转译符来配置的，在最简单的形式中，转换器将输出按照日志级别进行着色，如下面的示例所示:

%clr(%5p)

下表描述了日志级别到颜色的映射：

级别	颜色
FATAL	Red
ERROR	Red
WARN	Yellow
INFO	Green
DEBUG	Green
TRACE	Green

或者，你也可以通过提供颜色或样式作为转换的选项来指定应该使用的颜色或样式，例如，要使文本变为黄色，请使用以下设置:

%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){yellow}

支持以下颜色和风格:

• blue
• cyan
• faint
• green
• magenta
• red
• yellow

26.3 文件输出

默认情况下，Spring Boot日志只记录到控制台，不写日志文件，如果你想在控制台输出之外写入日志文件，你需要设置logging.file或logging.path属性（例如，在你的application.properties中）。

下表显示了如何将logging.*属性结合使用:

表26.1. Logging属性

logging.file	logging.path	样例	描述
(none)	(none)		只控制台记录日志
指定文件	(none)	my.log	写入指定的日志文件，名称可以是一个确切的位置或相对于当前目录
(none)	指定文件	/var/log	写如spring.log到指定的目录，名称可以是一个确切的位置或相对于当前目录

日志文件在达到10MB时就会回滚，与控制台输出一样，默认情况下会记录ERROR-级别、WARN-级别和INFO-级别的消息，可以使用logging.file.max-size属性更改大小限制，除非logging.file.max-history属性已被设置，否则之前回滚的文件将被无限期地归档。

日志系统在应用程序生命周期的早期初始化，因此，在通过@PropertySource注解加载的属性文件中没有发现日志属性。

日志记录属性独立于实际的日志记录基础设施，因此，特定的配置键（例如Logback的logback.configurationFile）不是由spring Boot管理的。

26.4 日志级别

所有受支持的日志系统都可以在Spring Environment中通过使用logging.level.<logger-name>=<level>（例如application.properties）中设置日志记录器级别，其中level为TRACE、DEBUG、INFO、WARN、ERROR、FATAL或OFF，可以使用logging.level.root配置root日志记录器。

下面的示例展示了application.properties中可能的日志记录设置：

logging.level.root=WARN
logging.level.org.springframework.web=DEBUG
logging.level.org.hibernate=ERROR

26.5 自定义日志配置

可以通过在类路径中包含适当的库来激活各种日志系统，还可以通过在类路径的根目录中或在以下Spring Environment属性（logging.config）指定的位置中提供合适的配置文件来进一步定制。

你可以通过使用org.springframework.boot.logging.LoggingSystem来强制Spring Boot使用特定的日志系统，值应该是LoggingSystem实现的完全限定类名，你还可以完全通过使用none值来禁用Spring Boot的日志配置。

因为日志是在创建ApplicationContext之前初始化的，无法在Spring @Configuration文件中控制来自@PropertySources的logging，更改日志系统或完全禁用日志系统的唯一方法是通过系统属性。

依赖于你的日志系统，加载下列文件：

Logging系统	自定义
Logback	logback-spring.xml，logback-spring.groovy，logback.xml，或logback.groovy
Log4j2	log4j2-spring.xml或log4j2.xml
JDK (Java Util Logging)	logging.properties

如果可能的话，我们建议你对logging配置使用-spring变体（例如，logback-spring.xml而不是logback.xml），如果使用标准配置位置，Spring不能完全控制日志初始化。

Java Util Logging存在已知的类加载问题，当从“可执行jar”运行时，会导致问题，如果可能的话，我们建议你在运行“可执行jar”时避免使用它。

为了帮助定制，一些其他属性从Spring Environment转移到系统属性，如下表所示：

Spring环境	系统属性	注释
logging.exception-conversion-word	LOG_EXCEPTION_CONVERSION_WORD	记录异常时使用的转换词
logging.file	LOG_FILE	如果定义，则在默认日志配置中使用
logging.file.max-size	LOG_FILE_MAX_SIZE	最大日志文件大小（如果启用LOG_FILE），（只支持默认的Logback设置）
logging.file.max-history	LOG_FILE_MAX_HISTORY	要保存的归档日志文件的最大数量（如果启用LOG_FILE），（只支持默认的Logback设置）
logging.path	LOG_PATH	如果定义，则在默认日志配置中使用
logging.pattern.console	CONSOLE_LOG_PATTERN	控制台上要使用的日志模式（stdout），（只支持默认的Logback设置）
logging.pattern.dateformat	LOG_DATEFORMAT_PATTERN	日志日期格式的附加模式，（只支持默认的Logback设置）
logging.pattern.file	FILE_LOG_PATTERN	在文件中使用的日志模式（如果启用了LOG_FILE），（只支持默认的Logback设置）
logging.pattern.level	LOG_LEVEL_PATTERN	在呈现日志级别时使用的格式（默认%5p），（只支持默认的Logback设置）
PID	PID	当前进程ID（如果可能的话会被发现，当还没有被定义为OS环境变量时）

所有支持的日志系统在解析配置文件时都可以参考系统属性，在spring-boot.jar中看默认配置的例子：

• Logback
• Log4j 2
• Java Util logging

如果希望在logging属性中使用占位符，你应该使用Spring Boot的语法，而不是底层框架的语法，值得注意的是，如果你使用Logback，你应该使用:作为属性名与其默认值之间的分隔符，而不是使用:-。

---

你可以通过只覆盖LOG_LEVEL_PATTERN（或使用Logback的logging.pattern.level）来将MDC和其他特殊内容添加到日志行中，例如，如果你使用logging.pattern.level=user:%X{user} %5p，然后，默认的日志格式包含“user”的MDC项，如果存在，如下例所示。

2015-09-30 12:30:04.031 user:someone INFO 22174 --- [  nio-8080-exec-0] demo.Controller
Handling authenticated request

26.6 Logback扩展

Spring Boot包含许多可以帮助进行高级配置的Logback扩展，你可以在你的logback-spring.xml配置文件使用这些扩展。

因为标准logback.xml配置文件过早地加载，不能在其中使用扩展，你需要使用logback-spring.xml或定义logging.config属性。

不能使用Logback的配置扫描来使用扩展，如果你尝试这样做，对配置文件进行更改将导致类似于下面记录的错误之一:

ERROR in ch.qos.logback.core.joran.spi.Interpreter@4:71 - no applicable action for [springProperty], current ElementPath is [[configuration][springProperty]]
ERROR in ch.qos.logback.core.joran.spi.Interpreter@4:71 - no applicable action for [springProfile], current ElementPath is [[configuration][springProfile]]

26.6.1 特殊配置文件配置

通过<springProfile>标签，你可以根据激活的Spring配置文件选择包含或排除配置的部分。在<configuration>元素中的任何地方都支持配置文件部分，使用name属性指定哪个配置文件接受配置，可以使用逗号分隔的列表指定多个配置文件，下面的清单显示了三个示例配置文件：

<springProfile name="staging">
    <!-- configuration to be enabled when the "staging" profile is active -->
</springProfile>

<springProfile name="dev, staging">
    <!-- configuration to be enabled when the "dev" or "staging" profiles are active -->
</springProfile>

<springProfile name="!production">
    <!-- configuration to be enabled when the "production" profile is not active -->
</springProfile>

26.6.2 环境属性

通过<springProperty>标记，可以从Spring Environment中公开属性，以便在Logback中使用，如果你希望在Logback配置中从application.properties文件中访问值，那么这样做是很有用的，标签的工作方式与Logback的标准<property>标签类似。但是，不是指定直接value，而是指定属性的source（来自Environment）。如果你需要将属性存储在本地范围之外的其他地方，则可以使用scope属性，如果需要回退值（如果Environment中没有设置属性），可以使用defaultValue属性，下面的示例展示了如何在Logback中公开属性以供使用：

<springProperty scope="context" name="fluentHost" source="myapp.fluentd.host"
        defaultValue="localhost"/>
<appender name="FLUENT" class="ch.qos.logback.more.appenders.DataFluentAppender">
    <remoteHost>${fluentHost}</remoteHost>
    ...
</appender>

必须在连接符形式中指定source（例如my.property-name），但是，可以使用宽松的规则将属性添加到Environment中。

---

上一篇：配置文件

下一篇：开发Web应用程序