什么是 Appender

Appender是负责写记录事件的组件。Appender 必须实现接口“ch.qos.logback.core.Appender”。该接口的重要方法总结如下：

package ch.qos.logback.core;
import ch.qos.logback.core.spi.ContextAware;
import ch.qos.logback.core.spi.FilterAttachable;
import ch.qos.logback.core.spi.LifeCycle;
public interface Appender<E> extends LifeCycle, ContextAware,
FilterAttachable {
public String getName();
public void setName(String name);
void doAppend(E event);
}

Appender 接口里的多数方法都是 getter 和 setting。值得注意的是 doAppend()方法，它唯一的参数是类型E的对象。类型E的实际类型视 logback模块的不同而不同。在 logback-classic模块里，E 可能是“ILoggingEvent”类型；在 logback-access 模块里，E 可能是“AccessEvent”类型。doAppend()方法也许是 logback 框架里最重要的方法，它负责以适当的格式将记录事件输出到合适的设备。
Appender 是被命名的实体。因为有名字，所以能被引用。Appender 接口扩展了FilterAttachable 接口，因此 appender 实例可被关联一个或多个过滤器。
Appender 是最终负责输出记录事件的组件。然而，它们可以把实际格式化的任务委托给Layout或Encoder对象。每个layout/encoder都关联到一个且仅一个appender。有些appender有内置的或固定的事件格式，因此它们不需要也没有 layout/encoder。例如，SocketAppender在发送记录事件之前只是简单地对其进行序列化。

AppenderBase

类 ch.qos.logback.core.AppenderBase 是实现了 Appender 接口的抽象类。AppenderBase提供所有 appender 共享的基本功能，比如设置/获取名字的方法，其活动状态和过滤器。
AppenderBase 是 loback 里所有 appender 的超类。尽管是抽象类，AppenderBase 实际上实现了 Appender 接口的 doAppend()方法。代码更能说明问题：

public synchronized void doAppend(E eventObject) {
// prevent re-entry.
if (guard) {
return;
}
try {
guard = true;
if (!this.started) {
if (statusRepeatCount++ < ALLOWED_REPEATS) {
addStatus(new WarnStatus(
"Attempted to append to non started appender ["
+ name + "].", this));
}
return;
}
if (getFilterChainDecision(eventObject) == FilterReply.DENY)
{
return;
}
// ok, we now invoke derived class' implementation of append
this.append(eventObject);
} catch (Exception e) {
if (exceptionCount++ < ALLOWED_REPEATS) {
addError("Appender [" + name + "] failed to append.", e);
}
} finally {
guard = false;
}
}

这里的 doAppend()方法的实现是同步的，确保不同线程对同一个 appender 的记录是线程安全的。
这里进行的同步并不总是合适的，logback 带了与 AppenderBase 非常相似的类ch.qos.logback.core.UnsynchronizedAppenderBase，之后会讨论它。
doAppend()方法做的第一件事就是检查“guard”是否为 true。如果是，则立即退出方法。
如果未设置“guard”，紧接下来的语句就把它设为 true。“guard”确保 doAppend()方法不会递归调用自己。
之后的语句里，我们检查“started”字段是否为 true。如果不是，doAppend()会发出一条警告信息然后返回。换句话说，appender 一旦关闭后，就无法再向它写入。Appender 对象实现 LifeCycle 接口，意味着它们实现了 start()、stop()和 isStarted()方法。对 appender 的所有属性都设值后，Joran 调用 start()方法让 appender 激活自己的属性。Appender 也许会启动失败，比如因为找不到某些属性，或者因为不同属性之间互相引用。例如，假设文件创建是截断模式，那么，FileAppender 在 Append 选项没确定之前不能作用于 File 选项。这种显式激活步骤确保 appender 在属性值被确定之后才能使用属性。
如果 appender 不能启动或者已经被停止，则会通过 logback 的内部状态管理系统发出一条警告消息。尝试几次后，为了避免内部状态系统被同一条警告消息所淹没，doAppend()方法将停止发出这些警告消息。
接着的 if 语句检查关联的过滤器的结果。根据过滤器链的判断结果，事件被拒绝或接受。如果过滤器链没有结果，则事件被默认接受。
doAppend()方法然后调用派生类的append()方法，此方法真正把事件增加到合适的设备。
最后，释放 guard，允许下一个 doAppend()调用。
在本手册中，术语“选项（option）”或“属性（property）”表示用 JavaBeans 内省机制通过 setter 和 getter 方法动态引用的属性（attribute）。

Logback-core

Logback-core 是其他 logback 模块的基础。一般来说，logback-core 里的模块需要一些细微的定制。不过在下面的几节理里，我们将讲述几个直接可以使用的 appender。

OutputStreamAppender

