Logback日志框架配置与最佳实践

10/13/22About 15 min

配置加载顺序

Logback可以通过程序配置，也可以通过XML或者Groovy文件配置。如果之前使用log4j.properties配置，可以通过log4j.properties Translator转换成logback.xml配置。

配置优先级顺序（从高到低）：

通过SPI机制，从classpath的META-INF/services/ch.qos.logback.classic.spi.Configurator（内容为实现类的全限定名）文件中获取Configurator的实现。
尝试查找classpath下的logback-test.xml文件
尝试查找classpath下的logback.xml文件
如果以上均未成功，使用BasicConfigurator作为默认配置，将日志输出到控制台。

说明：DefaultJoranConfigurator是Logback内部使用的默认配置器，不需要通过SPI方式单独提供。

自定义配置文件位置

通过指定系统属性logback.configurationFile的值，可以自定义配置文件的位置。该值可以是一个URL、classpath路径下的资源文件，或者是应用外部的文件。

命令行指定

java -Dlogback.configurationFile=/path/to/config.xml chapters.configuration.MyApp1

程序中指定

import ch.qos.logback.classic.util.ContextInitializer;

public class ServerMain {
    public static void main(String args[]) throws IOException, InterruptedException {
       // 必须在第一次调用LoggerFactory.getLogger()之前设置
       // ContextInitializer.CONFIG_FILE_PROPERTY的值为"logback.configurationFile"
       System.setProperty(ContextInitializer.CONFIG_FILE_PROPERTY, "/path/to/config.xml");
       ...
    }
}

日志等级

Logback支持以下日志等级（从低到高）：

TRACE < DEBUG < INFO < WARN < ERROR

TRACE：最详细的日志信息，通常仅用于开发和调试阶段
DEBUG：调试信息，用于跟踪程序执行流程
INFO：一般信息，记录程序正常运行状态
WARN：警告信息，表示潜在的问题或需要注意的情况
ERROR：错误信息，表示程序发生了错误但仍能继续运行

除了以上基本等级外，Logback还支持ALL（启用所有日志）和OFF（关闭所有日志）两个特殊等级。

日志等级继承规则

Logger通常会被分配一个等级（TRACE, DEBUG, INFO, WARN, ERROR）。如果没有为Logger显式指定等级，那么它会从最近的父级Logger继承等级。

Logger命名的层次结构

Logger命名采用层次化结构，使用点号(.)分隔。例如：

com.nikola 是 com.nikola.service 的父级
com.nikola.service 是 com.nikola.service.UserService 的父级

父级Logger的名称是子Logger名称的前缀，中间以点号分隔。

日志记录选择规则

一次日志记录请求（通过Logger实例调用info、debug等方法）是否会被处理，取决于记录的日志等级是否高于或等于Logger的有效等级。

例如：如果Logger的有效等级是DEBUG，那么：

trace() 方法调用会被忽略
debug()、info()、warn()、error() 方法调用会被处理

示例

假设在com.nikola包下有以下日志记录代码：

Logger logger = LoggerFactory.getLogger("com.nikola");
logger.trace("here is trace");
logger.debug("here is debug");
logger.info("here is info");

如果com.nikola Logger的等级设置为DEBUG，那么只会输出debug和info级别的日志，trace级别的日志会被忽略。

XML配置方式

