Java日志框架——Logback配置语法

一、Logback配置基本概念
1.1、Logback配置源的3种形式

分别是代码配置，XML形式的配置文件，Groovy形式的配置文件

1.2、Log4J中的log4j.properties文件转成logback.xml文件

http://logback.qos.ch/translator/

1.3、加载Logback配置源的过程
1)在类路径中，尝试加载logback.groovy文件
2)在类路径中，尝试加载logback-test.xml文件
3)在类路径中，尝试加载logback.xml文件
4)尝试加载一个com.qos.logback.classic.spi.Configurator实例
5)使用BasicConfigurator实例，该实例简单配置Logback

1.4、简单配置举例
在1.3中提及了"使用BasicConfigurator实例，该实例简单配置Logback"，这个简单配置转换成等价的XML形式的配置文件，文件内容如下：

<configuration>
  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <!-- encoders are assigned the type
         ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
    </encoder>
  </appender>

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

1.5、打印Logback运行中的内部状态信息

默认情况下，在Logback运行过程中，如果内部碰到Warning和Error状态，那么相应的内部状态信息会被打印出来；否则，不会有任何内部状态信息被打印出来。
假如想要打印任何内部状态下的信息，可以有3种途径进行配置：
1)代码形式
显式调用"StatusPrinter.print(lc)"方法，具体代码如下：

public static void main(String[] args) {


    // assume SLF4J is bound to logback in the current environment
    LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();


    // print logback's internal status
    StatusPrinter.print(lc);
}

2)XML形式配置文件中的<configuration>标签的debug属性值设为true
具体内容如下：

<configuration debug="true"> 
  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> 
    <!-- encoders are  by default assigned the type
         ch.qos.logback.classic.encoder.PatternLayoutEncoder -->
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
    </encoder>
  </appender>

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

3)通过“logback.statusListenerClass”系统变量
通过“logback.statusListenerClass”系统变量加载"OnConsoleStatusListener"这个StatusListener
具体内容如下：

java -Dlogback.statusListenerClass=ch.qos.logback.core.status.OnConsoleStatusListener

二、XML形式配置文件语法

Logback中XML形式配置文件的语法非常灵活，因而不能用DTD文件或者XML模式文件来进行可使用标签的定义。
在XML形式配置文件内，总体结构是：最顶层是一个<configuration>标签，在<configuration>标签下可以有0到多个<appender>标签，0到多个<logger>标签，最多只能有1个<root>标签以及其他一些高级配置。

如图1

                                                      图1

注意：
在XML形式的配置文件内，有些属性具有默认值，无需显式配置，但是为了更好的可读性和更精确的定义，我们还是显式配置比较好。


2.1、<logger>标签
配置<logger>标签相当于配置Logger实例，<logger>标签允许的属性有：
name:必需的，表示Logger实例的名称
level:可选的，表示Logger实例的Level值，可选值集合为"TRACE,DEBUG,INFO,WARN,ERROR,ALL,OFF和NULL"，其中NULL表示继承祖先或者父亲Logger实例的Level值

additivity:可选的，表示是否继承祖先或者父亲Logger实例绑定的Appender，可选值集合为true,false

<logger>标签允许0到多个<appender-ref>子标签，<appender-ref>子标签用来配置父<logger>标签表示的Logger实例所绑定的Appender，<appender-ref>子标签只有一个"ref"属性，"ref"属性的值为欲绑定Appender实例的名称。

2.2、<root>标签
配置<root>标签相当于配置名称为"ROOT"的特殊Logger实例，<root>标签允许的属性为level。有以下几点需要注意:
1)<root>标签配置的特殊Logger实例已经有名称"ROOT"，因而不允许name属性
2)<root>标签配置的特殊Logger实例处于Logger实例层次结构的最顶层，是否允许继承祖先或者父亲Logger实例的绑定的Appender对其无意义，因而不允许additivity属性
3)<root>标签配置的特殊Logger实例处于Logger实例层次结构的最顶层，继承祖先或者父亲Logger实例的Level值无意义，因而level属性值不能为NULL，level属性的可选值集合是"TRACE,DEBUG,INFO,WARN,ERROR,ALL,OFF"
<root>标签允许0到多个<appender-ref>子标签，<appender-ref>子标签用来配置父<root>标签表示的特殊Logger实例所绑定的Appender，<appender-ref>子标签只有一个"ref"属性，"ref"属性的值为欲绑定Appender实例的名称。

2.3、<appender>标签
配置<appender>标签相当于配置Appender实例，<appender>标签允许的属性有：
name:必需的，表示Appender实例的名称
class:必需的，表示Appender实例的类型
<appender>标签允许的子标签有：0到多个<layout>,0到多个<encoder>,0到多个<filter>和任意的相应于特定Appender类型的属性的标签
比如"ch.qos.logback.classic.db.DBAppender"类型的Appender具有
"connectionSource"属性，那么配置该类型的<appender>标签时，可以配置一个<connectionSource>标签，样例片段如下：

<appender name="DB" class="ch.qos.logback.classic.db.DBAppender">       
        <connectionSource class="ch.qos.logback.core.db.DriverManagerConnectionS
