日志记录

Spring Boot 使用 Commons Logging 进行所有内部日志记录，但底层日志实现保持开放。默认配置适用于 Java Util Logging、Log4j2 和 Logback。在每种情况下，日志记录器都预先配置为使用控制台输出，并可选地提供文件输出。

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

Java 有很多可用的日志框架。如果上面的列表看起来令人困惑，请不要担心。通常，您无需更改日志记录依赖项，Spring Boot 默认设置即可正常工作。
当您将应用程序部署到 Servlet 容器或应用程序服务器时，使用 Java Util Logging API 执行的日志记录不会路由到应用程序的日志中。这可以防止容器或已部署到其中的其他应用程序执行的日志记录出现在应用程序的日志中。

日志格式

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

2024-10-24T12:02:42.179Z  INFO 112052 --- [myapp] [           main] o.s.b.d.f.logexample.MyApplication       : Starting MyApplication using Java 17.0.13 with PID 112052 (/opt/apps/myapp.jar started by myuser in /opt/apps/)
2024-10-24T12:02:42.211Z  INFO 112052 --- [myapp] [           main] o.s.b.d.f.logexample.MyApplication       : No active profile set, falling back to 1 default profile: "default"
2024-10-24T12:02:45.743Z  INFO 112052 --- [myapp] [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port 8080 (http)
2024-10-24T12:02:45.764Z  INFO 112052 --- [myapp] [           main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2024-10-24T12:02:45.765Z  INFO 112052 --- [myapp] [           main] o.apache.catalina.core.StandardEngine    : Starting Servlet engine: [Apache Tomcat/10.1.31]
2024-10-24T12:02:45.863Z  INFO 112052 --- [myapp] [           main] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2024-10-24T12:02:45.869Z  INFO 112052 --- [myapp] [           main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 3429 ms
2024-10-24T12:02:47.030Z  INFO 112052 --- [myapp] [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port 8080 (http) with context path '/'
2024-10-24T12:02:47.049Z  INFO 112052 --- [myapp] [           main] o.s.b.d.f.logexample.MyApplication       : Started MyApplication in 6.238 seconds (process running for 7.345)

输出以下项目：

  • 日期和时间：毫秒精度且易于排序。

  • 日志级别：ERROR、WARN、INFO、DEBUG 或 TRACE。

  • 进程 ID。

  • --- 分隔符，用于区分实际日志消息的开始。

  • 应用程序名称：用方括号括起来（仅当设置了 spring.application.name 时才默认记录）。

  • 线程名称：用方括号括起来（控制台输出可能被截断）。

  • 关联 ID：如果启用了跟踪（在上面的示例中未显示）。

  • 日志记录器名称：这通常是源类名（通常缩写）。

  • 日志消息。

Logback 没有FATAL级别。它映射到ERROR。
如果您有spring.application.name属性但不想记录它，您可以将logging.include-application-name设置为false。

控制台输出

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

$ java -jar myapp.jar --debug
您也可以在application.properties文件中指定debug=true。

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

或者，您可以通过使用--trace标志启动应用程序（或在application.properties文件中使用trace=true）来启用“跟踪”模式。这样做会为一些核心日志记录器（嵌入式容器、Hibernate模式生成和整个Spring框架）启用跟踪日志记录。

彩色输出

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

颜色编码是通过使用%clr转换词来配置的。在其最简单的形式中，转换器会根据日志级别对输出进行着色，如下例所示

%clr(%5p)

下表描述了日志级别与颜色的映射关系

级别 颜色

FATAL

红色

ERROR

红色

WARN

黄色

INFO

绿色

DEBUG

绿色

TRACE

绿色

或者，您可以通过将其作为转换器的选项来指定要使用的颜色或样式。例如，要使文本显示为黄色，请使用以下设置

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

支持以下颜色和样式

  • 蓝色 (blue)

  • 青色 (cyan)

  • 浅色 (faint)

  • 绿色 (green)

  • 品红色 (magenta)

  • 红色 (red)

  • 黄色 (yellow)

文件输出

默认情况下，Spring Boot 仅将日志记录到控制台，而不写入日志文件。如果除了控制台输出之外还想写入日志文件，则需要设置logging.file.name或logging.file.path属性（例如，在您的application.properties文件中）。如果同时设置这两个属性，则会忽略logging.file.path，只使用logging.file.name。

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

表 1. 日志属性
logging.file.name logging.file.path 描述

(无)

(无)

仅控制台日志记录。

特定文件（例如，my.log）

(无)

写入由logging.file.name指定的路径。该路径可以是绝对路径或相对于当前目录的相对路径。

(无)

特定目录（例如，/var/log）

将spring.log写入由logging.file.path指定的目录。该目录可以是绝对路径或相对于当前目录的相对路径。

特定文件

特定目录

写入由logging.file.name指定的路径，并忽略logging.file.path。该路径可以是绝对路径或相对于当前目录的相对路径。

日志文件达到 10 MB 时会进行轮转，并且与控制台输出一样，默认情况下会记录ERROR级别、WARN级别和INFO级别的消息。

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

文件轮转

如果您使用的是 Logback，则可以使用您的application.properties或application.yaml文件微调日志轮转设置。对于所有其他日志系统，您需要自己直接配置轮转设置（例如，如果您使用 Log4j2，则可以添加log4j2.xml或log4j2-spring.xml文件）。

支持以下轮转策略属性

名称 描述

logging.logback.rollingpolicy.file-name-pattern

用于创建日志存档的文件名模式。

logging.logback.rollingpolicy.clean-history-on-start

应用程序启动时是否应进行日志存档清理。

logging.logback.rollingpolicy.max-file-size

日志文件在存档之前的最大大小。

logging.logback.rollingpolicy.total-size-cap

日志存档在被删除之前可以占用的最大大小。

logging.logback.rollingpolicy.max-history

要保留的最大存档日志文件数（默认为 7）。

日志级别

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

以下示例显示了application.properties中可能的日志设置

  • 属性

  • YAML

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

也可以使用环境变量设置日志级别。例如，LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=DEBUG 将org.springframework.web设置为DEBUG。

上述方法仅适用于包级别的日志记录。由于宽松绑定始终将环境变量转换为小写，因此无法以此方式配置单个类的日志记录。如果需要配置类的日志记录，可以使用SPRING_APPLICATION_JSON变量。

日志组

通常，能够将相关的日志记录器组合在一起以便可以同时配置它们非常有用。例如，您可能经常更改所有与 Tomcat 相关的日志记录器的日志级别，但您无法轻松记住顶级包。

为了帮助解决这个问题，Spring Boot 允许您在 Spring Environment中定义日志组。例如，以下是如何通过将其添加到您的application.properties中来定义“tomcat”组：

  • 属性

  • YAML

logging.group.tomcat=org.apache.catalina,org.apache.coyote,org.apache.tomcat
logging:
  group:
    tomcat: "org.apache.catalina,org.apache.coyote,org.apache.tomcat"

定义后，您可以使用一行代码更改组中所有日志记录器的级别

  • 属性

  • YAML

logging.level.tomcat=trace
logging:
  level:
    tomcat: "trace"

Spring Boot 包括以下可以即用型使用的预定义日志组

名称 日志记录器

web

org.springframework.core.codec, org.springframework.http, org.springframework.web, org.springframework.boot.actuate.endpoint.web, org.springframework.boot.web.servlet.ServletContextInitializerBeans

sql

org.springframework.jdbc.core, org.hibernate.SQL, org.jooq.tools.LoggerListener

使用日志关闭钩子

为了在应用程序终止时释放日志资源，提供了一个关闭钩子，该钩子将在 JVM 退出时触发日志系统清理。除非您的应用程序作为 war 文件部署，否则会自动注册此关闭钩子。如果您的应用程序具有复杂的上下文层次结构，则关闭钩子可能无法满足您的需求。如果不能满足，请禁用关闭钩子并调查底层日志系统提供的选项。例如，Logback 提供了上下文选择器，允许在各自的上下文中创建每个 Logger。您可以使用logging.register-shutdown-hook属性禁用关闭钩子。将其设置为false将禁用注册。您可以在application.properties或application.yaml文件中设置该属性

  • 属性

  • YAML

logging.register-shutdown-hook=false
logging:
  register-shutdown-hook: false

自定义日志配置

可以通过在类路径中包含相应的库来激活各种日志系统，并且可以通过在类路径的根目录或以下 Spring Environment属性指定的路径中提供合适的配置文件来进一步自定义：logging.config。

您可以强制 Spring Boot 使用特定的日志系统，方法是使用org.springframework.boot.logging.LoggingSystem系统属性。该值应该是LoggingSystem实现的完全限定类名。您也可以使用none值完全禁用 Spring Boot 的日志配置。

由于日志记录是在创建ApplicationContext**之前**初始化的，因此无法从 Spring @Configuration文件中的@PropertySources控制日志记录。更改日志系统或完全禁用它的唯一方法是通过系统属性。

根据您的日志系统，将加载以下文件

日志系统 自定义

Logback

logback-spring.xml、logback-spring.groovy、logback.xml或logback.groovy

Log4j2

log4j2-spring.xml或log4j2.xml

JDK（Java Util Logging）

logging.properties
如果可能，我们建议您使用日志配置的-spring变体（例如，logback-spring.xml而不是logback.xml）。如果您使用标准配置位置，Spring 无法完全控制日志初始化。
Java Util Logging 存在已知的类加载问题，在从“可执行 jar”运行时会导致问题。我们建议您尽可能避免在从“可执行 jar”运行时使用它。

为了帮助进行自定义，一些其他属性会从 Spring Environment转移到系统属性。这允许日志系统配置使用这些属性。例如，在application.properties中设置logging.file.name或作为环境变量设置LOGGING_FILE_NAME将导致设置LOG_FILE系统属性。转移的属性在下表中进行了描述

Spring 环境 系统属性 注释

logging.exception-conversion-word

LOG_EXCEPTION_CONVERSION_WORD

记录异常时使用的转换词。

logging.file.name

LOG_FILE

如果已定义，则在默认日志配置中使用。

logging.file.path

LOG_PATH

如果已定义，则在默认日志配置中使用。

logging.pattern.console

CONSOLE_LOG_PATTERN

在控制台（stdout）上使用的日志模式。

logging.pattern.dateformat

LOG_DATEFORMAT_PATTERN

附加程序模式用于日志日期格式。

logging.charset.console

CONSOLE_LOG_CHARSET

控制台日志使用的字符集。

logging.threshold.console

CONSOLE_LOG_THRESHOLD

控制台日志使用的日志级别阈值。

logging.pattern.file

FILE_LOG_PATTERN

文件中使用的日志模式（如果启用了LOG_FILE）。

logging.charset.file

FILE_LOG_CHARSET

文件日志使用的字符集（如果启用了LOG_FILE）。

logging.threshold.file

FILE_LOG_THRESHOLD

文件日志使用的日志级别阈值。

logging.pattern.level

LOG_LEVEL_PATTERN

渲染日志级别时使用的格式（默认值为%5p）。

PID

PID

当前进程ID（如果可能，并且未定义为操作系统环境变量时会自动发现）。

如果您使用Logback，则还会传递以下属性

Spring 环境 系统属性 注释

logging.logback.rollingpolicy.file-name-pattern

LOGBACK_ROLLINGPOLICY_FILE_NAME_PATTERN

滚动日志文件的命名模式（默认值为${LOG_FILE}.%d{yyyy-MM-dd}.%i.gz）。

logging.logback.rollingpolicy.clean-history-on-start

LOGBACK_ROLLINGPOLICY_CLEAN_HISTORY_ON_START

是否在启动时清除存档日志文件。

logging.logback.rollingpolicy.max-file-size

LOGBACK_ROLLINGPOLICY_MAX_FILE_SIZE

最大日志文件大小。

logging.logback.rollingpolicy.total-size-cap

LOGBACK_ROLLINGPOLICY_TOTAL_SIZE_CAP

要保留的日志备份的总大小。

logging.logback.rollingpolicy.max-history

LOGBACK_ROLLINGPOLICY_MAX_HISTORY

要保留的最大存档日志文件数量。

所有支持的日志系统在解析其配置文件时都可以参考系统属性。有关示例，请参阅spring-boot.jar中的默认配置。

如果要在日志属性中使用占位符，则应使用Spring Boot的语法，而不是底层框架的语法。尤其是在使用Logback时，应使用:作为属性名称及其默认值之间的分隔符，而不是使用:-。

您可以通过仅覆盖LOG_LEVEL_PATTERN（或使用Logback的logging.pattern.level）来向日志行添加MDC和其他临时内容。例如，如果您使用logging.pattern.level=user:%X{user} %5p，则默认日志格式包含“user”的MDC条目（如果存在），如下例所示。

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

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]]

特定于配置文件的配置

<springProfile>标签允许您根据活动的Spring配置文件有选择地包含或排除配置部分。配置文件部分在<configuration>元素中的任何位置都受支持。使用name属性指定哪个配置文件接受配置。<springProfile>标签可以包含配置文件名称（例如staging）或配置文件表达式。配置文件表达式允许表达更复杂的配置文件逻辑，例如production & (eu-central | eu-west)。有关更多详细信息，请查看Spring Framework参考指南。以下列表显示了三个示例配置文件

<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>

环境属性

<springProperty>标签允许您公开Spring Environment中的属性以便在Logback中使用。如果您想在Logback配置中访问application.properties文件中的值，这样做会很有用。该标签的工作方式类似于Logback的标准<property>标签。但是，您不是指定直接的value，而是指定属性的source（来自Environment）。如果您需要将属性存储在local范围之外的某个位置，则可以使用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。

Log4j2扩展

Spring Boot包含许多Log4j2扩展，可以帮助进行高级配置。您可以在任何log4j2-spring.xml配置文件中使用这些扩展。

由于标准的log4j2.xml配置文件加载过早，因此您不能在其中使用扩展。您需要使用log4j2-spring.xml或定义logging.config属性。
这些扩展取代了Log4J提供的Spring Boot支持。您应该确保不要在构建中包含org.apache.logging.log4j:log4j-spring-boot模块。

特定于配置文件的配置

<SpringProfile>标签允许您根据活动的Spring配置文件有选择地包含或排除配置部分。配置文件部分在<Configuration>元素中的任何位置都受支持。使用name属性指定哪个配置文件接受配置。<SpringProfile>标签可以包含配置文件名称（例如staging）或配置文件表达式。配置文件表达式允许表达更复杂的配置文件逻辑，例如production & (eu-central | eu-west)。有关更多详细信息，请查看Spring Framework参考指南。以下列表显示了三个示例配置文件

<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>

环境属性查找

如果要在Log4j2配置中引用Spring Environment中的属性，可以使用spring:前缀的查找。如果您想在Log4j2配置中访问application.properties文件中的值，这样做会很有用。

以下示例显示了如何设置名为applicationName的Log4j2属性，该属性从Spring Environment读取spring.application.name

<Properties>
	<Property name="applicationName">${spring:spring.application.name}</Property>
</Properties>
查找键应使用短横线命名法指定（例如my.property-name）。

Log4j2系统属性

Log4j2支持许多系统属性，可用于配置各种项目。例如，log4j2.skipJansi系统属性可用于配置ConsoleAppender是否会在Windows上尝试使用Jansi输出流。

在Log4j2初始化后加载的所有系统属性都可以从Spring Environment中获取。例如，您可以将log4j2.skipJansi=false添加到application.properties文件中，以使ConsoleAppender在Windows上使用Jansi。

只有在系统属性和操作系统环境变量不包含正在加载的值时，才会考虑Spring Environment。
在Log4j2早期初始化期间加载的系统属性无法引用Spring Environment。例如，Log4j2用于允许选择默认Log4j2实现的属性在Spring Environment可用之前就被使用了。