Logback的XML配置文件是最常用的配置方式，下面是一个完整的logback.xml示例：

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration>
<configuration scan="true" scanPeriod="60 seconds" packagingData="true">
    <!-- 引入Spring Boot默认配置 -->
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
    
    <!-- 定义属性 -->
    <property name="LOG_HOME" value="/logs/be-kami/spring-test"/>
    <property name="LOG_PATTERN" value="%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{15} - %msg%n"/>

    <!-- 控制台输出 -->
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <pattern>%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){yellow} %-5level [%thread] %clr(%logger{15}){blue} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- 文件输出 -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_HOME}/spring-demo.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <!-- 每天滚动生成日志文件 -->
            <fileNamePattern>${LOG_HOME}/spring-demo-%d{yyyy-MM-dd}.%i.log</fileNamePattern>
            <!-- 每个文件最大100MB，保留60天历史记录，总大小不超过10GB -->
            <maxFileSize>100MB</maxFileSize>
            <maxHistory>60</maxHistory>
            <totalSizeCap>10GB</totalSizeCap>
        </rollingPolicy>
        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <pattern>${LOG_PATTERN}</pattern>
        </encoder>
    </appender>

    <!-- 错误日志单独输出 -->
    <appender name="ERROR_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>ERROR</level>
        </filter>
        <file>${LOG_HOME}/spring-demo-error.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOG_HOME}/spring-demo-error-%d{yyyy-MM-dd}.%i.log</fileNamePattern>
            <maxFileSize>100MB</maxFileSize>
            <maxHistory>60</maxHistory>
            <totalSizeCap>5GB</totalSizeCap>
        </rollingPolicy>
        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <pattern>${LOG_PATTERN}</pattern>
        </encoder>
    </appender>

    <!-- 根日志配置 -->
    <root level="info">
        <appender-ref ref="STDOUT"/>
        <appender-ref ref="FILE"/>
        <appender-ref ref="ERROR_FILE"/>
    </root>
    
    <!-- 特定包日志配置 -->
    <logger name="com.nikola" level="debug" additivity="false">
        <appender-ref ref="STDOUT"/>
        <appender-ref ref="FILE"/>
    </logger>
    
    <!-- 第三方框架日志配置 -->
    <logger name="org.springframework" level="warn"/>
    <logger name="org.apache" level="warn"/>
</configuration>

配置文件语法

Logback的XML配置文件采用自定义语法，不提供DTD或Schema规范，但官方文档提供了详细的配置说明。配置文件最外层为configuration标签，内部包含：

0或多个appender标签
0或多个logger标签
最多一个root标签

从0.9.17版本之后，标签不再区分大小写（但XML标签的开闭必须匹配）。

配置文件基本结构：

<configuration>
    <!-- 属性定义 -->
    <property name="propertyName" value="propertyValue"/>
    
    <!-- Appender配置 -->
    <appender name="appenderName" class="appenderClass">
        <!-- Appender特定配置 -->
    </appender>
    
    <!-- Logger配置 -->
    <logger name="loggerName" level="level" additivity="true|false">
        <appender-ref ref="appenderName"/>
    </logger>
    
    <!-- Root Logger配置 -->
    <root level="level">
        <appender-ref ref="appenderName"/>
    </root>
</configuration>

configuration标签

configuration是配置文件的根标签，支持以下属性：

属性	值	描述
scan	true/false	是否扫描配置文件变更，默认关闭
scanPeriod	时间值（如：milliseconds, seconds, minutes, hours）	配置文件扫描周期，默认1分钟，示例：`30 seconds`、`5 minutes`
packagingData	true/false	是否在日志中包含包信息，默认关闭

说明

如果不设置扫描时间单位，默认使用milliseconds
使用scan属性会启用ReconfigureOnChangeTask线程，检测配置文件变更
如果配置文件包含XML语法错误，会自动回退到上一次有效的配置
启用packagingData后，当程序出错时会打印报错堆栈所在的包信息

shutdownHook标签

shutdownHook用于安装JVM关机钩子，以便在JVM关闭时正确关闭Logback并释放相关资源。

默认关机钩子

DefaultShutdownHook是默认的关机钩子，会在JVM停止时延迟（默认0毫秒）后停止Logback上下文，允许后台运行的日志文件压缩任务完成（最多30秒）。

<configuration>
    <shutdownHook class="ch.qos.logback.core.hook.DefaultShutdownHook"/>
</configuration>

Web应用中的特殊处理

在Web应用中，Logback会自动添加WebShutdownHook，无需额外配置<shutdownHook/>。

LogbackServletContainerInitializer实现了ServletContainerInitializer接口，会在Web应用启动时实例化LogbackServletContextListener，该监听器会在Web应用停止或重启时停止日志上下文。

禁用自动关机钩子

通过设置logbackDisableServletContainerInitializer属性为true，可以禁用LogbackServletContextListener的自动装载：

<web-app>
    <context-param>
        <param-name>logbackDisableServletContainerInitializer</param-name>
        <param-value>true</param-value>
    </context-param>
    <!-- 其他配置 -->
</web-app>

contextName标签

contextName用于配置日志上下文的名称，每个Logback配置都有一个对应的上下文名称。如果不配置，默认名称为default。

作用

