Logback(3) 进阶:appender与encoder

Appender

我们在基础配置中简单介绍了appender的配置以及用法，那么这篇我们就来进阶了解一下appender！

回顾一下：什么是Appender

我们在上一篇基本配置的介绍中，我们知道logback 将写入日志事件的任务委托给一个名为 appender 的组件，所以appender是负责日志的输出或者打印事宜。以及大致有一个印象，日志的打印和一个叫doAppend()的方法有关。这篇我们就具体谈谈这些。

源码出发

appender起源在哪里呢？我们通过官方的文档可以知道最顶级的接口Appender是这一切的开端。

public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachable<E> {

    /**
     * Get the name of this appender. The name uniquely identifies the appender.
     */
    String getName();

    /**
     * This is where an appender accomplishes its work. Note that the argument 
     * is of type Object.
     * @param event
     */
    void doAppend(E event) throws LogbackException;

    /**
     * Set the name of this appender. The name is used by other components to
     * identify this appender.
     * 
     */
    void setName(String name);

}

doAppender() 方法接收一个泛型参数 E 作为唯一的参数。E 的实际参数类型取决于 logback 模块。在 logback-classic 模块里面，E 的类型是 ILoggingEvent 。在 logback-access 模块里面，E 的类型是 AccessEvent。doAppend() 是 logback 框架里面最重要的模块。它的责任是将日志事件进行格式化，然后输出到对应的设备上。我们以logback为例打开源码LoggingEvent这个类，这些属性就是E的内容，我们这里大致只要先知道里面存的是日志内容相关的信息。

两个顶级抽象类：AppenderBase ,UnsynchronizedAppenderBase，在官方文档中对AppenderBase的介绍有一句话

It is the super-class of all appenders shipped with logback.

这个不够全面，应该要包含UnsynchronizedAppenderBase，因为这两个加起来才是logback中所有的具体的appender的父类。

因为AppenderBase 的实现是 synchronized 的。不同的线程通过同一个 appender 打印日志是线程安全的。当一个线程 T 正在执行 doAppend() 方法，接下来其它的线程调用将会被阻塞直到线程 T 离开 doAppend() 方法，这样可以确保 T 对 appender 的访问具有独占性。这种日志打印的方式其实对我们线上项目是不够友好的，很多时候我们需要的是多线程的打印方式，UnsynchronizedAppenderBase能够很好满足我们的需求，所以我们的介绍也会以实现UnsynchronizedAppenderBase的appender为介绍对象。

OutputStreamAppender

OutputStreamAppender将事件附加到 java.io.OutputStream 上。这个类提供了其它 appender 构建的基础服务。用户通常不会直接实例一个 OutputStreamAppender 实例。因为一般来说 java.io.OutputStream 类型不能方便的转为 String。因为在配置文件中没有方法去直接指定一个 OutputStream 目标对象。简单来说，你不能通过配置文件配置一个 OutputStreamAppender。但是这并不意味着 OutputStreamAppender 缺少配置属性。

这个appender并不是我们需要具体了解的，我们主要了解他的子类。

OutputStreamAppender 是其他三个 appender 的父类，分别是 ConsoleAppender、FileAppender 以及 RollingFileAppender。FileAppender 又是 RollingFileAppender 的父类。这三个才是我们真正要具体掌握的！

ConsoleAppender

ConsoleAppender将日志事件附加到控制台，更具体来说其实是通过 System.out 或者 System.err 来进行输出。默认通过前者。ConsoleAppender 通过用户指定的 encoder，格式化日志事件。Encoder 会在接下来的章节讨论。System.out 与System.err 两者都是 java.io.PrintStream 类型。因此，它们被包装在可以进行 I/O 缓存操作的 OutputStreamWriter 中。

示例配置：

<configuration>

    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender" >
        <!-- encoder 默认使用 ch.qos.logback.classic.encoder.PatternLayoutEncoder -->
        <encoder>
            <pattern>%-4relative [%thread] %-5level %logger{35} - %msg %n</pattern>
        </encoder>
        <!--<target>System.err</target>-->
        <!--<withJansi>true</withJansi>-->
    </appender>

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

FileAppender

FileAppender 是 OutputStreamAppender 的子类，将日志事件输出到文件中。通过 file 来指定目标文件。如果该文件存在，根据 append 的值，要么将日志追加到文件中，要么该文件被截断。

例如

<configuration>
    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        <file>testFile.log</file>
        <!--         将 immediateFlush 设置为 false 可以获得更高的日志吞吐量 -->
        <immediateFlush>true</immediateFlush>
        <!--         默认为 ch.qos.logback.classic.encoder.PatternLayoutEncoder -->
        <encoder>
            <pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</pattern>
        </encoder>
    </appender>

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

如上配置会在当前项目目录下生成一个testFile.log文件，内容为：

250  [main] INFO  com.exercise.appenderconfig.MyApp - hello,now is 2020-01-08T20:07:16.236

RollingFileAppender

