logback 速查上手-平芜编程栈

下面给出一份“logback 速查手册”，从“零配置能跑”到“线上调优”一条线捋清，复制即可用。

一、logback 是什么

作者：log4j 创始人 Ceki Gülcü 的“亲儿子”，SLF4J 默认实现。
特点：速度更快、内存占用更低、XML/Groovy 双配置、SiftingAppender（多租户/多文件自动分离）、自动热加载。

二、零依赖就能跑（Spring Boot 已内置）

<!-- 实际不用再引，spring-boot-starter-web 已传递 --> <dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-classic</artifactId> </dependency>

代码里：

private static final Logger log = LoggerFactory.getLogger(UserService.class); log.info("order {} paid", orderId);

三、核心三件套

Logger（写日志） → Appender（写到哪） → Encoder/Layout（怎么格式化）

四、最常用配置文件（src/main/resources/logback-spring.xml，SpringBoot 专用）

<?xml version="1.0" encoding="UTF-8"?> <configuration scan="true" scanPeriod="30 seconds"> <!-- 30s热加载 --> <springProfile name="dev,test"> <!-- 开发/测试环境彩色控制台 --> <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"> <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder"> <pattern>%cyan(%d{HH:mm:ss.SSS}) %highlight(%-5level) %magenta([%thread]) %yellow(%logger{36}:%line) - %msg%n</pattern> <charset>UTF-8</charset> </encoder> </appender> <root level="INFO"> <appender-ref ref="CONSOLE"/> </root> </springProfile> <springProfile name="prod"> <!-- 生产只按大小/日期滚动文件 --> <property name="LOG_HOME" value="/var/log/app"/> <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>${LOG_HOME}/business.log</file> <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy"> <fileNamePattern>${LOG_HOME}/business.%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern> <maxFileSize>200MB</maxFileSize> <maxHistory>30</maxHistory> <totalSizeCap>20GB</totalSizeCap> </rollingPolicy> <encoder> <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36}:%line - %msg%n</pattern> <charset>UTF-8</charset> </encoder> </appender> <!-- 异步提升性能，丢日志<0.01%可接受 --> <appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender"> <appender-ref ref="FILE"/> <queueSize>2048</queueSize> <discardingThreshold>0</discardingThreshold> <includeCallerData>false</includeCallerData> </appender> <root level="INFO"> <appender-ref ref="ASYNC"/> </root> </springProfile> <!-- 单独给 error 再写一份，方便告警 --> <appender name="ERROR" class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>${LOG_HOME:-./logs}/error.log</file> <filter class="ch.qos.logback.classic.filter.LevelFilter"> <level>ERROR</level> <onMatch>ACCEPT</onMatch> <onMismatch>DENY</onMismatch> </filter> <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> <fileNamePattern>${LOG_HOME:-./logs}/error.%d{yyyy-MM-dd}.log.gz</fileNamePattern> <maxHistory>15</maxHistory> </rollingPolicy> <encoder> <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %logger{36}:%line - %msg%n</pattern> </encoder> </appender> <root level="INFO"> <appender-ref ref="ERROR"/> </root> </configuration>

要点

文件名必须是 logback-spring.xml 才能用 <springProfile> 动态区分环境，否则启动报错。
scan="true" 修改配置后 30 秒自动生效，无需重启。
AsyncAppender 队列满时会丢弃 TRACE/DEBUG，INFO 以上不丢（discardingThreshold=0）。

五、多租户/多文件自动分离（SiftingAppender 实战）

<appender name="SIFT" class="ch.qos.logback.classic.sift.SiftingAppender"> <discriminator> <key>tenantId</key> <defaultValue>default</defaultValue> </discriminator> <sift> <appender class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>/var/log/app/${tenantId}.log</file> <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> <fileNamePattern>/var/log/app/${tenantId}.%d{yyyy-MM-dd}.log.gz</fileNamePattern> <maxHistory>15</maxHistory> </rollingPolicy> <encoder> <pattern>%d{HH:mm:ss.SSS} [%thread] %level %logger{36} - %msg%n</pattern> </encoder> </appender> </sift> </appender>

代码里放 discriminator：

MDC.put("tenantId", TenantContext.get());

即可按租户自动拆文件，再也不用 if-else 新建 logger。

六、线上调优 checklist

关闭 debug 级别：<logger name="com.alibaba.nacos" level="WARN"/>
关闭 includeCallerData（AsyncAppender 里拿行号会慢 5~10 倍）。
使用 SizeAndTimeBasedRollingPolicy 而非 FixedWindowRollingPolicy，大并发下减少重命名竞争。
磁盘独立：日志盘与业务盘分离，避免 java.io.IOException: No space left on device 把应用拖死。
监控：

文件句柄数 /proc/sys/fs/file-max
日志写入延迟：appender.getQueueSize() / appender.getDiscardingCount()
接入 Prometheus：通过 logback-metrics 暴露 logback_events_total{level="error"} 做告警。

七、常见坑

现象	原因	快速 fix
修改 logback.xml 不生效	文件名写成 logback.xml 却被 spring 提前加载	改名 logback-spring.xml
控制台彩色失效	Windows 老版本 ANSI 不支持	加 jansi 依赖或关闭彩色
启动报 “no applicable action for [springProfile]”	用了普通 logback.xml	换 logback-spring.xml
日志文件中文乱码	没有 <charset>UTF-8</charset>	全部 encoder 加 charset