OutputStreamAppender 把事件添加到 java.io.OutputStream。该类提供其他 appender 所需的基本服务。用户通常不直接实例化 OutputStreamAppender 对象。由于 java.io.OutputStream一般无法被方便地映射到字符串，所以无法在配置文件里指定目标 OutputStream 对象。简而言之，你不能在配置文件里配置 OutputStreamAppender。但这不是说 OutputStreamAppender没有配置属性。它的属性如下。

OutputStreamAppender 是另外三个 appender 的超类：ConsoleAppender、FileAppender及其直接子类 RollingFileAppender。下图演示了 OutputStreamAppender 和其子类的类图。

ConsoleAppender

ConsoleAppender把事件添加到控制台，更准确地说是System.out或 System.err，默认为前者。ConsoleAppender按照用户指定的encoder对事件进行格式化。System.out和System.err都是 java.io.PrintStream 类型，因此，它们被包裹在有缓冲 I/O 操作的 OutputStreamWriter 里。

下面是使用 ConsoleAppender 的配置示例。
示例：ConsoleAppender 配置
(logback-examples/src/main/java/chapters/appenders/conf/logback-Console.xml)

<configuration><appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"><!--encoders are assigned the typech.qos.logback.classic.encoder.PatternLayoutEncoder bydefault--><encoder><pattern>%-4relative [%thread] %-5level - %msg%n</pattern></encoder></appender><root level="DEBUG"><appender-ref ref="STDOUT" /></root>
</configuration>

FileAppender

FileAppender 是 OutputStreamAppender 的子类，把记录事件添加到文件。目标文件通过File 选项指定。如果文件已经存在，则根据 Append 属性追加或清空文件。

下面是 FileAppender 的配置文件例子。
示例：FileAppender 配置
(logback-examples/src/main/java/chapters/appenders/conf/logback-fileAppender.xml)

<configuration>
<appender name="FILE" class="ch.qos.logback.core.FileAppender">
<file>testFile.log</file>
<append>true</append>
<!--
encoders are assigned the type
ch.qos.logback.classic.encoder.PatternLayoutEncoder by
default
-->
<encoder>
<pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n
</pattern>
</encoder>
</appender>
<root level="DEBUG">
<appender-ref ref="FILE" />
</root>
</configuration>

唯一文件名（用时间戳）

在程序开发期，或对于短生命期程序如批量程序，可以在个新程序启动时创建新记录文件。用

<configuration>
<!--
Insert the current time formatted as "yyyyMMdd'T'HHmmss" under the
key
"bySecond" into the logger context. This value will be available
to
all subsequent configuration elements.
-->
<timestamp key="bySecond" datePattern="yyyyMMdd'T'HHmmss" />
<appender name="FILE" class="ch.qos.logback.core.FileAppender">
<!--
use the previously created timestamp to create a uniquely named
log
file
-->
<file>log-${bySecond}.txt</file>
<encoder>
<pattern>%logger{35} - %msg%n</pattern>
</encoder>
</appender>
<root level="DEBUG">
<appender-ref ref="FILE" />
</root>
</configuration>

timestamp 元素有两个属性：key 和 datePattern。属性 key 是变量名，对余下的配置元素可用。属性 datePattern 表示把当前时间（解析配置文件的时间）转换成字符串时使用的日期模式，遵从 java.text.SimpleDateFormat 里的约定。

RollingFileAppender

RollingFileAppender 继承 FileAppender，能够滚动记录文件。例如，RollingFileAppender能先记录到文件“log.txt”，然后当符合某个条件时，变成记录到其他文件。RollingFileAppender 有两个与之互动的重要子组件。第一个是 RollingPolicy，负责滚动。
第二个是 TriggeringPolicy，决定是否以及何时进行滚动。所以，RollingPolicy 负责“什么”，TriggeringPolicy 负责“何时”。

要想 RollingFileAppender 起作用，必须同时设置 RollingPolicy 和 TriggeringPolicy。不过，如果 RollingPolicy 也实现了 TriggeringPolicy 接口，那么只需要设置 RollingPolicy。
下面是 RollingFileAppender 的可用属性。

滚动策略概述

RollingPolicy 负责滚动步骤，涉及文件移动和重命名。
RollingPolicy 接口如下：

package ch.qos.logback.core.rolling;
import ch.qos.logback.core.FileAppender;
import ch.qos.logback.core.rolling.helper.CompressionMode;
import ch.qos.logback.core.spi.LifeCycle;
public interface RollingPolicy extends LifeCycle {
public void rollover() throws RolloverFailure;
public String getActiveFileName();
public CompressionMode getCompressionMode();
public void setParent(FileAppender appender);
}

rollover 方法完成对当前记录文件的归档工作。getActiveFileName()方法计算当前记录文件（写实时记录的地方）的文件名。如 getCompressionMode()方法名所示，RollingPolicy 也负责决定压缩模式。最后，RollingPolicy 通过 setParent()方法得到一个对其父的引用。

