Logging

QWen Max 中英对照 Logging

Spring Boot 除了 Commons Logging API 之外没有强制的日志依赖，而 Commons Logging API 通常由 Spring Framework 的 spring-jcl 模块提供。要使用 Logback，你需要将其和 spring-jcl 添加到 classpath 中。推荐的做法是通过 starters 来实现，因为所有 starters 都依赖于 spring-boot-starter-logging。对于 Web 应用程序，你只需要引入 spring-boot-starter-web，因为它会通过传递依赖自动引入日志 starter。如果你使用 Maven，以下依赖会为你添加日志功能：

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-web</artifactId>
</dependency>

Spring Boot 提供了一个 LoggingSystem 抽象，它会根据 classpath 中的内容尝试配置日志系统。如果 Logback 可用，则优先选择它。

如果要对日志记录进行的唯一更改是设置各个 logger 的级别，你可以通过在 application.properties 中使用 "logging.level" 前缀来实现，如下例所示：

Properties

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

YAML

logging:
  level:
    org.springframework.web: "debug"
    org.hibernate: "error"

你也可以通过使用 logging.file.name 来设置日志写入的文件位置（除了控制台之外）。

要配置日志系统更细粒度的设置，你需要使用该 LoggingSystem 所支持的原生配置格式。默认情况下，Spring Boot 会从该日志系统的默认位置加载原生配置（例如 Logback 的 classpath:logback.xml），但你可以通过 logging.config 属性来指定配置文件的位置。

配置 Logback 进行日志记录

如果你需要对 Logback 进行超出 application.properties 所能实现的自定义配置，就需要添加一个标准的 Logback 配置文件。你可以在 classpath 的根目录下添加一个 logback.xml 文件，供 Logback 查找使用。如果你希望使用 Spring Boot 的 Logback 扩展功能，也可以使用 logback-spring.xml。

提示

Logback 文档中有一个专门章节详细介绍了配置。

Spring Boot 提供了多个 logback 配置，可以被 included 到你自己的配置中。这些 include 的设计目的是允许重新应用某些常见的 Spring Boot 约定。

以下文件位于 org/springframework/boot/logging/logback/ 目录下：

• defaults.xml - 提供转换规则、模式属性和通用的日志记录器配置。

• console-appender.xml - 使用 CONSOLE_LOG_PATTERN 添加一个 ConsoleAppender。

• structured-console-appender.xml - 使用 CONSOLE_LOG_STRUCTURED_FORMAT 中的结构化日志格式添加一个 ConsoleAppender。

• file-appender.xml - 使用 FILE_LOG_PATTERN 和 ROLLING_FILE_NAME_PATTERN 并配合适当的设置，添加一个 RollingFileAppender。

• structured-file-appender.xml - 使用 ROLLING_FILE_NAME_PATTERN 和 FILE_LOG_STRUCTURED_FORMAT 中的结构化日志格式，添加一个 RollingFileAppender。

此外，还提供了一个旧版的 base.xml 文件，以兼容早期版本的 Spring Boot。

一个典型的自定义 logback.xml 文件大致如下所示：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
	<include resource="org/springframework/boot/logging/logback/defaults.xml"/>
	<include resource="org/springframework/boot/logging/logback/console-appender.xml" />
	<root level="INFO">
		<appender-ref ref="CONSOLE" />
	</root>
	<logger name="org.springframework.web" level="DEBUG"/>
</configuration>

你的 logback 配置文件也可以使用 LoggingSystem 为你创建的系统属性：

• ${PID}：当前进程 ID。

• ${LOG_FILE}：Boot 的外部配置中是否设置了 logging.file.name。

• ${LOG_PATH}：Boot 的 external configuration 中是否设置了 logging.file.path（表示日志文件所在目录）。

• ${LOG_EXCEPTION_CONVERSION_WORD}：Boot 的外部配置中是否设置了 logging.exception-conversion-word。

• ${ROLLING_FILE_NAME_PATTERN}：Boot 的外部配置中是否设置了 logging.pattern.rolling-file-name。

Spring Boot 还通过使用自定义的 Logback 转换器，在控制台（但不在日志文件中）提供了一些漂亮的 ANSI 彩色终端输出。示例可参见 defaults.xml 配置中的 CONSOLE_LOG_PATTERN。

