SpringBoot日志框架使用详解

原创已于 2025-08-30 21:43:52 修改 · 751 阅读

2 ·

CC 4.0 BY-SA版权

文章标签：

#spring boot #log4j #java

于 2023-02-20 22:21:53 首次发布

本文介绍了日志级别从TRACE到FATAL的顺序，以及如何在SpringBoot中配置日志级别。提到了log4j因其性能问题逐渐被logback和log4j2取代，其中logback是SpringBoot的默认日志框架。文章详细讲解了如何自定义日志级别、输出日志到文件、定制日志格式以及配置日志文件，同时也提及了不同日志框架的配置文件命名规则。

日志级别怎么“过滤”？

几种常见的日志级别由低到高分为：TRACE < DEBUG < INFO < WARN < ERROR < FATAL。
理解法则：项目的生效阈值≥你设置的级别；阈值以下的日志会被“过滤掉”。

若设置为 INFO，则 TRACE/DEBUG 不会输出；INFO/WARN/ERROR/FATAL 会输出。

当前阈值	会看到
TRACE	全部
DEBUG	DEBUG 及以上
INFO	INFO 及以上
WARN	WARN 及以上
ERROR	ERROR、FATAL
FATAL	FATAL

开发环境建议 DEBUG（或针对包粒度下调）；生产环境一般 INFO，临时排障用包级别开到 DEBUG，并设置过期时间或重启回收。

常见的日志框架有 log4j、logback、log4j2。

log4j（1.x）：历史悠久，但已 EOL，安全与性能都不占优，不建议新项目使用。
logback：由 log4j 创始人设计，性能与功能均衡；Spring Boot 默认（spring-boot-starter-logging）。
log4j2：引入 LMAX Disruptor 的异步日志，高吞吐低延迟更突出；生态良好，想极致性能可选。

取舍建议：大多数 Spring Boot 项目直接用 logback 就够了；高吞吐写密集场景可评估迁移 log4j2 的 Async Logger。两者在 Boot 中切换都不复杂。

原则上需要使用 logback，需要添加以下依赖，但是既然是默认的日志框架，当然不用重新引入依赖了。

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

如需 log4j2：排除默认 logging，改用：

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

使用方式

private final Logger logger = LoggerFactory.getLogger(DemoApplicationTests.class);

lombok 简化日志输出：

@Slf4j
class DemoApplicationTests {
    @Test
    public void test(){
        log.debug("输出DEBUG日志.......");
    }
}

实战小建议

参数化日志避免字符串拼接开销：log.debug("userId={}, costMs={}", userId, took);
记录异常用两参形式：log.error("save order failed, id={}", id, e);

如何定制日志级别？

Spring Boot 默认阈值是 INFO，可按 root 与包级分别设置：

logging.level.root=DEBUG
logging.level.com.example.demo=INFO

也可用 application.yml：

logging:
  level:
    root: INFO
    com.example.demo: DEBUG
    org.springframework.jdbc.core: WARN

日志如何输出到文件？

注意：官方文档说 logging.file.path 与 logging.file.name 不能同时配置，否则不生效。

logging.file.path：指定日志文件的目录
logging.file.name：指定文件名（包含路径时优先生效），默认 spring.log

示例：输出到项目路径的 logs 目录：

logging.file.path=./logs

参数化日志建议写法

级别被关闭时不会进行字符串拼接/格式化，减少 CPU/GC；
占位符语法更稳定可检索（便于日志平台解析）

log.debug("userId={}, costMs={}", userId, took);

若参数本身很耗时（序列化/计算），再加一层：

if (log.isDebugEnabled()) { log.debug("payload={}", toJson(req)); }

异常两参形式建议写法

将 Throwable 作为最后一个参数能打印完整栈信息；
同时保留关键业务字段，便于快速定位。

`log.error("save order failed, id={}", id, e);`

如何定制日志格式？

logging.pattern.console：控制台的输出格式
logging.pattern.file：日志文件的输出格式

例如配置如下：

logging.pattern.console=%d{yyyy/MM/dd-HH:mm:ss} [%thread] %-5level %logger- %msg%n
logging.pattern.file=%d{yyyy/MM/dd-HH:mm} [%thread] %-5level %logger- %msg%n

上面的编码含义如下：

%d{HH:mm:ss.SSS} —— 日志输出时间
%thread   ——   线程名（不是“进程名”）
%-5level  ——   日志级别，5个字符左对齐
%logger   ——   日志输出者（类/包）
%msg      ——   日志消息
%n        ——   换行符

如何自定义日志配置？

Spring Boot 官方文档指出，根据不同的日志系统，以下文件名将被自动识别加载：

Logback ：logback-spring.xml, logback-spring.groovy, logback.xml, logback.groovy
Log4j ：log4j-spring.properties, log4j-spring.xml, log4j.properties, log4j.xml
Log4j2 ：log4j2-spring.xml, log4j2.xml
JDK (Java Util Logging) ：logging.properties

推荐优先使用带有 -spring 的文件名。因此在 src/main/resources 创建 logback-spring.xml 即可。

