logback.xml 常用配置详解

一、参考文档

1. Logback 官方文档
2. Logback 博客文档

二、logback.xml常用配置详解

以下是logback.xml常用节点结构图：

1. 根节点<configuration>

<configuration>是 Logback 配置文件的根节点，包含以下三个重要属性：

• scan：当此属性设置为true时，Logback 将监测配置文件是否发生改变。如果配置文件被修改，它将自动重新加载。默认值为true。
• scanPeriod：设置监测配置文件是否有修改的时间间隔。如果没有指定时间单位，默认单位为毫秒。此属性在scan设置为true时生效。默认的时间间隔为 1 分钟。
• debug：当此属性设置为true时，Logback 将打印其内部日志信息，帮助开发者实时查看 Logback 的运行状态。默认值为false。

示例：

<configuration scan="true" scanPeriod="60 seconds" debug="false">
    <!-- 其他配置省略 -->
</configuration>

2. 子节点<appender>

<appender>是负责将日志事件写入到目的地的组件，它有两个必要属性：name和class。name指定 Appender 的名称，class指定 Appender 的全限定类名。

下文仅简述常见的 Appender，其他更专业的 Appender 使用方式请参考 Logback 官方文档。

2.1 ConsoleAppender：将日志输出到控制台

ConsoleAppender具有以下子节点：

• <encoder>：用于对日志事件进行格式化。
• <target>：指定日志输出的目标流，可以是System.out（默认值）或System.err。

示例： 将DEBUG及以上级别的日志输出到控制台

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</pattern>
        </encoder>
    </appender>

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

2.2 FileAppender：将日志添加到文件

FileAppender具有以下子节点：

• <file>：指定日志写入的文件名，可以是相对路径或绝对路径。如果上级目录不存在，Logback 会自动创建。此节点没有默认值。
• <append>：如果设置为true，日志将被追加到文件末尾；如果设置为false，则在每次启动时清空现有文件。默认值为true。
• <encoder>：用于对日志事件进行格式化。
• <prudent>：如果设置为true，日志会被安全地写入文件，即使有其他FileAppender也在向此文件写入。这会降低效率，默认值为false。

示例： 将DEBUG及以上级别的日志输出到testFile.log

<configuration>
    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        <file>testFile.log</file>
        <append>true</append>
        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="DEBUG">
        <appender-ref ref="FILE" />
    </root>
</configuration>

2.3 RollingFileAppender：滚动记录文件

RollingFileAppender能够先将日志记录到指定文件，当满足特定条件（如时间或文件大小）时，将日志滚动到其他文件。它具有以下子节点：

• <file>：被写入的文件名，可以是相对或绝对路径。如果上级目录不存在会自动创建，没有默认值。
• <append>：如果为true，日志被追加到文件结尾；如果为false，清空现存文件。默认是true。
• <rollingPolicy>：决定RollingFileAppender在发生滚动时的行为，涉及文件的移动和重命名。其class属性定义具体的滚动策略类。
• <triggeringPolicy>：告知RollingFileAppender何时激活滚动。

2.3.1 TimeBasedRollingPolicy：基于时间的滚动策略

这是最常用的滚动策略，它根据时间来制定滚动策略，既负责滚动也负责触发滚动。其class属性值为ch.qos.logback.core.rolling.TimeBasedRollingPolicy。它有以下子节点：

• <fileNamePattern>：必要节点，包含文件名及%d转换符。%d可以包含一个java.text.SimpleDateFormat指定的时间格式，例如%d{yyyy-MM}。如果直接使用%d，默认格式是yyyy-MM-dd。
  • RollingFileAppender的<file>子节点可以省略。如果设置了<file>，当前日志总是记录到<file>指定的文件（活动文件），活动文件的名字不会改变；如果未设置<file>，活动文件的名字会根据<fileNamePattern>的值，每隔一段时间改变一次。斜杠/或反斜杠 \ 会被当作目录分隔符。
• <maxHistory>：可选节点，控制保留的归档文件的最大数量。超出数量的旧文件将被删除。例如，如果设置每月滚动且<maxHistory>为 6，则只保留最近 6 个月的文件，并删除更早的旧文件。在删除旧文件时，为归档而创建的目录也会被删除。

2.3.2 SizeBasedTriggeringPolicy：基于文件大小的触发策略