ource">
            <driverClass>com.mysql.jdbc.Driver</driverClass>
            <url>jdbc:mysql://127.0.0.1:3306/dslztx?useUnicode=true&characterEncoding=gbk</url>
            <user>dsl</user>
            <password>dsl</password>
        </connectionSource>
</appender>

2.3.1、<layout>标签

配置<layout>标签相当于配置Layout实例，<layout>标签允许的属性有：
class:必需的，表示Layout实例的类型。如果不显式设置，那么默认值为"ch.qos.logback.classic.PatternLayout"

<layout>标签允许的子标签有：任意的相应于特定Layout类型的属性的标签

Layout被用来格式化LoggingEvent实例，Layout格式化LoggingEvent实例得到一个String
常用的Layout的类型为"ch.qos.logback.classic.PatternLayout"，配置该类型的实例时，一般需配置它的"pattern"属性，样例配置片段如下：

<layout class="ch.qos.logback.classic.PatternLayout">
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
</layout>

2.3.2、<encoder>标签

配置<encoder>标签相当于配置Encoder实例，<encoder>标签允许的属性有：
class:必需的，表示Encoder实例的类型。如果不显式设置，那么默认值为"ch.qos.logback.classic.encoder.PatternLayoutEncoder"
<encoder>标签允许的子标签有：任意的相应于特定Encoder类型的属性的标签
Encoder被用来格式化LoggingEvent实例，Encoder格式化LoggingEvent实例得到一个Byte Array。Encoder和Layout都被用来进行格式化操作，但是相比之下，Encoder拥有更多功能。
常用的Encoder的类型为"ch.qos.logback.classic.encoder.PatternLayoutEncoder"，配置该类型的实例时，一般需配置它的"pattern"属性，样例配置片段如下：

<encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>

备注：PatternLayoutEncoder其实继承Encoder接口，内部包含一个对PatternLayout实例的引用，而PatternLayoutEncoder中配置的pattern属性其实最终是被PatternLayout使用，因此PatternLayout和PatternLayoutEncoder中的pattern属性配置语法一致，关于pattern属性的配置语法见" Conversion Word"

经过实验，pattern属性值设置为如下值：“%-5level %logger %C %M %d{MM/dd-HH:mm:ss.SSS} [%thread] - %msg%n”比较好。

%logger表示Logger实例的名称，开发者在类中定义Logger实例，当使用该类的全限定名称作为Logger实例的名称时，Logger实例的名称可以被用来追溯Logger实例定义所在类;否则，Logger实例的名称不可以被用来追溯Logger实例定义所在类
%M表示产生本条日志记录请求的方法所在
%C表示产生本条日志记录请求的方法所在的类

2.3.3、<filter>标签

配置<filter>标签相当于配置Filter实例，<filter>标签允许的属性有：
class:必需的，表示Filter实例的类型
<filter>标签允许的子标签有：任意的相应于特定Filter类型的属性的标签

Filter被用来根据设置的一些条件来过滤日志记录请求

Logback中的Filter介绍，见文章《Java日志框架——Logback的Filter》

2.4、其他一些高级配置
2.4.1、设置Context Name
有这样的一个应用场景：项目A下的Logback运行的时候将日志记录在文件a.txt中，项目B下的Logback运行的时候也将日志记录在文件a.txt中，对于a.txt文件中的某条日志记录，该如何确定是来自A还是B下的Logback?
某个项目的Logback运行的时候，会得到唯一的一个ch.qos.logback.classic.LoggerContext实例，它负责管理所有的Logger实例，它有一个name属性，可以通过XML形式配置文件中的<contextName>标签定义。

现在我们可以设置项目A下的Logback的Context Name为"A Context Name"，B下的Logback的Context Name为"B Context Name"，接着设置A和B下的Logback在记录日志的时候包含Context Name这个字段（通过"%contextName"指示符实现），这样在最终获得的日志记录中就可以通过Context Name这个字段来判定该条日志记录是来自A还是B下的Logback。

2.4.2、变量定义和使用
1)变量的作用域
变量的作用域有：local scope,context scope,system scope，常用的作用域是local scope。
2)变量的来源
变量的来源主要有3处，分别是：Logback配置文件自身，外部文件，外部资源（外部资源跟外部文件的唯一区别是外部资源处于项目类路径下）。
i、Logback配置文件自身
Logback配置文件配置片段如下：

<property name="USER_HOME" value="/home/dsl" />

ii、外部文件
外部文件"/home/dsl/variables.properties"内容如下：

USER_HOME=/home/dsl

Logback配置文件配置片段如下：

<property file="/home/dsl/variables.properties" />

iii、外部资源
外部资源"resource.properties"内容如下：

USER_HOME=/home/dsl

Logback配置文件配置片段如下：

 <property resource="resource.properties" />

3)使用变量
使用变量采用"${variableName}"的形式

2.4.3、其他

另外还有“支持条件语句”，“从JNDI获取变量”，“配置文件导入”，“配置Context Listener”等高级内容

参考文献：
[1]http://logback.qos.ch/manual/architecture.html
[2]http://logback.qos.ch/manual/configuration.html
[3]http://logback.qos.ch/manual/encoders.html
[4]http://logback.qos.ch/manual/layouts.html
[5]http://logback.qos.ch/manual/filters.html