FixedWindowRollingPolicy

当发生滚动时，FixedWindowRollingPolicy 根据如下固定窗口（window）算法重命名文件。
选项“fileNamePattern”代表归档（滚动）记录文件的文件名模式。该选项是必需的，且必需在模式的某处包含标志“%i”。
下面是 FixedWindowRollingPolicy 的可用属性。

由于固定窗口滚动策略需要的文件重命名操作与窗口大小一样多，所以强烈建议不要使用太大的窗口大小。当用户指定过大的窗口大小时，当前的代码会自动将窗口大小设为 12。让我们来看固定窗口滚动策略的一个更具体的例子。假设“minIndex”是 1， “maxIndex”是 3，“fileNamePatter”是“foo%i.log”。

下面的配置文件演示了 RollingFileAppender 和 FixedWindowRollingPolicy。注意“file”选项是必需的，即使它与“fileNamePattern”选项有部分重叠信息。
示例：使用 FixedWindowRollingPolicy 的 RollingFileAppender 的示例配置
(logback-examples/src/main/java/chapters/appenders/conf/logback-RollingFixedWindow.xml)

<configuration>
<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>testFile.log</file>
<rollingPolicy
class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
<fileNamePattern>testFile.%i.log.zip</fileNamePattern>
<minIndex>1</minIndex>
<maxIndex>3</maxIndex>
</rollingPolicy>
<triggeringPolicy
class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
<maxFileSize>5MB</maxFileSize>
</triggeringPolicy>
<encoder>
<pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n
</pattern>
</encoder>
</appender>
<root level="DEBUG">
<appender-ref ref="FILE" />
</root>
</configuration>

TimeBasedRollingPolicy

TimeBasedRollingPolicy 或许是最受流行的滚动策略。它根据时间来制定滚动策略，例如 根 据 日 或 月 。TimeBasedRollingPolicy 既 负 责 滚 动 也 负 责 触 发 滚 动 。 实 际 上 ，TimeBasedRollingPolicy 同时实现了 RollingPolicy 接口和 TriggeringPolicy 接口。
TimeBasedRollingPolicy 有两个属性：必需的“fileNamePattern”和可选的“maxHistory”。

下面是 fileNamePattern 的部分值及其作用。

所有“”和“/”都被解释为目录分隔符。任何需要的目录都会被创建。所以你可以轻松地把记录文件放到不同的目录。
正如 FixedWindowRollingPolicy，TimeBasedRollingPolicy 支持自动压缩文件。如果“fileNamePattern”选项以“.gz”或“.zip”结尾，就表示需要压缩。

属性“fileNamePattern”有两个目的。一是，通过学习模式，logback 计算滚动周期。二是，计算每个归档文件的名称。注意，可以为两种不同的模式指定同一个周期。模式 yyyy-MM和 yyyy@MM 都表示每月滚动，但它们的归档文件名不同。
通过设置“file”属性，你可以为活动记录文件和归档记录文件指定不同的位置。记录输出会被指向“file”属性指定的文件，所以活动文件的名字不会改变。然而，如果没有“file”
属性，则活动文件的名字会根据“fileNamePattern”的值每隔一段时间就重新计算一次。
属性“maxHistory”控制被保留的归档文件的最大数量，超出数量就删除旧文件。例如，假设每月滚动，且 maxHistory 是 6，则只保留最近 6 个月的归档文件，删除之前的文件。注意当删除旧归档文件时，那些为了归档而创建的目录也会被删除。
出于某些技术原因，滚动不是时钟驱动，而是按照记录事件的到达时间。比如，在 2002年 3 月 8 日，假设“fileNamePattern”是“yyyy-MM-dd”（每日滚动），则午夜过后的第一个记录事件会触发滚动。如果，比如说直到 0 点 23 分 47 秒之前都没有记录事件，那么滚动发生的实际时间是 3 月 9 日 0 点 23 分 47 秒，而不是 0 点 0 分。因此，根据事件到达的频率，滚动或许会被延时触发。不过，在某个时期内产生的所有记录事件都被输出到划分该时期的正确的文件，从这个角度看，虽然有延迟，滚动算法仍然是正确的。
下面是 RollingFileAppender 和 TimeBasedRollingPolicy 合作的例子。
示例：使用 TimeBasedRollingPolicy 的 RollingFileAppender 的配置例子
(logback-examples/src/main/java/chapters/appenders/conf/logback-RollingTimeBased.xml)

<configuration>
<appender name="FILE"
class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>logFile.log</file>
<rollingPolicy
class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<!-- daily rollover -->
<fileNamePattern>logFile.%d{yyyy-MM-dd}.log</fileNamePattern>
<!-- keep 30 days worth of history -->
<maxHistory>30</maxHistory>
</rollingPolicy>
<encoder>
<pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n
</pattern>
</encoder>
</appender>
<root level="DEBUG">
<appender-ref ref="FILE" />
</root>
</configuration>