此策略用于查看当前活动文件的大小，如果超过指定大小，则会通知RollingFileAppender触发当前活动文件滚动。其class属性值为ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy。它只有一个节点：

• <maxFileSize>：这是活动文件的最大大小，默认值是10MB。

2.3.3 FixedWindowRollingPolicy：基于固定窗口的滚动策略

此策略根据固定窗口算法重命名文件。其class属性值为ch.qos.logback.core.rolling.FixedWindowRollingPolicy。它有以下子节点：

• <minIndex>：窗口索引最小值。
• <maxIndex>：窗口索引最大值。当用户指定的窗口过大时，会自动将窗口设置为 12。
• <fileNamePattern>：必须包含%i，例如，假设最小值和最大值分别为 1 和 2，命名模式为mylog%i.log，会产生归档文件mylog1.log和mylog2.log。还可以指定文件压缩选项，例如mylog%i.log.gz或mylog%i.log.zip。

示例： 每天生成一个日志文件，并保存 30 天的日志文件。

<configuration>
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>logFile.%d{yyyy-MM-dd}.log</fileNamePattern>
            <maxHistory>30</maxHistory>
        </rollingPolicy>
        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="DEBUG">
        <appender-ref ref="FILE" />
    </root>
</configuration>

3. 子节点<logger>

<logger>用来设置特定包或类的日志打印级别，以及指定其使用的 Appender。

<logger>元素仅有一个name属性，一个可选的level属性和一个可选的additivity属性。它可以包含零个或多个<appender-ref>元素，表示将 Appender 添加到此 Logger。

• name：用于指定受此 Logger 约束的包或具体的类。
• level：用于设置打印级别，大小写不敏感：TRACE,DEBUG,INFO,WARN,ERROR,ALL和OFF。还有一个特殊值INHERITED或其同义词null，代表强制继承上级的级别。如果未设置此属性，则当前 Logger 将继承其上级的级别。
• additivity：是否向上级 Logger 传递打印信息。默认是true。

4. 子节点<root>

<root>也是一个 Logger 元素，但它是根 Logger，是所有其他 Logger 的上级。它只有一个level属性，因为其name已固定为 "root"，且已是最上级。

• level：用于设置打印级别，大小写不敏感：TRACE,DEBUG,INFO,WARN,ERROR,ALL和OFF。不能设置为INHERITED或null。默认是DEBUG。

与<logger>一样，<root>可以包含零个或多个<appender-ref>元素，表示将 Appender 添加到此 Logger。

示例： 常用 Logger 配置

<!-- show parameters for hibernate sql 专为 Hibernate SQL 定制 -->
<logger name="org.hibernate.type.descriptor.sql.BasicBinder" level="TRACE" />
<logger name="org.hibernate.type.descriptor.sql.BasicExtractor" level="DEBUG" />
<logger name="org.hibernate.SQL" level="DEBUG" />
<logger name="org.hibernate.engine.QueryParameters" level="DEBUG" />
<logger name="org.hibernate.engine.query.HQLQueryPlan" level="DEBUG" />

<!-- MyBatis log configure -->
<logger name="org.apache.ibatis" level="TRACE"/>
<logger name="java.sql.Connection" level="DEBUG"/>
<logger name="java.sql.Statement" level="DEBUG"/>
<logger name="java.sql.PreparedStatement" level="DEBUG"/>

5. 子节点<contextName>

<contextName>用于设置上下文名称。每个 Logger 都关联到一个 Logger 上下文，默认上下文名称为default。可以使用<contextName>设置成其他名称，用于区分不同应用程序的日志记录。一旦设置，上下文名称不能修改。

示例：

<configuration scan="true" scanPeriod="60 seconds" debug="false">
    <contextName>myAppName</contextName>
    <!-- 其他配置省略 -->
</configuration>

6. 子节点<property>

<property>用于定义变量值，它有两个属性name和value。通过<property>定义的值会被插入到 Logger 上下文中，可以通过${}语法来使用这些变量。

• name：变量的名称。
• value：变量定义的值。

示例：

<configuration scan="true" scanPeriod="60 seconds" debug="false">
    <property name="APP_Name" value="myAppName" />
    <contextName>${APP_Name}</contextName>
    <!-- 其他配置省略 -->
</configuration>

7. 子节点<timestamp>

