Spring Boot Logging中文文档

本文为官方文档直译版本。原文链接

引言

Spring Boot 将 Commons Logging 用于所有内部日志记录，但保留底层日志实现的开放性。为 Java Util Logging、Log4j2 和 Logback 提供了默认配置。在每种情况下，日志记录器都预先配置为使用控制台输出，也可选择文件输出。
默认情况下，如果使用 “Starters”，Logback 将用于日志记录。还包括适当的 Logback 路由，以确保使用 Java Util Logging、Commons Logging、Log4J 或 SLF4J 的依赖库都能正常工作。

有很多适用于 Java 的日志框架。如果上述列表看起来很混乱，请不要担心。一般来说，您不需要更改日志记录依赖关系，Spring Boot 的默认设置就可以正常工作。

将应用程序部署到 servlet 容器或应用程序服务器时，使用 Java Util Logging API 执行的日志记录不会被路由到应用程序的日志中。这样，容器或部署到容器中的其他应用程序执行的日志记录就不会出现在应用程序的日志中。

日志格式

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

2023-11-23T13:39:52.622Z  INFO 35705 --- [myapp] [           main] o.s.b.d.f.logexample.MyApplication       : Starting MyApplication using Java 17.0.9 with PID 35705 (/opt/apps/myapp.jar started by myuser in /opt/apps/)
2023-11-23T13:39:52.628Z  INFO 35705 --- [myapp] [           main] o.s.b.d.f.logexample.MyApplication       : No active profile set, falling back to 1 default profile: "default"
2023-11-23T13:39:53.900Z  INFO 35705 --- [myapp] [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port 8080 (http)
2023-11-23T13:39:53.923Z  INFO 35705 --- [myapp] [           main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2023-11-23T13:39:53.924Z  INFO 35705 --- [myapp] [           main] o.apache.catalina.core.StandardEngine    : Starting Servlet engine: [Apache Tomcat/10.1.16]
2023-11-23T13:39:54.048Z  INFO 35705 --- [myapp] [           main] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2023-11-23T13:39:54.052Z  INFO 35705 --- [myapp] [           main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 1345 ms
2023-11-23T13:39:54.538Z  INFO 35705 --- [myapp] [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port 8080 (http) with context path ''
2023-11-23T13:39:54.548Z  INFO 35705 --- [myapp] [           main] o.s.b.d.f.logexample.MyApplication       : Started MyApplication in 2.545 seconds (process running for 2.907)

输出以下项目：

• 日期和时间：毫秒级精度，易于排序。
• 日志级别 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 标志启动应用程序，从而启用 "debug "模式。

java -jar myapp.jar --debug

您也可以在application.properties中指定 debug=true。

启用调试模式后，选定的核心日志记录器（嵌入式容器、Hibernate 和 Spring Boot）将被配置为输出更多信息。启用调试模式不会将应用程序配置为以 DEBUG 级别记录所有信息。
另外，你也可以通过使用 --trace 标志（或在 application.properties 中使用 trace=true）启动应用程序来启用 "trace "模式。这样就能对选定的核心日志记录器（嵌入式容器、Hibernate 模式生成和整个 Spring 组合）进行跟踪记录。

彩色输出

如果您的终端支持 ANSI，则会使用彩色输出来帮助阅读。您可以将 spring.output.ansi.enabled 设置为支持的值，以覆盖自动检测功能。
颜色编码通过 %clr 转换字进行配置。在最简单的形式下，转换器根据日志级别对输出进行着色，如下例所示：

%clr(%5p)

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

Level	Color
FATAL	Red
ERROR	Red
WARN	Yellow
INFO	Green
DEBUG	Green
TRACE	Green

或者，您也可以将颜色或样式作为转换的一个选项来指定应使用的颜色或样式。例如，要使文字变为黄色，请使用以下设置：

%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 属性（例如，在应用程序属性中）。
下表显示了如何同时使用 logging.* 属性：

logging.file.name	logging.file.path	例子	描述
(none)	(none)
仅在控制台进行日志记录。
Specific file	(none)	my.log	写入指定的日志文件。文件名可以是确切位置，也可以是当前目录的相对位置。
(none)	Specific directory	/var/log	将 spring.log 写入指定目录。名称可以是确切的位置，也可以是相对于当前目录的位置。

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

日志属性独立于实际的日志基础架构。因此，特定的配置键（如 Logback 的 logback.configurationFile）并不由 spring Boot 管理。

文件轮转

如果您使用的是 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）。

日志级别

通过使用 logging.level.<logger-name>=<level>，可以在 Spring 环境（例如在 application.properties 中）中设置所有支持的日志系统的日志记录器级别，其中级别为 TRACE、DEBUG、INFO、WARN、ERROR、FATAL 或 OFF 之一。可以使用 logging.level.root 配置根日志记录器。
下面的示例显示了 application.properties 中潜在的日志记录设置：

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 "组来定义该组：

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

定义后，只需一行即可更改组内所有记录仪的级别：

logging:
  level:
    tomcat: "trace"

Spring Boot 包含以下预定义日志组，开箱即可使用：

Name	Loggers
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 提供了上下文选择器，允许在自己的上下文中创建每个日志记录器。您可以使用 logging.register-shutdown-hook 属性禁用关机钩子。将其设置为 false 将禁用注册。您可以在 application.properties 或 application.yaml 文件中设置该属性：

logging:
  register-shutdown-hook: false

自定义日志配置

各种日志系统可通过在类路径中加入相应的库来激活，也可通过在类路径根目录或以下 Spring 环境属性指定的位置提供合适的配置文件来进一步自定义：logging.config。
您可以使用 org.springframework.boot.logging.LoggingSystem 系统属性强制 Spring Boot 使用特定的日志系统。该值应为日志系统实现的全限定类名。您也可以使用 none 的值来完全禁用 Spring Boot 的日志记录配置。

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

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

Logging System	Customization
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 存在已知的类加载问题，在从 “executable.jar” 运行时会造成问题。我们建议您尽可能避免从 “executable.jar” 中运行。

为了帮助定制，其他一些属性也从 Spring Environment 转移到了 System 属性。这样，这些属性就能被日志系统配置使用。例如，在 application.properties 中设置 logging.file.name 或将 LOGGING_FILE_NAME 设置为环境变量，都会导致 LOG_FILE 系统属性被设置。下表描述了传输的属性：

Spring Environment	System Property	描述
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（如果可能，且尚未定义为操作系统环境变量，则为已发现的进程 ID）。

如果使用 Logback，还将传输以下属性：

Spring Environment	System Property	描述
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 中的默认配置：

• Logback
• Log4j 2
• Java Util logging

如果要在日志属性中使用占位符，应使用 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 必须以 kebab-case 指定（如 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>

查找键应使用 kebab-case （如 my.property-name）。

Log4j2 系统属性

Log4j2 支持许多系统属性，可用于配置各种项目。例如，log4j2.skipJansi 系统属性可用于配置 ConsoleAppender 是否会尝试在 Windows 上使用 Jansi 输出流。
在 Log4j2 初始化后加载的所有系统属性都可以从 Spring Environment 中获取。例如，您可以在application.properties 文件中添加 log4j2.skipJansi=false，让 ConsoleAppender 在 Windows 上使用 Jansi。

只有当系统属性和操作系统环境变量不包含正在加载的值时，才会考虑 Spring Environment。

在早期 Log4j2 初始化过程中加载的系统属性不能引用 Spring Environment。例如，Log4j2 用于允许选择默认 Log4j2 实现的属性会在 Spring 环境可用之前使用。