RollingFileAppender继承自FileAppender，具有轮转日志文件的功能。白话文来说：RollingFileAppender 将日志输出到 log.txt 文件，在满足了特定的条件之后，比如第二天把前一天的日志打包起来，或者将日志放到另一个地方。

与 RollingFileAppender 进行交互的有两个重要的子组件。第一个是 RollingPolicy，轮转策略，它负责日志轮转的功能，即轮转日志做什么事情；另一个是 TriggeringPolicy，触发策略，它负责日志轮转的时机，即什么条件下进行轮转。

为了让 RollingFileAppender 生效，必须同时设置 RollingPolicy 与 TriggeringPolicy。但是，如果 RollingPolicy 也实现了TriggeringPolicy 接口，那么只需要设置前一个就好了。

RollingFileAppender 的属性如下所示：

Rolling policy 简介

RollingPolicy 负责轮转的方式为：移动文件以及对文件改名。

接口源码如下：

package ch.qos.logback.core.rolling;  

import ch.qos.logback.core.FileAppender;
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 方法决定采取哪种压缩模式。通过 setParent 方法引用父类。

常用的轮转模式：TimeBasedRollingPolicy

它是基于时间来定义轮转策略。例如按天或者按月。TimeBasedRollingPolicy 既负责轮转的行为，也负责触发轮转。实际上，TimeBasedRollingPolicy 同时实现了 RollingPolicy 与 TriggeringPolicy 接口。

TimeBasedRollingPolicy 的配置中 fileNamePattern是必选项，其它的属性可选。

该模式的轮转周期是通过 fileNamePattern 推断出来的。在某些情况下，你可能想要根据时区而不是主机的时钟来轮转日志，具体见官方文档，这里不做叙述。

TimeBasedRollingPolicy 支持文件自动压缩。如果 fileNamePattern 以 .gz 或者 .zip 结尾，将会启动这个特性。

下面是关于 fileNamePattern 的一些常见示例：

注意：轮转并不是时间驱动的，而是依赖日志事件。例如，在 2020.01.08，假设 fileNamePattern 的值为 yyyy-MM-dd（按天轮转），在晚上零点之后，没有日志事件到来，假设在 23 分 47 秒之后，第一个到达的日志事件将会触发轮转。也就是说轮转实际发生在 01.09 00:23'47 AM 而不是 0:00 AM。因此，依赖日志事件的到达速度，所以轮转可能会有延迟。但是！不管延迟的情况是什么样，一定周期内生成的日志事件将会被输出到指定的文件中。

示例：

<configuration>
    <!-- 按照每天生成日志文件 -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>logFile.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <FileNamePattern>logFile.%d{yyyy-MM-dd}.gz</FileNamePattern>
            <MaxHistory>180</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>

基于大小以及时间的轮转策略:SizeAndTimeBasedRollingPolicy

有时你希望按时轮转，但同时又想限制每个日志文件的大小。特别是如果后期处理工具需要对日志进行大小限制。为了满足这个需求，logback 配备了 SizeAndTimeBasedRollingPolicy。

TimeBasedRollingPolicy 是所有的限制归档文件总大小。而SizeAndTimeBasedRollingPolicy是限制每个日子文件的大小。

例如：

<configuration debug="true">
    <appender name="ROLLING" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>mylog.txt</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
<!--             按天轮转 -->
            <fileNamePattern>mylog-%d{yyyy-MM-dd}.%i.txt</fileNamePattern>
            <maxFileSize>100MB</maxFileSize>
            <maxHistory>60</maxHistory>
            <totalSizeCap>20GB</totalSizeCap>
        </rollingPolicy>

        <encoder>
            <pattern>%msg%n</pattern>
        </encoder>
    </appender>

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

SizeAndTimeBasedRollingPolicy的fileNamePattern属性除了%d之外%i也是必要属性。在当前时间还没有到达周期轮转之前，日志文件达到了 maxFileSize 指定的大小，会进行归档，%i是轮转的索引，递增索引从 0 开始。如：mylog-2020-01-08.0.txt，mylog-2020-01-08.1.txt。

当然默认的轮转算法不止这些还有诸如：FixedWindowRollingPolicy（根据固定窗口算法重命名文件的轮转策略），SizeBasedTriggeringPolicy（观察当前活动文件的大小，如果已经大于了指定的值，它会给 RollingFileAppender 发一个信号触发对当前活动文件的轮转）的触发策略

如果这些常用的还不能满足你的需求也可以自定义appender~

Encoder

什么是Encoder

Encoder 将日志事件转换为字节数组，同时将字节数组写入到一个 OutputStream 中。Encoder 在 logback 0.9.19 版本引进，旨在代替layouts。现在的layouts都是通过LayoutWrappingEncoder来实现 encoder 与 layout 进行交互，它实现了 encoder 接口并且包裹了一个 layout，通过委托该 layout 将日志事件转换为字符串。

PatternLayoutEncoder 是目前真正唯一有用的 encoder。它仅仅包裹了一个 PatternLayout 就完成了大部分的工作。

源码出发

package ch.qos.logback.core.encoder;

public interface Encoder<E> extends ContextAware, LifeCycle {

