日志这件事说大不大说小也不小。平时业务跑得好好的谁也不愿意去碰配置文件可一旦线上出了问题翻遍磁盘找不到一个能看的日志文件或者日志文件一夜之间把磁盘撑爆那种感觉就像半夜被人叫起来修水管——手忙脚乱还找不到阀门在哪。logback 搭配 slf4j 这套组合在 Java 生态里算是老资历了几乎每个后端项目都会用到但真正把配置写明白、写扎实的人并不多。大多数人是从别的项目里复制一份logback.xml改改路径就上线了至于里面每个 appender 为什么这么配、rollingPolicy 的参数怎么算、异步日志到底该不该开心里其实没底。这篇内容就是想把这件事从头到尾捋一遍。我会从依赖关系讲起说清楚 slf4j 和 logback 各自扮演什么角色然后把logback.xml里最核心的几个配置块拆开揉碎包括控制台输出、文件输出、滚动策略、异步包装、多环境切换这些实际项目里绕不开的东西。中间会穿插一些我自己踩过的坑比如日志文件按天滚动却死活不生效、异步队列满了丢日志、配置文件加载顺序搞错导致配置被覆盖等等。不管你是刚接触 Java 日志的新手还是想把手头项目的日志配置重新梳理一遍的老手应该都能从里面找到点有用的东西。1. 先把 slf4j 和 logback 的关系理清楚很多人写配置的时候是懵的不知道自己在配的到底是 slf4j 还是 logback看到两个名字摆在一起就头大。其实这两者的分工非常清晰用一句话概括slf4j 是门面logback 是实现。你在代码里写的LoggerFactory.getLogger(xxx.class)来自 slf4j它只负责定义一套统一的日志接口本身不干活真正把日志写到控制台、写到文件、做滚动的是背后绑定的 logback。1.1 门面模式到底解决了什么问题设想一个场景项目早期用的是某个日志框架后来因为性能或者功能原因要换成另一个如果代码里到处直接调用具体框架的 API那换起来就是一场灾难几百个文件挨个改。slf4j 的存在就是为了避免这种绑定。你的业务代码只依赖 slf4j 的接口底层实现可以随时替换只要换掉对应的 jar 包和配置就行代码一行不用动。这个设计在依赖管理上体现得特别明显。一个稍微大一点的项目依赖树里往往同时躺着好几个日志框架的 jar比如某个第三方库自带了自己的日志实现。这时候 slf4j 的桥接机制就派上用场了它能把其他框架的日志调用统一转发到 logback 上避免出现日志打了两遍或者日志不知道跑哪去了的情况。我在排查日志重复输出问题时十有八九就是依赖里混进了多个绑定这个后面会专门讲。1.2 依赖引入时最容易犯的错用 Maven 引入依赖的时候很多人只写一个logback-classic就完事了其实它已经传递依赖了slf4j-api和logback-core理论上够用。但问题在于如果你的项目里还有其他库间接引入了别的日志实现比如老版本的 commons-logging 或者 log4j就可能出现多个绑定共存slf4j 会在启动时打印一句警告然后随机挑一个用。这种随机在开发环境可能看不出来到了生产环境就是定时炸弹。我的习惯是在pom.xml里显式声明slf4j-api和logback-classic的版本并且用exclusions把那些可能捣乱的传递依赖排掉。具体做法是先用mvn dependency:tree把依赖树打出来搜一下log4j、commons-logging、slf4j-log4j12这些关键字看到就排除。这一步花不了几分钟但能省掉后面很多莫名其妙的排查时间。dependency groupIdch.qos.logback/groupId artifactIdlogback-classic/artifactId version1.4.14/version /dependency dependency groupIdorg.slf4j/groupId artifactIdslf4j-api/artifactId version2.0.9/version /dependency注意logback 1.3 及以上版本要求 slf4j 2.0 以上版本对不上会在启动时报NoSuchMethodError别问我怎么知道的。1.3 配置文件到底该放哪logback 启动时会按固定顺序去找配置文件优先级从高到低大致是logback-test.xml测试环境、logback.xml主配置、然后是logback.groovy。它找的位置是 classpath 根目录。这里有个细节很多人忽略如果你用的是 Spring Boot它其实推荐用logback-spring.xml因为这个名字的文件会交给 Spring 的扩展机制处理支持springProfile这类标签而标准的logback.xml加载时机更早拿不到 Spring 的环境信息。我一般会在src/main/resources下放logback-spring.xml测试目录下放一份精简的logback-test.xml这样跑单元测试的时候日志不会刷屏也不会往生产目录写文件。有一次我把两份配置搞混了测试跑完在项目根目录生成了一堆日志文件提交代码的时候差点把它们一起带上去从那以后我养成了在.gitignore里加*.log和logs/的习惯。2. logback.xml 的骨架从 appender 到 logger 的完整链路理解了依赖关系接下来就是配置本身。一份完整的logback.xml大致由三部分组成appender定义日志往哪写、怎么写logger定义哪些包用哪个级别、走哪个 appenderroot是兜底的全局配置。这三者的关系像一条流水线logger 负责拦截和过滤appender 负责落地root 负责收尾。2.1 appender 的三种典型形态实际项目里最常用的 appender 就三类控制台、文件、异步包装。控制台那个叫ConsoleAppender开发环境必备配上带颜色的 pattern 看起来舒服很多。文件那个叫RollingFileAppender是生产环境的主力负责把日志写到磁盘并按规则切割。异步那个叫AsyncAppender它本身不写日志而是包在别的 appender 外面把写操作丢到独立线程里执行避免日志 IO 拖慢业务线程。先看一个最基础的控制台配置appender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n/pattern charsetUTF-8/charset /encoder /appender这个 pattern 里的每个占位符都有讲究。%d是时间格式可以自定义%thread是线程名排查并发问题全靠它%-5level表示日志级别左对齐占 5 个字符这样输出能对齐好看%logger{36}是 logger 名字数字表示最大长度超了会缩写%msg是日志内容%n是换行。我见过有人把%n漏掉结果所有日志挤在一行排查的时候简直要命。文件 appender 的配置要复杂一些核心是滚动策略appender nameFILE classch.qos.logback.core.rolling.RollingFileAppender filelogs/app.log/file rollingPolicy classch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy fileNamePatternlogs/app.%d{yyyy-MM-dd}.%i.log/fileNamePattern maxFileSize100MB/maxFileSize maxHistory30/maxHistory totalSizeCap5GB/totalSizeCap /rollingPolicy encoder pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n/pattern charsetUTF-8/charset /encoder /appender这里SizeAndTimeBasedRollingPolicy是最实用的策略它同时按时间和大小切割。fileNamePattern里的%d和%i必须同时出现%i是当天的文件序号从 0 开始。maxFileSize是单个文件的上限maxHistory是保留多少天的历史totalSizeCap是所有日志文件的总大小上限超了会从最老的开始删。这几个参数配合起来才能既保证日志够用又不至于把磁盘吃光。2.2 logger 的继承与级别控制logger 是有继承关系的名字用点号分隔com.example.service是com.example的子 logger会继承父级的级别和 appender。这个机制很实用你可以给整个com.example设成 INFO然后单独把某个特别吵的包设成 WARN把它的日志压下去。logger namecom.example.dao levelDEBUG additivityfalse appender-ref refFILE/ /logger logger nameorg.springframework levelWARN/additivity这个属性值得单独说。它默认是 true意思是这个 logger 处理完日志后还会把事件往父 logger 传父 logger 的 appender 也会再输出一遍。如果你给子 logger 配了 appender 又没关掉 additivity就会出现同一条日志打两遍的情况。我排查过好几次日志重复的问题最后都是这个属性没设成 false 导致的。2.3 root 的兜底作用root是 logger 树的根所有没被具体 logger 匹配到的日志都会走到这里。它必须配一个级别通常设成 INFO然后挂上需要的 appender。root levelINFO appender-ref refCONSOLE/ appender-ref refFILE/ /root有个常见的误区是把 root 的级别设成 DEBUG想着多打点日志总没坏处。实际上 DEBUG 级别在框架内部会产生海量输出尤其是 Spring 和 MyBatis 这类框架一个请求能刷出几百行磁盘很快就满了而且真正有用的业务日志被淹没在里面排查效率反而下降。我的做法是 root 保持 INFO需要调试的特定包单独开 DEBUG用完就关。3. 滚动策略的参数怎么算才不踩坑滚动策略是日志配置里最容易出问题的地方参数设得不对要么日志不滚动、单文件无限增长要么滚动太频繁、产生一堆碎文件要么历史清理不生效、磁盘被慢慢填满。这一节把几个关键参数的计算逻辑讲透。3.1 maxFileSize 与 totalSizeCap 的配合maxFileSize决定单个文件多大时触发切割totalSizeCap决定所有日志文件加起来最多占多少空间。这两个参数必须一起考虑。假设你设maxFileSize为 100MBmaxHistory为 30 天那么理论上最多可能占用 30 天乘以每天的文件数乘以 100MB。如果某天日志量特别大一天产生 50 个文件那就是 5GB30 天下来就是 150GB远超预期。totalSizeCap就是用来兜底的它会在超过上限时从最旧的文件开始删除不管有没有到maxHistory的天数。我一般会先估算日均日志量比如每天 2GB保留 7 天就是 14GB那totalSizeCap设成 15GB 左右比较稳妥。这个值不要设得刚好等于理论值留一点余量因为清理是异步的可能短时间内会略微超出。参数作用常见取值注意事项maxFileSize单文件大小上限50MB~200MB太小产生碎文件太大单文件打开慢maxHistory保留天数7~30 天按 fileNamePattern 里的时间粒度算totalSizeCap总空间上限按磁盘余量估算必须大于 maxFileSize否则不生效cleanHistoryOnStart启动时清理true配合 totalSizeCap 使用更彻底3.2 按天滚动不生效的排查思路这是被问得最多的问题之一明明配了按天滚动为什么日志文件还是叫app.log从来没变过原因通常有几个。第一fileNamePattern里没有%d或者%d的格式和file标签对不上。第二用的是TimeBasedRollingPolicy但没配file标签导致当前日志直接写进了带日期的文件里看起来像没滚动。第三应用一直没重启而某些旧版本的滚动依赖 JVM 的定时任务跨天时如果没触发就卡住了。排查的时候我一般先看fileNamePattern和file这两个标签。正确的写法是file指向一个固定的当前文件名比如logs/app.logfileNamePattern指向带日期和序号的归档名比如logs/app.%d{yyyy-MM-dd}.%i.log。这样当前日志始终写在app.log到了切割点才把app.log改名归档同时新建一个app.log继续写。如果file也带了日期那就乱套了。3.3 历史文件清理的隐藏开关maxHistory的清理动作默认是在滚动发生时触发的也就是说如果应用一直不产生新的滚动老文件就不会被删。有些场景下日志量很小几天才滚动一次那清理就会滞后。这时候可以加上cleanHistoryOnStart设为 true让应用启动时先做一次清理。还有一个坑是文件名的解析。logback 清理历史文件时是靠解析fileNamePattern里的日期来识别文件年龄的。如果你的归档文件名格式和 pattern 对不上比如手动改过名字或者用了别的工具重命名logback 就认不出来这些文件会一直留着。我遇到过运维同学为了整理把日志文件批量重命名结果清理机制失效磁盘慢慢被撑满的情况。4. 异步日志性能提升与丢日志的权衡日志写磁盘是 IO 操作同步写的话业务线程要等 IO 完成才能继续高并发场景下这个等待会累积成明显的延迟。异步日志的思路是把写操作丢给一个独立线程业务线程只管把日志事件塞进队列就返回响应速度能提升不少。但异步不是银弹队列满了怎么办、应用关闭时队列里的日志怎么处理都是要提前想清楚的。4.1 AsyncAppender 的包装方式异步是通过AsyncAppender包在普通 appender 外面实现的它不改变日志的格式和去向只是改变了写入的时机。appender nameASYNC_FILE classch.qos.logback.classic.AsyncAppender appender-ref refFILE/ queueSize1024/queueSize discardingThreshold0/discardingThreshold neverBlockfalse/neverBlock includeCallerDatafalse/includeCallerData /appenderqueueSize是队列容量默认 256高并发下建议调到 1024 或更大。discardingThreshold默认是队列剩余 20% 时开始丢弃 TRACE、DEBUG、INFO 级别的日志只保留 WARN 和 ERROR。设成 0 表示不丢弃任何级别但这样队列满了就会阻塞业务线程。neverBlock设为 true 时队列满了直接丢日志不阻塞设为 false 则阻塞等待。includeCallerData控制是否记录调用方的类名行号开启后性能会下降一般关掉。这几个参数的取舍本质上是性能和完整性的权衡。我的经验是核心交易链路用neverBlockfalse加discardingThreshold0宁可慢一点也不能丢日志普通业务日志用默认的丢弃策略队列满了丢点 INFO 无所谓保住 WARN 和 ERROR 就行。4.2 应用关闭时日志丢失的处理异步日志最隐蔽的坑在应用关闭的时候。业务线程把日志塞进队列就返回了如果此时 JVM 直接退出队列里还没写盘的日志就丢了。logback 提供了stop机制在上下文关闭时会尝试把队列里的日志刷完但前提是关闭流程被正确触发。在 Spring Boot 里可以通过配置logging.register-shutdown-hooktrue让 logback 注册一个 JVM 关闭钩子确保退出前刷盘。如果是传统 Web 应用要在ServletContextListener的contextDestroyed里手动调用LoggerContext的stop方法。我见过有项目因为没做这一步每次发布重启都会丢掉最后几秒的日志偏偏那几秒往往是最关键的。提示异步日志的队列是内存中的进程被强制杀掉比如 kill -9时无论如何都救不回来所以对日志完整性要求极高的场景关键日志建议单独走同步 appender。4.3 异步与同步混用的实践实际项目里我一般不会把所有日志都异步化而是分两条线一条同步的文件 appender 专门接 ERROR 级别保证错误日志一定落盘另一条异步的接 INFO 及以下追求吞吐。这样既保证了关键信息的可靠性又兼顾了普通日志的性能。配置上可以用LevelFilter或者ThresholdFilter来做分流。ThresholdFilter比较简单设个level就行低于这个级别的直接拒绝。LevelFilter更灵活可以指定某个级别匹配还是拒绝。分流之后logger 里挂两个 appender-ref各管各的互不干扰。5. 多环境配置与动态调整的实用套路一个项目通常要在开发、测试、生产几套环境跑每套环境的日志需求不一样开发要详细、要输出到控制台测试要适中生产要精简、要滚动、要控制总量。如果每次部署都改配置文件迟早会出错。合理的做法是用 profile 或者外部化配置来区分。5.1 用 springProfile 做环境隔离如果用的是logback-spring.xml可以直接用springProfile标签按环境切换配置块springProfile namedev root levelDEBUG appender-ref refCONSOLE/ /root /springProfile springProfile nameprod root levelINFO appender-ref refASYNC_FILE/ /root /springProfile这样同一份配置文件在不同环境下表现不同不用维护多份。注意springProfile只在logback-spring.xml里有效标准的logback.xml不认这个标签写了也会被忽略。这个细节我踩过当时把文件命名搞错profile 死活不生效查了半天才发现是文件名的问题。5.2 外部化配置覆盖内部默认值生产环境的日志路径、级别这些最好能从外部传入而不是写死在 jar 包里。logback 支持用${}占位符引用系统属性或环境变量file${LOG_PATH:-logs}/app.log/file root level${LOG_LEVEL:-INFO}:-后面是默认值外部没传的时候用这个。启动时通过-DLOG_PATH/data/logs -DLOG_LEVELWARN就能覆盖。这样做的好处是同一个包在不同机器上部署不用重新打包改启动参数就行。不过要注意占位符的解析发生在配置加载阶段如果引用的属性不存在又没有默认值logback 会报错并可能回退到默认配置表现就是配置没生效。5.3 运行期动态调整级别有时候线上出了问题需要临时把某个包的日志级别调成 DEBUG 看看细节但又不想重启应用。logback 提供了JMXConfigurator可以通过 JMX 在运行期修改 logger 级别。配置方式是在logback.xml里加一行jmxConfigurator/然后通过 jconsole 或者 JMX 客户端连上去找到 logback 的 MBean就能动态改级别了。这个功能在排查疑难问题时特别好用改完观察一会儿问题定位了再改回去全程不影响服务。不过要记得在生产环境做好 JMX 的访问控制别让不该连的人连上来。6. 那些年我踩过的日志配置坑配置这东西看文档觉得都懂真上手了才发现处处是坑。这一节挑几个印象深刻的记录下来都是实际项目里遇到过的希望能帮你少走点弯路。6.1 日志重复输出的三种成因日志打两遍是最常见的现象成因主要有三类。第一类是 additivity 没关子 logger 和父 logger 都挂了 appender事件传了两遍。第二类是依赖里混进了多个日志绑定比如同时有logback-classic和slf4j-log4j12slf4j 会警告并随机选一个但某些情况下两个都生效了。第三类是配置了多个 appender-ref 指向同一个 appender或者 appender 被重复定义。排查顺序我一般是先看 logger 的 additivity再看依赖树里有没有多余的绑定最后检查 appender 定义有没有重复。用mvn dependency:tree | grep -i log能快速定位第二类问题。6.2 配置文件加载顺序导致的覆盖logback 找配置文件的顺序是固定的logback-test.xml优先于logback.xml。如果你的测试目录里有一份logback-test.xml打包时不小心带进了生产包那生产环境用的就是测试配置级别、路径全不对。这种问题很隐蔽因为应用能正常启动只是日志行为不符合预期。我的做法是在打包插件里显式排除测试资源或者干脆不用logback-test.xml测试环境也用主配置加 profile 区分。另外如果 classpath 里有多个同名配置文件比如依赖的 jar 里也带了一份加载哪个取决于 classpath 顺序这种更要避免。6.3 编码问题导致的中文乱码日志里的中文变成问号或者乱码通常是编码没统一。encoder里的charset要设成 UTF-8同时确保 JVM 的file.encoding也是 UTF-8。有些老系统默认用 GBK日志文件用 UTF-8 打开就是乱码。更麻烦的是控制台输出Windows 的 cmd 默认代码页是 GBK即使日志本身是 UTF-8显示出来也是乱的这时候要么改控制台编码要么用支持 UTF-8 的终端。我在一个跨平台项目里遇到过这个问题开发同学在 Windows 上看到乱码以为是日志配置错了改来改去没效果最后发现是终端编码的问题配置本身没问题。所以排查乱码要先确认是写进去就错了还是读出来才错两者的解决方向完全不同。6.4 磁盘写满的紧急处理日志把磁盘写满是很严重的事故轻则应用报错重则整个机器上的服务都受影响。预防的手段前面讲过就是maxHistory加totalSizeCap双保险。但万一已经写满了紧急处理要快先找到最大的日志文件确认没有保留价值后清空或者删除然后立刻检查滚动策略为什么没生效。清空文件用 app.log而不是rm app.log因为文件被进程打开着直接删虽然能释放空间但进程还在往那个 inode 写磁盘空间不会真正释放直到进程重启。用重定向清空内容则安全得多。这个技巧在紧急情况下能救命值得记牢。7. 一份可以直接抄的完整配置讲了这么多原理和坑最后给一份我目前在用的配置模板覆盖了控制台、同步错误文件、异步业务文件三条线带滚动和清理支持外部化路径和级别。你可以根据自己的项目调整参数。?xml version1.0 encodingUTF-8? configuration property nameLOG_PATH value${LOG_PATH:-logs}/ property nameLOG_LEVEL value${LOG_LEVEL:-INFO}/ property namePATTERN value%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n/ appender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder pattern${PATTERN}/pattern charsetUTF-8/charset /encoder /appender appender nameERROR_FILE classch.qos.logback.core.rolling.RollingFileAppender file${LOG_PATH}/error.log/file filter classch.qos.logback.classic.filter.ThresholdFilter levelERROR/level /filter rollingPolicy classch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy fileNamePattern${LOG_PATH}/error.%d{yyyy-MM-dd}.%i.log/fileNamePattern maxFileSize50MB/maxFileSize maxHistory30/maxHistory totalSizeCap2GB/totalSizeCap /rollingPolicy encoder pattern${PATTERN}/pattern charsetUTF-8/charset /encoder /appender appender nameAPP_FILE classch.qos.logback.core.rolling.RollingFileAppender file${LOG_PATH}/app.log/file rollingPolicy classch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy fileNamePattern${LOG_PATH}/app.%d{yyyy-MM-dd}.%i.log/fileNamePattern maxFileSize100MB/maxFileSize maxHistory15/maxHistory totalSizeCap5GB/totalSizeCap /rollingPolicy encoder pattern${PATTERN}/pattern charsetUTF-8/charset /encoder /appender appender nameASYNC_APP classch.qos.logback.classic.AsyncAppender appender-ref refAPP_FILE/ queueSize1024/queueSize discardingThreshold0/discardingThreshold neverBlockfalse/neverBlock /appender logger namecom.example.dao levelDEBUG additivityfalse appender-ref refASYNC_APP/ /logger root level${LOG_LEVEL} appender-ref refCONSOLE/ appender-ref refERROR_FILE/ appender-ref refASYNC_APP/ /root /configuration这份配置里ERROR 走同步保证不丢普通日志走异步追求性能控制台方便本地开发。LOG_PATH和LOG_LEVEL都能从外部覆盖部署时灵活。参数值是我按中等规模项目估的你实际用的时候记得根据日均日志量重新算一下totalSizeCap别直接照搬。最后分享一个我自己的习惯每次调整日志配置后不要只看应用能不能启动一定要实际触发几条不同级别的日志去磁盘上确认文件生成了、内容对了、滚动策略在跨天或者超大小的时候真的生效了。日志配置的验证成本很低但出问题的代价很高多花五分钟验证能省掉半夜被叫起来排查的麻烦。