下面是在 prudent 模式下，使用 TimeBasedRollingPolicy 的 RollingFileAppender 的配置
例子。
示例：使用 TimeBasedRollingPolicy 的 RollingFileAppender 的配置例子
(logback-examples/src/main/java/chapters/appenders/conf/logback-PrudentTimeBasedRollin
g.xml)

<configuration>
<appender name="FILE"
class="ch.qos.logback.core.rolling.RollingFileAppender">
<!-- Support multiple-JVMs writing to the same log file -->
<prudent>true</prudent>
<rollingPolicy
class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<fileNamePattern>logFile.%d{yyyy-MM-dd}.log</fileNamePattern>
<maxHistory>30</maxHistory>
</rollingPolicy>
<encoder>
<pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n
</pattern>
</encoder>
</appender>
<root level="DEBUG">
<appender-ref ref="FILE" />
</root>
</configuration>

基于大小和时间的归档

有时你也许想按照日期进行归档的同时限制每个记录文件的大小，特别是当后处理工具
对记录 文件大 小有 限制时 。Logback 为 此提 供了 SizeAndTimeBasedFNATP ，它是
TimeBasedRollingPolicy 的子组件，FNATP 代表“文件命名和触发策略”。
下面的例子演示了基于大小和时间的记录文件归档。
示例：SizeAndTimeBasedFNATP 配置
(logback-examples/src/main/java/chapters/appenders/conf/logback-sizeAndTime.xml)

<configuration>
<appender name="ROLLING"
class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>mylog.txt</file>
<rollingPolicy
class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<!-- rollover daily -->
<fileNamePattern>mylog-%d{yyyy-MM-dd}.%i.txt</fileNamePattern>
<timeBasedFileNamingAndTriggeringPolicy
class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
<!-- or whenever the file size reaches 100MB -->
<maxFileSize>100MB</maxFileSize>
</timeBasedFileNamingAndTriggeringPolicy>
</rollingPolicy>
<encoder>
<pattern>%msg%n</pattern>
</encoder>
</appender>
<root level="debug">
<appender-ref ref="ROLLING" />
</root>
</configuration>

注意“%d”后面的“%i”。在当前时间周期结束之前，每当当前记录文件达到“maxFileSize”时，就会用递增索引归档，索引从 0 开始。
基于大小和时间的归档支持删除旧归档文件。你需要用“maxHistory”属性指定要保留的周期的数量。当程序停止并重启时，记录会从正确的位置继续，即当前周期的最大索引。

触发策略概述

TriggeringPolicy 负责指示 RollingFileAppender 在什么时候滚动。
TriggeringPolicy 接口只有一个方法。

package ch.qos.logback.core.rolling;
import java.io.File;
import ch.qos.logback.core.spi.LifeCycle;
public interface TriggeringPolicy<E> extends LifeCycle {
public boolean isTriggeringEvent(final File activeFile, final E
event);
}

isTriggeringEvent()方法有两个参数，一个是归档文件，一个是当前正被处理的记录事件。
该方法的具体实现根据这两个参数来决定是否进行滚动。
使用最广泛的触发策略是 TimeBasedRollingPolicy，它也是一个滚动策略，上节已讲过。

SizeBasedTriggeringPolicy

查看当前活动文件的大小。如果超过指定大小，SizeBasedTriggeringPolicy 会告诉RollingFileAppender 去触发当前活动文件的滚动。
SizeBasedTriggeringPolicy 只有一个参数：maxFileSize，默认值是 10MB。
根据数字后面不同的后缀，“maxFileSize”可以是 bytes、KB、MB或 GB。比如 5000000,5000KB、5MB和 2GB都是合法值，且前三个等价。
下面是 RollingFileAppender 与 SizeBasedTriggeringPolicy 合作的配置例子，当记录文件的大小超过 5MB后，会触发滚动。
示例：使用 SizeBasedTriggeringPolicy 的 RollingFileAppender 的配置
(logback-examples/src/main/java/chapters/appenders/conf/logback-RollingSizeBased.xml)

<configuration>
<appender name="FILE"
class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>test.log</file>
<rollingPolicy
class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
<fileNamePattern>test.%i.log.zip</fileNamePattern>
<minIndex>1</minIndex>
<maxIndex>3</maxIndex>
</rollingPolicy>
<triggeringPolicy
class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
<maxFileSize>5MB</maxFileSize>
</triggeringPolicy>
<encoder>
<pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n
</pattern>
</encoder>
</appender>
<root level="DEBUG">
<appender-ref ref="FILE" />
</root>
</configuration>

Logback Classic

Logback Access