    /**
     * Get header bytes. This method is typically called upon opening of 
     * an output stream.
     * 
     * @return header bytes. Null values are allowed.
     */
    byte[] headerBytes();

    /**
     * Encode an event as bytes.
     *  
     * @param event
     */
    byte[] encode(E event);
                    
    /**
     * Get footer bytes. This method is typically called prior to the closing 
     * of the stream where events are written.
     * 
     * @return footer bytes. Null values are allowed.
     */
    byte[] footerBytes();
}

我们可以看到这个接口其实很简单，但是可以做的事却远不只看到的如此！

PatternLayoutEncoder

由于 PatternLayout 是最常用的 layout，logback 使用 PatternLayoutEncoder 来满足这种用法。它扩展了 LayoutWrappingEncoder，被限制用来包裹 PatternLayout 实例。

在 logback 0.9.19 版本，无论 FileAppender 还是其子类通过 PatternLayout 来进行配置，都必须使用 PatternLayoutEncoder 来代替。

immediateFlush 属性

在 LOGBACK 1.2.0 中, immediateFlush 属性是 appender 的一部分。

用格式化字符串作为开头

为了帮助解析日志文件，logback 可以将格式化字符串插入到日志文件的顶部。这个功能默认是关闭的。可以为相关的 PatternLayoutEncoder 设置 outputPatternAsHeader 属性的值为 true 来开启这个功能。下面是示例：

<appender name="FILE" class="ch.qos.logback.core.FileAppender"> 
  <file>foo.log</file>
  <encoder>
    <pattern>%d %-5level [%thread] %logger{0}: %msg%n</pattern>
    <outputPatternAsHeader>true</outputPatternAsHeader>
  </encoder> 
</appender>

将会在日志文件中输出类似下面的日志：

#logback.classic pattern: %d [%thread] %-5level %logger{36} - %msg%n
2012-04-26 14:54:38,461 [main] DEBUG com.foo.App - Hello world
2012-04-26 14:54:38,461 [main] DEBUG com.foo.App - Hi again
...

以 "#logback.classic pattern" 开头的行就是新插入的行。

格式化语法：pattern

每一个转换说明符由一个百分号开始 '%'，后面跟随可选的格式修改器，以及用综括号括起来的转换字符与可选的参数。转换字符需要转换的字段。如：logger 的名字，日志级别，日期以及线程名。格式修改器控制字段的宽度，间距以及左右对齐。

我们这里举几个例子，完整的请移步官网：http://logback.qos.ch/manual/layouts.html#ClassicPatternLayout

在给定的转换模式上下文中，% 有特殊的含义，如果作为字面量，需要进行转义。例如，"%d %p % %m%n"。

在大多数的情况下，字面量包括空格或者其它的分隔符，所以它们不会与转换字符混淆。例如，"%level [%thread] - %message%n" 包含字面量字符 " [" 与 "] - "。但是，如果一个转换字符后面紧跟着一个字面量，那么 logback 的模式解析器将会错误的认为这个字面量也是转换字符的一部分。例如，"%date%nHello" 将会被解析成两个转换字符 %date 与 %nHello，但是 %nHello 不是一个转换字符，所以 logback 将会输出 %PARSER_ERROR[nHello]。如果你想要区分 %n 跟 Hello，可以通过给 %n 传递一个空参数。例如，"%date%n{}Hello" 将会被解析为 %date %n 再紧跟着一个字符串 "Hello"。

格式修改器

有了pattern还不够，我们的每个日志的等级可能长可能短比如debug，info，就会造成日志打印的参差不齐，为了美观我们可以使用格式修改器，可以对每个数据字段进行对齐，以及更改最大最小宽度。

可选的格式修改器放在百分号跟转换字符之间。

第一个可选的格式修改器是左对齐标志，也就是减号 (-) 字符。接下来的是最小字段宽度修改器，它是一个十进制常量，表示输出至少多少个字符。如果字段包含很少的数据，它会选择填充左边或者右边，直到满足最小宽度。默认是填充左边 (右对齐)，但是你可以通过左对齐标志来对右边进行填充。填充字符为空格。如果字段的数据大于最小字段的宽度，会自动扩容去容纳所有的数据。字段的数据永远不会被截断。

这个行为可以通过使用最大字段宽度修改器来改变，它通过一个点后面跟着一个十进制常量来指定。如果字段的数据长度大于最大字段的宽度，那么会从数据字段的开头移除多余的字符。

如果想从后面开始截断，可以在点后面增加一个减号。如果是这样的话，最大字段宽度是 8，数据长度是十个字符的长度，那么最后两个字符将会被丢弃。

我们来尝试解读一个pattern吧！

%d{yyyy/MM/dd HH:mm:ss.SSS} %-5p [%t] [%X{requestId} - %C{0}] %m%n

打印的格式大致是日期+左对齐5格的日志等级+ 被[]括起来的线程名+MDC定义的key为requestId+没有包前缀的类名+日志信息+类名。

我们所列举的都是比较常见的打印格式，还有更多奇妙的操作，如打印日志的颜色，分组格式化等等可以具体查看官方文档深入了解！