<timestamp>用于获取时间戳字符串，它有两个属性key和datePattern。

• key：标识此<timestamp>的名字。
• datePattern：设置将当前时间（解析配置文件的时间）转换为字符串的模式，遵循java.text.SimpleDateFormat的格式。

示例：

<configuration scan="true" scanPeriod="60 seconds" debug="false">
    <timestamp key="bySecond" datePattern="yyyyMMdd'T'HHmmss"/>
    <contextName>${bySecond}</contextName>
    <!-- 其他配置省略 -->
</configuration>

三、logback.xml配置示例

<?xml version="1.0" encoding="UTF-8"?>
<configuration debug="false">

    <!-- 定义日志文件的存储地址，避免在 Logback 配置中使用相对路径 -->
    <property name="LOG_HOME" value="/home" />

    <!-- 控制台日志 Appender -->
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <!-- 格式化输出：%d表示日期，%thread表示线程名，%-5level：级别从左显示5个字符宽度，%logger{50}：logger名称最多50个字符，%msg：日志消息，%n是换行符 -->
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- 文件日志 Appender，按照每天生成日志文件 -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <!-- 日志文件输出的文件名模式 -->
            <FileNamePattern>${LOG_HOME}/TestWeb.log.%d{yyyy-MM-dd}.log</FileNamePattern>
            <!-- 日志文件保留天数 -->
            <MaxHistory>30</MaxHistory>
        </rollingPolicy>
        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <!-- 格式化输出：%d表示日期，%thread表示线程名，%-5level：级别从左显示5个字符宽度，%logger{50}：logger名称最多50个字符，%msg：日志消息，%n是换行符 -->
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
        </encoder>
        <!-- 日志文件达到最大大小时触发滚动 -->
        <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
            <MaxFileSize>10MB</MaxFileSize>
        </triggeringPolicy>
    </appender>

    <!-- 专为 Hibernate SQL 定制日志级别 -->
    <logger name="org.hibernate.type.descriptor.sql.BasicBinder" level="TRACE" />
    <logger name="org.hibernate.type.descriptor.sql.BasicExtractor" level="DEBUG" />
    <logger name="org.hibernate.SQL" level="DEBUG" />
    <logger name="org.hibernate.engine.QueryParameters" level="DEBUG" />
    <logger name="org.hibernate.engine.query.HQLQueryPlan" level="DEBUG" />

    <!-- MyBatis 日志配置 -->
    <logger name="org.apache.ibatis" level="TRACE"/>
    <logger name="java.sql.Connection" level="DEBUG"/>
    <logger name="java.sql.Statement" level="DEBUG"/>
    <logger name="java.sql.PreparedStatement" level="DEBUG"/>

    <!-- 根日志记录器的输出级别和 Appender 引用 -->
    <root level="DEBUG">
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE"/>
    </root>
</configuration>

四、总结

1. 输出源选择

Logback 的配置涉及输出源appender、日志记录器logger（子节点）和根记录器root（根节点）。实际上，Logback 输出日志的流程是从最具体的 Logger 开始：

• 如果 Logger 配置了 Appender 引用（<appender-ref>），它将直接使用这些 Appender 输出日志。
• 同时，Logback 会检查 Logger 的additivity属性。如果additivity为true（默认值），日志事件还会向上级 Logger 传递。
• 上级 Logger 会继续重复上述过程，直到根 Logger。根 Logger 总是会处理传递过来的日志事件，并使用其配置的 Appender 输出。
• 如果 Logger 的additivity属性设置为false，则日志事件将不会传递给其上级 Logger，也不会使用上级 Logger 或根 Logger 的 Appender。

2. 日志级别 Level

日志记录器（Logger）的行为是分等级的，级别从高到低依次为OFF、FATAL、ERROR、WARN、INFO、DEBUG、TRACE、ALL，或自定义级别。

Logback 建议在实践中主要使用ERROR、WARN、INFO、DEBUG、TRACE这四个级别。级别高于或等于指定级别的日志将被打印出来。

例如，如果将 Logger 级别定义为INFO，则应用程序中所有DEBUG和TRACE级别的日志信息将不会被打印出来。

重要提示： 在生产环境中，通常应将日志级别调整为WARN或更高级别（如ERROR），以避免生成过多日志影响性能和存储。

参考：logback 配置文件