一、参考文档
- Logback 官方文档
- 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 配置文件