跳到主要内容

日志记录

DeepSeek V3 中英对照 Logging

Spring Boot 除了依赖于 Commons Logging API（通常由 Spring Framework 的 spring-jcl 模块提供）之外，没有强制性的日志依赖。要使用 Logback，你需要在 classpath 中包含它以及 spring-jcl。推荐的方式是通过 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>
xml

Spring Boot 提供了一个 LoggingSystem 抽象层，它会根据类路径的内容尝试配置日志系统。如果 Logback 可用，它将是首选。

如果唯一需要更改的日志配置是设置不同日志记录器的级别，你可以在 application.properties 文件中使用 "logging.level" 前缀来实现，如下例所示：

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

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

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

配置 Logback 进行日志记录​

如果你需要对 Logback 进行超出 application.properties 所能实现的自定义配置，你需要添加一个标准的 Logback 配置文件。你可以在类路径的根目录下添加一个 logback.xml 文件，以便 Logback 能够找到它。如果你想使用 Spring Boot 的 Logback 扩展，你也可以使用 logback-spring.xml。

提示

Logback 文档中有一个专门的部分详细介绍了配置。

Spring Boot 提供了许多可以在你自己的配置中 include 的 logback 配置。这些包含项旨在允许重新应用某些常见的 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>
xml

您的 Logback 配置文件也可以利用由 LoggingSystem 负责为您创建的系统属性：

  • ${PID}: 当前进程的 ID。

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

  • ${LOG_PATH}: 是否在 Boot 的外部配置中设置了 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>
xml

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

logging.file.name=myapplication.log
properties

配置 Log4j 日志记录​

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

Gradle 提供了几种不同的方式来设置 starters。其中一种方式是使用 模块替换。为此，声明对 Log4j 2 starter 的依赖，并告诉 Gradle 任何出现的默认 logging 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")
        }
    }
}
gradle
备注

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

备注

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

使用 YAML 或 JSON 配置 Log4j 2​

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

格式依赖项文件名
YAMLcom.fasterxml.jackson.core:jackson-databind + com.fasterxml.jackson.dataformat:jackson-dataformat-yamllog4j2.yaml + log4j2.yml
JSONcom.fasterxml.jackson.core:jackson-databindlog4j2.json + log4j2.jsn

使用组合配置来配置 Log4j 2​

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