上下文名称常用于区分不同的应用环境（如开发、测试、生产），可以在日志格式中使用%contextName占位符将其打印到日志中。

<configuration>
  <contextName>myAppName</contextName>
  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%d %contextName [%t] %level %logger{36} - %msg%n</pattern>
    </encoder>
  </appender>

  <root level="debug">
    <appender-ref ref="STDOUT" />
  </root>
</configuration>

在上述示例中，日志输出将包含myAppName上下文名称，便于在多应用环境中区分日志来源。

logger标签配置

logger用于配置特定包或类的日志记录行为，必须包含name属性，可选包含level和additivity属性。

属性	值	含义
name	字符串	logger命名，通常是包名或类名，参考命名的层次结构
level	TRACE, DEBUG, INFO, WARN, ERROR, ALL, OFF, INHERITED, NULL（大小写均可）	当前logger的日志等级
additivity	true/false（默认true）	是否继承父logger的appender配置

关键说明

日志级别INHERITED或其同义词NULL，将强制logger的级别从层次结构中更高的地方继承过来
additivity属性控制是否将日志记录传递给父logger的appender，设置为false可以避免日志重复输出
logger标签可包含0个或多个appender-ref子标签，引用的每个appender都会被添加到该logger中

<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d [%t] %level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
    
    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        <file>application.log</file>
        <encoder>
            <pattern>%d [%t] %level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
    
    <!-- 配置com.example包的日志级别为DEBUG，仅输出到CONSOLE -->
    <logger name="com.example" level="DEBUG" additivity="false">
        <appender-ref ref="CONSOLE" />
    </logger>
    
    <!-- 配置com.example.service包的日志级别为INFO，同时输出到CONSOLE和FILE -->
    <logger name="com.example.service" level="INFO">
        <appender-ref ref="FILE" />
    </logger>
</configuration>

root标签配置

root是所有logger的根节点，代表全局日志配置，只有一个level属性。

属性说明

属性	值	含义
level	TRACE, DEBUG, INFO, WARN, ERROR, ALL, OFF（大小写均可）	全局日志级别，不能为`INHERITED`或`NULL`

结构说明

和logger一样，root也包含0或多个appender-ref子元素标签
所有未明确配置的logger都会继承root的日志级别和appender配置

<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d [%t] %level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
    
    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        <file>application.log</file>
        <encoder>
            <pattern>%d [%t] %level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
    
    <!-- 配置全局日志级别为INFO，同时输出到CONSOLE和FILE -->
    <root level="INFO">
        <appender-ref ref="CONSOLE" />
        <appender-ref ref="FILE" />
    </root>
</configuration>

appender标签配置

appender负责日志输出的具体实现，定义了日志如何、在哪里输出。每个appender必须包含name和class属性。

基本属性

属性	值	含义
name	字符串	appender的唯一标识，用于在logger或root中引用
class	类的全限定名	appender的实现类，用于实例化该类

子标签结构

appender可以包含以下子标签：

最多一个layout或encoder标签（现代Logback推荐使用encoder）
0或多个filter标签（用于过滤日志）
其他特定appender类型的配置标签

Layout与Encoder的区别

Layout：仅负责将日志事件转换为字符串格式
Encoder：不仅负责格式化日志，还负责将日志写入输出目标（如文件、控制台），是Layout的增强版
现代推荐：使用Encoder，特别是PatternLayoutEncoder，它内部集成了PatternLayout

常用Appender类型

1. ConsoleAppender（控制台输出）

<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
        <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n</pattern>
    </encoder>
</appender>

2. FileAppender（文件输出）

<appender name="FILE" class="ch.qos.logback.core.FileAppender">
    <file>logs/application.log</file>
    <encoder>
        <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n</pattern>
    </encoder>
    <!-- 追加模式，默认为true -->
    <append>true</append>
</appender>

3. RollingFileAppender（滚动文件输出）

<appender name="ROLLING_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>logs/application.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
        <!-- 按天滚动，保留30天 -->
        <fileNamePattern>logs/application.%d{yyyy-MM-dd}.log</fileNamePattern>
        <maxHistory>30</maxHistory>
    </rollingPolicy>
    <encoder>
        <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n</pattern>
    </encoder>
</appender>

4. AsyncAppender（异步输出）

<appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
    <!-- 引用其他appender -->
    <appender-ref ref="ROLLING_FILE" />
    <!-- 队列大小 -->
    <queueSize>512</queueSize>
    <!-- 当队列满时是否阻塞，默认为true -->
    <neverBlock>false</neverBlock>
</appender>

日志记录到多个Appender

将日志同时输出到多个目标非常简单，只需定义多个appender，然后在logger或root中引用它们即可。

示例：同时输出到控制台和文件

<configuration>
  <appender name="FILE" class="ch.qos.logback.core.FileAppender">
    <file>myApp.log</file>
    <encoder>
      <pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</pattern>
    </encoder>
  </appender>

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%msg%n</pattern>
    </encoder>
  </appender>

  <root level="debug">
    <appender-ref ref="FILE" /> <!-- 输出到文件 -->
    <appender-ref ref="STDOUT" /> <!-- 同时输出到控制台 -->
  </root>
</configuration>

工作原理

定义了两个appender：
- FILE：将日志输出到myApp.log文件
- STDOUT：将日志输出到控制台（仅显示日志消息内容）
在root中同时引用这两个appender，因此所有日志事件都会被同时发送到这两个输出目标

应用场景

开发环境：同时输出到控制台（方便实时查看）和文件（方便后续分析）
生产环境：同时输出到本地文件和远程日志收集系统
错误处理：将ERROR级别日志单独输出到告警文件

默认类映射

Logback的配置解析器（Joran）提供了默认类映射机制，允许在配置文件中省略某些组件的完整类名，简化配置。
Logback的JoranConfigurator类在addDefaultNestedComponentRegistryRules方法中定义了一系列默认映射规则，将父组件和子组件名称映射到对应的实现类。

常用默认映射示例

PatternLayoutEncoder内部默认使用PatternLayout

<!-- 完整配置 -->
<encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
    <layout class="ch.qos.logback.classic.PatternLayout">
        <pattern>%d [%t] %level %logger - %msg%n</pattern>
    </layout>
</encoder>

<!-- 使用默认映射的简化配置 -->
<encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
    <pattern>%d [%t] %level %logger - %msg%n</pattern>
</encoder>

RollingFileAppender默认使用TimeBasedRollingPolicy

<!-- 完整配置 -->
<appender name="ROLLING" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
        <fileNamePattern>logs/app.%d{yyyy-MM-dd}.log</fileNamePattern>
    </rollingPolicy>
</appender>

<!-- 使用默认映射的简化配置 (某些版本支持) -->
<appender name="ROLLING" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <fileNamePattern>logs/app.%d{yyyy-MM-dd}.log</fileNamePattern>
</appender>

注意事项

默认映射规则可能随Logback版本变化，建议查阅官方文档或源码确认
简化配置提高了可读性，但在复杂场景下使用完整类名更明确和安全

Appender的累加性

默认情况下，Logger的Appender具有累加性（additivity=true），即子Logger会继承父Logger的所有Appender配置，这种机制可能导致日志重复输出。

问题：日志重复输出

当子Logger和父Logger（包括root）都引用了相同的Appender时，日志会被重复输出：

<configuration>
  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
    </encoder>
  </appender>

  <!-- 子Logger配置了STDOUT -->
  <logger name="chapters.configuration">
    <appender-ref ref="STDOUT" />
  </logger>

  <!-- 父Logger(root)也配置了STDOUT -->
  <root level="debug">
    <appender-ref ref="STDOUT" />
  </root>
</configuration>

结果：chapters.configuration包下的日志会被输出两次（一次来自子Logger，一次来自root）

解决方案：利用累加性实现分层日志

我们可以利用Appender的累加性，将不同Logger的日志输出到不同目标：

<configuration>
  <appender name="FILE" class="ch.qos.logback.core.FileAppender">
    <file>myApp.log</file>
    <encoder>
      <pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</pattern>
    </encoder>
  </appender>

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%msg%n</pattern>
    </encoder>
  </appender>

  <!-- chapters.configuration包的日志额外输出到FILE -->
  <logger name="chapters.configuration">
    <appender-ref ref="FILE" />
  </logger>

  <!-- 所有日志输出到STDOUT -->
  <root level="debug">
    <appender-ref ref="STDOUT" />
  </root>
</configuration>

结果：

所有日志通过控制台（STDOUT）打印
chapters.configuration包的日志额外打印到文件（FILE）中

