Chapter 5: Encoders

What is an encoder

编码器负责将事件转化为字节数组，并将字节数组转换成一个OutputStream 。

Encoder ---> Byte[] ---> OutputStream

 

在0.9.19版本之前，大多数的appender都依赖layout布局组件将事件转换为字符串String

在使用java.io.Writer将其写入到文件

在0.9.19版本之前，对FileAppender将在内部嵌套PatternLayout进行样式设置

从0.9.19版本开始，FileAppender将通过Encoder设置样式，不再设置layout属性了

 

This appender no longer admits a layout as a sub-component, set an encoder instead.

to (GOOD)

<appender name="FILE" class="ch.qos.logback.core.FileAppender">
  <file>testFile.log</file>
  ...
  <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
    <pattern>%msg%n</pattern>
  </encoder>
</appender>  

or the shorter equivalent (GOOD) 

<appender name="FILE" class="ch.qos.logback.core.FileAppender">
  <file>testFile.log</file>
  ...
  <!-- encoders are assigned the type 
       ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
  <encoder>
    <pattern>%msg%n</pattern>
  </encoder>
</appender> 

 

For layout type other than PatternLayout, for example HTMLLayout, your configuration files need to be changed

to (GOOD)

<appender name="FILE" class="ch.qos.logback.core.FileAppender">
  <file>testFile.log</file>
  ...
  <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
    <layout class="ch.qos.logback.classic.html.HTMLLayout">
      <pattern>%msg%n</pattern>
    </layout>
  </encoder>
</appender> 

 

Layouts仅仅能够将event转换为某种样式的字符串String

此外，鉴于Layout无法控制何时对event进行写出，也没有批处理能力

Encoder不仅提供了写出字节数组的格式，还可以控制何时进行写出操作

Encoder兼备Layout样式和决定日志写出时机的功能

到目前为止，PatternLayoutEncoder是唯一真正使用的Encoder

PatternLayoutEncoder包装了一个LayoutPattern，从而提供了设置样式的功能

 

Encoder负责将event转换为Byte[]，并将结果写到合适的OutputStream流中

这样，appender就可以通过Encoder完全控制何时将什么bytes进行写出操作

 

LayoutWrappingEncoder

直到logback版本0.9.19 ，许多appender都依赖于布局实例来控制日志输出格式

由于Layout 的接口已经提供了大量的样式设置功能，我们只需要将Encoder与Layout结合在一起即可

LayoutWrappingEncoder作为一个桥梁，有效的将Encoder与Layout两者结合在一起

LayoutWrappingEncoder实现了Encoder接口，并对Layout进行了包装（Layout将event转换为字符串）

 

由此，得到：

Event ---> Layout ---> Formated String ---> Encoder ---> Byte[] ---> OutputStream 

 

LayoutWrappingEncoder

package ch.qos.logback.core.encoder;

public class LayoutWrappingEncoder<E> extends EncoderBase<E> {

  protected Layout<E> layout;
  private Charset charset;
  private boolean immediateFlush = true;

  public void doEncode(E event) throws IOException {
    String txt = layout.doLayout(event);
    outputStream.write(convertToBytes(txt));
    if (immediateFlush)
      outputStream.flush();
  }

  private byte[] convertToBytes(String s) {
    if (charset == null) {
      return s.getBytes();
    } else {
      return s.getBytes(charset);
    }
  } 
}

 

 

PatternLayoutEncoder

鉴于PatternLayout是最常用的布局， logback这种常见的用例满足与PatternLayoutEncoder 

immediateFlush property

true: 保证日志及时输出到文件，会影响系统处理日志的吞吐量；

false:可以大大提高日志处理的throughout，大概5倍，但有可能造成日志丢失(appender没有正确关闭)；

<appender name="FILE" class="ch.qos.logback.core.FileAppender"> 
  <file>foo.log</file>
  <encoder>
    <pattern>%d %-5level [%thread] %logger{0}: %msg%n</pattern>
    <!-- this quadruples logging throughput -->
    <immediateFlush>false</immediateFlush>
  </encoder> 
</appender>

 

 

Output pattern string as header

在输入日志的上方，输出日志的Pattern

默认为false，不在头部输出样式

<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>

 

This will result output akin to the following in the log file: 

#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

 

%d                   日期：2012-04-26 14:54:38,461

[%thread]         线程：[mian]

%-5level           级别：DEBUG

%logger{36}  类路径：com.foo.App

%msg               消息：Hello world

%n                    换行