如果 Groovy 在 classpath 中，你也应该能够使用 logback.groovy 来配置 Logback。如果存在该文件，此设置将被优先使用。

备注

Spring 扩展不支持 Groovy 配置。任何 logback-spring.groovy 文件都不会被检测到。

配置 Logback 仅输出到文件

如果你想禁用控制台日志记录，仅将输出写入文件，则需要一个自定义的 logback-spring.xml，该文件导入 file-appender.xml 但不导入 console-appender.xml，如下例所示：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
	<include resource="org/springframework/boot/logging/logback/defaults.xml" />
	<property name="LOG_FILE" value="${LOG_FILE:-${LOG_PATH:-${LOG_TEMP:-${java.io.tmpdir:-/tmp}}/}spring.log}"/>
	<include resource="org/springframework/boot/logging/logback/file-appender.xml" />
	<root level="INFO">
		<appender-ref ref="FILE" />
	</root>
</configuration>

你还需要在 application.properties 或 application.yaml 中添加 logging.file.name，如下例所示：

Properties

logging.file.name=myapplication.log

YAML

logging:
  file:
    name: "myapplication.log"

配置 Log4j 用于日志记录

如果 Log4j 2 在 classpath 中，Spring Boot 支持使用 Log4j 2 进行日志配置。如果你使用 starters 来组装依赖项，则必须排除 Logback，然后改为包含 Log4j 2。如果你不使用 starters，则除了 Log4j 2 之外，还需要提供（至少）spring-jcl。

推荐的路径是通过 starters，即使它需要一些调整。以下示例展示了如何在 Maven 中设置 starters：

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter</artifactId>
	<exclusions>
		<exclusion>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-logging</artifactId>
		</exclusion>
	</exclusions>
</dependency>
<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-log4j2</artifactId>
</dependency>

Gradle 提供了几种不同的方式来设置 starters。其中一种方法是使用 module replacement。为此，声明对 Log4j 2 starter 的依赖，并告诉 Gradle 将所有默认日志 starter 的出现替换为 Log4j 2 starter，如下例所示：

dependencies {
	implementation "org.springframework.boot:spring-boot-starter-log4j2"
	modules {
		module("org.springframework.boot:spring-boot-starter-logging") {
			replacedBy("org.springframework.boot:spring-boot-starter-log4j2", "Use Log4j2 instead of Logback")
		}
	}
}

备注

Log4j starters 会将常见的日志记录依赖项（例如让 Tomcat 使用 java.util.logging，但使用 Log4j 2 配置输出）集中在一起。

备注

为确保使用 java.util.logging 执行的调试日志被路由到 Log4j 2，请通过将系统属性 java.util.logging.manager 设置为 org.apache.logging.log4j.jul.LogManager 来配置其 JDK logging adapter。

使用 YAML 或 JSON 配置 Log4j 2

除了默认的 XML 配置格式外，Log4j 2 还支持 YAML 和 JSON 配置文件。要配置 Log4j 2 使用其他配置文件格式，请将相应的依赖项添加到 classpath 中，并将配置文件命名为与所选文件格式相匹配的名称，如下例所示：

格式	依赖项	文件名
YAML	com.fasterxml.jackson.core:jackson-databind + com.fasterxml.jackson.dataformat:jackson-dataformat-yaml	log4j2.yaml + log4j2.yml
JSON	com.fasterxml.jackson.core:jackson-databind	log4j2.json + log4j2.jsn

使用复合配置来配置 Log4j 2

Log4j 2 支持将多个配置文件合并为一个复合配置。要在 Spring Boot 中使用此功能，请通过 logging.log4j2.config.override 配置一个或多个次要配置文件的位置。这些次要配置文件将与主配置合并，无论主配置的来源是 Spring Boot 的默认配置、标准位置（例如 log4j.xml），还是由 logging.config 属性指定的位置。

备注

Log4j2 覆盖配置文件的位置可以加上 optional: 前缀。例如，optional:classpath:log4j2-override.xml 表示仅当该资源存在时才加载 log4j2-override.xml。