解决方案：禁用累加性避免重复

通过设置additivity="false"可以完全禁用Logger的Appender继承，仅使用当前Logger配置的Appender：

<configuration>
  <appender name="FILE" class="ch.qos.logback.core.FileAppender">
    <file>foo.log</file>
    <encoder>
      <pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</pattern>
    </encoder>
  </appender>

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%msg%n</pattern>
    </encoder>
  </appender>

  <logger name="chapters.configuration.Foo" additivity="false">
    <appender-ref ref="FILE" />
  </logger>

  <root level="debug">
    <appender-ref ref="STDOUT" />
  </root>
</configuration>

禁用累加性示例说明

按照上述配置，chapters.configuration.Foo类的日志只会输出到FILE（文件）中，而不会输出到STDOUT（控制台），即使root配置了STDOUT。

如果希望它同时输出到控制台，只需在其下添加STDOUT的引用：

<logger name="chapters.configuration.Foo" additivity="false">
  <appender-ref ref="FILE" />
  <appender-ref ref="STDOUT" /> <!-- 同时输出到控制台 -->
</logger>

文件引入

Logback支持通过include标签从其他文件引入部分配置，实现配置的模块化和复用。

引入方式

引用本地文件（使用file属性）

<configuration>
  <include file="/path/to/includedConfig.xml"/>
  
  <root level="DEBUG">
    <appender-ref ref="includedConsole" />
  </root>
</configuration>

引用类路径资源（使用resource属性）

<include resource="config/logback-included.xml"/>

引用远程URL（使用url属性）

<include url="http://some.host.com/config/logback.xml"/>

处理引用失败

如果无法找到需要引用的文件，Logback会打印异常信息。通过设置optional="true"可以忽略找不到文件的情况：

<include resource="optional-config.xml" optional="true"/>

被引入文件的格式

被引入的文件必须将配置标签嵌套在included根标签中：

<included>
  <appender name="includedConsole" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%d - %m%n</pattern>
    </encoder>
  </appender>
  
  <logger name="com.example.common" level="INFO"/>
</included>

应用场景：

抽取通用配置（如标准appender、第三方框架日志配置）
区分环境配置（开发、测试、生产）
实现配置的模块化管理

总结

Logback是一个功能强大且灵活的日志框架，通过合理配置可以满足各种复杂的日志需求。本文介绍了Logback的基本概念、配置文件语法、核心组件（Logger、Appender、Layout/Encoder）以及高级特性（Appender累加性、文件引入等）。

在实际应用中，建议根据项目需求选择合适的日志配置策略，遵循以下最佳实践：

使用有意义的Logger名称（通常是包名或类名）
合理设置日志级别，避免过多的调试日志影响性能
采用适当的日志输出策略（控制台、文件、滚动文件等）
使用结构化日志格式，便于日志分析和监控
避免日志重复输出，合理利用additivity属性
实现配置的模块化和复用
考虑生产环境的日志性能和存储需求

上下文监听器（Context Listeners）

LoggerContextListener接口的实现可以监听Logger上下文生命周期的各种事件，如上下文初始化、配置完成、重置等。通过上下文监听器，可以实现对Logback运行时的监控和扩展。

1. JMXConfigurator

作用：允许通过JMX（Java Management Extensions）远程管理和配置Logback。

配置示例：

<configuration>
  <jmxConfigurator />
</configuration>

应用场景：

生产环境中动态调整日志级别
监控日志系统状态
远程管理日志配置

2. LevelChangePropagator

作用：将Logback日志记录器的级别变化传播到java.util.logging（JUL）框架，实现两个日志系统的级别同步。

配置示例：

<configuration debug="true">
  <contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator"/>
  <!-- 其他配置... -->
</configuration>

应用场景：

项目中同时使用Logback和JUL框架时
需要统一管理不同日志框架的日志级别

3. SequenceNumberGenerator

作用：为每个日志事件生成唯一的序列号，该序列号在事件创建时自动填充。

配置示例：

<configuration>
  <sequenceNumberGenerator class="ch.qos.logback.core.spi.BasicSequenceNumberGenerator"/>
  <!-- 其他配置... -->
</configuration>

应用场景：

需要对日志事件进行精确排序
实现日志事件的唯一标识
便于日志分析和关联