<?xml version="1.0" encoding="UTF-8"?>
<configuration scan="true" scanPeriod="60 seconds" debug="false">
    <!-- 定义日志存放目录 -->
    <property name="logPath" value="logs"/>
    <!-- 日志输出的格式-->
    <property name="PATTERN" value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%t-%L] %-5level %logger{36} %L %M - %msg%xEx%n"/>
    <contextName>logback</contextName>
    <!--输出到控制台 ConsoleAppender-->
    <appender name="consoleLog" class="ch.qos.logback.core.ConsoleAppender">
        <!--展示格式 layout-->
        <layout class="ch.qos.logback.classic.PatternLayout">
            <pattern>${PATTERN}</pattern>
        </layout>
        <!--过滤器，只有过滤到指定级别的日志信息才会输出，如果level为ERROR，那么控制台只会输出
        ERROR日志-->
        <!-- <filter class="ch.qos.logback.classic.filter.ThresholdFilter">-->
        <!-- <level>ERROR</level>-->
        <!-- </filter>-->
    </appender>
    <!--正常的日志文件，输出到文件中-->
    <appender name="fileDEBUGLog" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <!--如果只是想要 Info 级别的日志，只是过滤 info 还是会输出 Error 日志，因为 Error 的级别高，
        所以我们使用下面的策略，可以避免输出 Error 的日志-->
        <filter class="ch.qos.logback.classic.filter.LevelFilter">
            <!--过滤 Error-->
            <level>Error</level>
            <!--匹配到就禁止-->
            <onMatch>DENY</onMatch>
            <!--没有匹配到就允许-->
            <onMismatch>ACCEPT</onMismatch>
        </filter>
        <!--日志名称，如果没有File 属性，那么只会使用FileNamePattern的文件路径规则
        如果同时有<File>和<FileNamePattern>，那么当天日志是<File>，明天会自动把今天
        的日志改名为今天的日期。即，<File> 的日志都是当天的。
        -->
        <File>${logPath}/log_demo.log</File>
        <!--滚动策略，按照时间滚动 TimeBasedRollingPolicy-->
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <!--文件路径,定义了日志的切分方式——把每一天的日志归档到一个文件中,以防止日志填满整个
            磁盘空间-->
            <FileNamePattern>${logPath}/log_demo_%d{yyyy-MM-dd}.log</FileNamePattern>
            <!--只保留最近90天的日志-->
            <maxHistory>90</maxHistory>
            <!--用来指定日志文件的上限大小，那么到了这个值，就会删除旧的日志-->
            <!--<totalSizeCap>1GB</totalSizeCap>-->
        </rollingPolicy>
        <!--日志输出编码格式化-->
        <encoder>
            <charset>UTF-8</charset>
            <pattern>${PATTERN}</pattern>
        </encoder>
    </appender>
    <!--输出ERROR日志到指定的文件中-->
    <appender name="fileErrorLog" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <!--如果只是想要 Error 级别的日志，那么需要过滤一下，默认是 info 级别的，ThresholdFilter-->
        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>Error</level>
        </filter>
        <!--日志名称，如果没有File 属性，那么只会使用FileNamePattern的文件路径规则
        如果同时有<File>和<FileNamePattern>，那么当天日志是<File>，明天会自动把今天
        的日志改名为今天的日期。即，<File> 的日志都是当天的。
        -->
        <File>${logPath}/error.log</File>
        <!--滚动策略，按照时间滚动 TimeBasedRollingPolicy-->
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <!--文件路径,定义了日志的切分方式——把每一天的日志归档到一个文件中,以防止日志填满整个
            磁盘空间-->
            <FileNamePattern>${logPath}/error_%d{yyyy-MM-dd}.log</FileNamePattern>
            <!--只保留最近90天的日志-->
            <maxHistory>90</maxHistory>
            <!--用来指定日志文件的上限大小，那么到了这个值，就会删除旧的日志-->
            <!--<totalSizeCap>1GB</totalSizeCap>-->
        </rollingPolicy>
        <!--日志输出编码格式化-->
        <encoder>
            <charset>UTF-8</charset>
            <pattern>${PATTERN}</pattern>
        </encoder>
    </appender>
    <!--指定最基础的日志输出级别-->
    <root level="DEBUG">
        <!--appender将会添加到这个loger-->
        <appender-ref ref="consoleLog"/>
        <appender-ref ref="fileDEBUGLog"/>
        <appender-ref ref="fileErrorLog"/>
    </root>
    <!-- 定义指定package的日志级别-->
    <logger name="org.springframework" level="DEBUG"></logger>
    <logger name="org.mybatis" level="DEBUG"></logger>
    <logger name="java.sql.Connection" level="DEBUG"></logger>
    <logger name="java.sql.Statement" level="DEBUG"></logger>
    <logger name="java.sql.PreparedStatement" level="DEBUG"></logger>
    <logger name="io.lettuce.*" level="INFO"></logger>
    <logger name="io.netty.*" level="ERROR"></logger>
    <logger name="com.rabbitmq.*" level="DEBUG"></logger>
    <logger name="org.springframework.amqp.*" level="DEBUG"></logger>
    <logger name="org.springframework.scheduling.*" level="DEBUG"></logger>
    <!--定义com.xxx..xx..xx包下的日志信息不上传，直接输出到fileDEBUGLog和fileErrorLog这个两个appender
    中，日志级别为DEBUG-->
    <logger name="com.xxx.xxx.xx" additivity="false" level="DEBUG">
        <appender-ref ref="fileDEBUGLog"/>
        <appender-ref ref="fileErrorLog"/>
    </logger>
</configuration>

当然，如果就不想用 Spring Boot 推荐的名字，想自己定制也行，只需要在配置文件中指定配置文件名即可：

logging.config=classpath:logging-config.xml

常见坑点 & 排障速查

开了 root=DEBUG 结果网卡/磁盘打满：生产环境别全局 DEBUG；按包开、限时开。
日志里到处是字符串拼接：统一改参数化日志，减少无谓 toString()。
单文件越写越大：记得滚动策略 + maxHistory + totalSizeCap。
行号 %L 卡顿：行号要解析堆栈，代价大；生产慎用。
同时配了 logging.file.path 和 logging.file.name：两者互斥，保留一个。
异步日志丢失：logback 的 AsyncAppender 默认在停止时 flush；容器粗暴杀进程可能丢尾巴，优雅停机（TERM）或 neverBlock=true 配合队列冗余。