(三)Logback中的Appender

╰半橙微兮° 2022-02-05 07:07 384阅读 0赞

一、什么是Appender？

Logback会把书写日志事件的任务委托给叫做appender的组件，appenders必须实现[`ch.qos.logback.core.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或setter方法，而doAppend()方法例外，该方法携带E类型的实例作为唯一参数。E的实际类型取决于logback组件，在logback-classic里，E的类型为[ILoggingEvent][]，而在logback-access组件里，E的类型为[AccessEvent][]。doAppend()方法负责以合适的方式输出日志事件到输出设备。

Appender接口继承自FilterAttachable接口，因此可以绑定一个或多个filters。Appenders负责输出日志事件，但它可能会把实际日志格式化事件委托给Layout或者Encoder对象。而有些Appenders有内置或者固定的事件格式，因此不需要配置layout或者encoder。

Appender相关类图如下：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xpbmdib21hbmJ1X2x5bA_size_16_color_FFFFFF_t_70][]

二、Appender分类

1、ConsoleAppender

见名知意，日志信息输出到控制台，也就是通过System.out或者System.err输出，前者是默认值。

<table> 
 <tbody> 
  <tr> 
   <th>属性名</th> 
   <th style="width:79px;">类型</th> 
   <th style="width:689px;">备注</th> 
  </tr> 
  <tr> 
   <td><strong>encoder</strong></td> 
   <td style="width:79px;"><a href="https://logback.qos.ch/xref/ch/qos/logback/core/encoder/Encoder.html" rel="nofollow"><code>Encoder</code></a></td> 
   <td style="width:689px;">编码器。</td> 
  </tr> 
  <tr> 
   <td><strong>target</strong></td> 
   <td style="width:79px;"><code>String</code></td> 
   <td style="width:689px;">有效值为System.out或者System.err，默认为System.out。</td> 
  </tr> 
  <tr> 
   <td><strong>withJansi</strong></td> 
   <td style="width:79px;"><code>boolean</code></td> 
   <td style="width:689px;">默认为false，设为true激活<a href="http://jansi.fusesource.org/" rel="nofollow">Jansi</a>库，该库提供了windows机器上ANSI颜色编码支持，用不上。</td> 
  </tr> 
 </tbody> 
</table>

示例：

<configuration>
    
      <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        
        <encoder>
          <pattern>%-4relative [%thread] %-5level %logger{35} - %msg %n</pattern>
        </encoder>
      </appender>
    
      <root level="DEBUG">
        <appender-ref ref="STDOUT" />
      </root>
    </configuration>

2、FileAppender

OutputStreamAppender的子类，输出日志信息到文件中，目标文件通过File选项指定。

<table> 
 <tbody> 
  <tr> 
   <th>属性名</th> 
   <th style="width:82px;">类型</th> 
   <th style="width:692px;">备注</th> 
  </tr> 
  <tr> 
   <td><strong>append</strong></td> 
   <td style="width:82px;"><code>boolean</code></td> 
   <td style="width:692px;">是否追加到指定文件。</td> 
  </tr> 
  <tr> 
   <td><strong>encoder</strong></td> 
   <td style="width:82px;"><a href="https://logback.qos.ch/xref/ch/qos/logback/core/encoder/Encoder.html" rel="nofollow"><code>Encoder</code></a></td> 
   <td style="width:692px;">编码器。</td> 
  </tr> 
  <tr> 
   <td><strong>file</strong></td> 
   <td style="width:82px;"><code>String</code></td> 
   <td style="width:692px;">写入日志信息的文件名，如果文件不存在，自动创建。</td> 
  </tr> 
  <tr> 
   <td><strong>prudent</strong></td> 
   <td style="width:82px;"><code>boolean</code></td> 
   <td style="width:692px;">谨慎模式写入，默认为false。当多个JVM中的Appender实例写入相同文件时，谨慎模式下会串行I/O操作。</td> 
  </tr> 
 </tbody> 
</table>

示例：

<configuration>
    
      <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        <file>testFile.log</file>
        <append>true</append>
        
        <immediateFlush>true</immediateFlush>
        
        <encoder>
          <pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</pattern>
        </encoder>
      </appender>
            
      <root level="DEBUG">
        <appender-ref ref="FILE" />
      </root>
    </configuration>

2.1 日志文件唯一命名(通过timestamp)

<configuration>
    
      
      <timestamp key="bySecond" datePattern="yyyyMMdd'T'HHmmss" timeReference="contextBirth"/>
    
      <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        
        <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，可选属性为timeReference，key指定名字，dataPattern指定日期转换格式，timeReference指定引用的时间戳。

3、RollingFileAppender

RollingFileAppender继承自FileAppender，用于翻滚日志文件。例如，写入日志信息到名为log.txt的文件，由于超出指定的文件大小限制，日志输出到另一个文件。

<table> 
 <tbody> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>备注</th> 
  </tr> 
  <tr> 
   <td><strong>file</strong></td> 
   <td><code>String</code></td> 
   <td>参考FileAppender。</td> 
  </tr> 
  <tr> 
   <td><strong>append</strong></td> 
   <td><code>boolean</code></td> 
   <td>参考FileAppender。</td> 
  </tr> 
  <tr> 
   <td><strong>encoder</strong></td> 
   <td><a href="https://logback.qos.ch/xref/ch/qos/logback/core/encoder/Encoder.html" rel="nofollow"><code>Encoder</code></a></td> 
   <td>编码器。</td> 
  </tr> 
  <tr> 
   <td><strong>rollingPolicy</strong></td> 
   <td><code>RollingPolicy</code></td> 
   <td>滚动策略。</td> 
  </tr> 
  <tr> 
   <td><strong>triggeringPolicy</strong></td> 
   <td><code>TriggeringPolicy</code></td> 
   <td>触发策略。</td> 
  </tr> 
  <tr> 
   <td style="vertical-align:top;"><strong>prudent</strong></td> 
   <td style="vertical-align:top;"><code>boolean</code></td> 
   <td style="vertical-align:top;">参考FileAppender。</td> 
  </tr> 
 </tbody> 
</table>

3.1 滚动策略

滚动策略负责日志文件移动和重命名相关滚动步骤，该接口api如下：

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);
    }

3.1.1 TimeBasedRollingPolicy(基于时间的滚动策略)

基于时间的滚动策略是最长使用的滚动策略，可以通过天或者月份制定何时滚动。

<table> 
 <tbody> 
  <tr> 
   <th>属性名</th> 
   <th>类型</th> 
   <th>备注</th> 
  </tr> 
  <tr> 
   <td><strong>fileNamePattern</strong></td> 
   <td><code>String</code></td> 
   <td>必选参数，定义了归档日志文件的名字，它的值由文件名和%d的占位转换符组成，如果没有指定时间和日期格式，默认为yyyy-MM-dd。 <p>&nbsp;</p> <p>多个%d转换符</p> <p>/var/log/<strong>%d{yyyy/MM, aux}</strong>/myapplication.<strong>%d{yyyy-MM-dd}</strong>.log</p> </td> 
  </tr> 
  <tr> 
   <td><strong>maxHistory</strong></td> 
   <td>int</td> 
   <td>可选参数，表示日志文件保存的最大数量。例如：如果按天滚动，该值设为30，则日志文件最多保存30天。</td> 
  </tr> 
  <tr> 
   <td><strong>totalSizeCap</strong></td> 
   <td>int</td> 
   <td> <p>可选参数，表示所有归档日志文件的的文件大小，和maxHistory结合使用，maxHistory优先于totalSizeCap。</p> </td> 
  </tr> 
  <tr> 
   <td><strong>cleanHistoryOnStart</strong></td> 
   <td>boolean</td> 
   <td> <p>可选参数，表示appender启动时是否清除归档日志文件，默认为false。</p> </td> 
  </tr> 
 </tbody> 
</table>

下面是一些fileNamePattern的示例：

<table> 
 <tbody> 
  <tr> 
   <th>文件命名格式</th> 
   <th style="width:250px;">滚动计划</th> 
   <th style="width:398px;">备注</th> 
  </tr> 
  <tr> 
   <td><em>/wombat/foo.%d</em></td> 
   <td style="width:250px;">按日滚动，由于%d后缺失日期和时期格式，采用默认格式yyyy-MM-dd</td> 
   <td style="width:398px;"> <p>如果设置file属性(日志文件名)，文件格式如下：</p> <p>昨天：/wombat/foo.2019-05-05</p> <p>当天：/wombat/foo.2019-05-06</p> <p>&nbsp;</p> <p>如果设置file属性为/wombat/foo.txt，文件格式如下<br> 昨天：/wombat/foo.2019-05-05</p> <p>当天：/wombat/foo.txt</p> </td> 
  </tr> 
  <tr> 
   <td><em>/wombat/%d{yyyy/MM}/foo.txt</em></td> 
   <td style="width:250px;">按月滚动</td> 
   <td style="width:398px;"> <p>如果没设置file属性，文件格式如下：</p> <p>上个月：/wombat/2019/05/foo.txt</p> <p>当月：/wombat/2019/06/foo.txt</p> <p>&nbsp;</p> <p>如果设置file属性为/wombat/foo.txt，</p> <p>上个月：/wombat/2019/05/foo.txt</p> <p>当月：/wombat/foo.txt</p> </td> 
  </tr> 
  <tr> 
   <td><em>/wombat/foo.%d{yyyy-ww}.log</em></td> 
   <td style="width:250px;">每周第一天滚动</td> 
   <td style="width:398px;">文件命名规则与上类似</td> 
  </tr> 
  <tr> 
   <td><em>/wombat/foo%d{yyyy-MM-dd_HH}.log</em></td> 
   <td style="width:250px;">按小时滚动</td> 
   <td style="width:398px;">文件命名规则与上类似</td> 
  </tr> 
  <tr> 
   <td><em>/wombat/foo%d{yyyy-MM-dd_HH-mm}.log</em></td> 
   <td style="width:250px;">按分钟滚动</td> 
   <td style="width:398px;">文件命名规则与上类似</td> 
  </tr> 
  <tr> 
   <td><em>/wombat/foo%d{yyyy-MM-dd_HH-mm, UTC}.log</em></td> 
   <td style="width:250px;">指定时区按分钟滚动</td> 
   <td style="width:398px;">文件命名规则与上类似，只是指定了时区</td> 
  </tr> 
  <tr> 
   <td><em>/foo/%d{yyyy-MM,<strong>aux</strong>}/%d.log</em></td> 
   <td style="width:250px;">按天滚动，归档日志文件在一个包含年和月文件夹里。</td> 
   <td style="width:398px;">第一个%d起辅助作用，第二个%d由于没有指定日期和时间格式，默认为yyyy-MM-dd。</td> 
  </tr> 
 </tbody> 
</table>

TimeBasedRollingPolicy支持归档日志文件自动压缩，如果fileNamePattern的值以.gz或者.zip结尾则可利用该特性。

<table> 
 <tbody> 
  <tr> 
   <th>文件命名格式</th> 
   <th style="width:197px;">滚动计划</th> 
   <th style="width:515px;">备注</th> 
  </tr> 
  <tr> 
   <td><em>/wombat/foo.%d.gz</em></td> 
   <td style="width:197px;">按日滚动，归档日志文件会自动GZIP压缩</td> 
   <td style="width:515px;"> <p>如果file属性没有设置，文件格式如下：</p> <p>昨天：/wombat/foo.2019-05-05.gz</p> <p>当天：/wombat/foo.2019-05-06</p> <p>&nbsp;</p> <p>如果设置file属性为/wombat/foo.txt，文件格式如下：</p> <p>昨天：/wombat/foo.2019-05-05.gz</p> <p>当天：/wombat/foo.txt</p> </td> 
  </tr> 
 </tbody> 
</table>

示例1 (滚动策略为TimeBasedRollingPolicy的RollingFileAppender)：

<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}.log</fileNamePattern>
    
          
          <maxHistory>30</maxHistory>
          <totalSizeCap>3GB</totalSizeCap>
    
        </rollingPolicy>
    
        <encoder>
          <pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</pattern>
        </encoder>
      </appender> 
    
      <root level="DEBUG">
        <appender-ref ref="FILE" />
      </root>
    </configuration>

示例2 (谨慎模式)：

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

3.1.2 Size and time based rolling policy(基于文件大小和时间的滚动策略)

通过这种策略可以按日期来归档日志文件，同时也可以限制每个日志文件的大小，示例如下：

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

注意：%i转换符和%d在这里是必须的，当前时间周期内如果日志文件大小达到了maxFileSize，则会进行归档，文件名以从0开始的递增索引命名，%i表示从0开始递增索引。例如：mylog-2019-05-05.0.txt

3.1.3 FixedWindowRollingPolicy(固定窗口的滚动策略)  
滚动时会根据固定窗口算法重命名文件，下面是FixedWindowRollingPolicy的可用属性：

<table> 
 <tbody> 
  <tr> 
   <th>属性名</th> 
   <th style="width:66px;">类型</th> 
   <th style="width:659px;">备注</th> 
  </tr> 
  <tr> 
   <td><strong>minIndex</strong></td> 
   <td style="width:66px;"><code>int</code></td> 
   <td style="width:659px;"> <p>最小索引</p> </td> 
  </tr> 
  <tr> 
   <td><strong>maxIndex</strong></td> 
   <td style="width:66px;"><code>int</code></td> 
   <td style="width:659px;"> <p>最大索引</p> </td> 
  </tr> 
  <tr> 
   <td><strong>fileNamePattern</strong></td> 
   <td style="width:66px;"><code>String</code></td> 
   <td style="width:659px;"> <p>文件命名格式，必须包含%i转换符，用来表示被插入的当前窗口索引的位置。例如：</p> <p>如果文件命名格式为MyLogFile%i.log，minIndex、maxIndex分别被设为1、3，那么滚动时会产生名为MyLogFile1.log、MyLogFile2.log、MyLogFile3.log的三个日志文件。</p> </td> 
  </tr> 
 </tbody> 
</table>

假设minIndex被设为1，maxIndex被设为3，fileNamePatter被设为foo%i.log，file属性被设为foo.log，具体示例如下：

<table> 
 <tbody> 
  <tr> 
   <th style="width:82px;">滚动次数</th> 
   <th style="width:114px;">输出目标</th> 
   <th style="width:111px;">归档日志文件</th> 
   <th style="width:542px;">备注</th> 
  </tr> 
  <tr> 
   <td style="width:82px;">0</td> 
   <td style="width:114px;">foo.log</td> 
   <td style="width:111px;">-</td> 
   <td style="width:542px;">没有产生滚动，日志输出文件为初始文件foo.log。</td> 
  </tr> 
  <tr> 
   <td style="width:82px;">1</td> 
   <td style="width:114px;">foo.log</td> 
   <td style="width:111px;">foo1.log</td> 
   <td style="width:542px;">第一次滚动，foo.log重命名为foo1.log，新的foo.log被创建作为输出目标。</td> 
  </tr> 
  <tr> 
   <td style="width:82px;">2</td> 
   <td style="width:114px;">foo.log</td> 
   <td style="width:111px;">foo1.log, foo2.log</td> 
   <td style="width:542px;">第二次滚动，foo1.log重命名为foo2.log，foo.log重命名为foo1.log，新的foo.log被创建作为输出目标。</td> 
  </tr> 
  <tr> 
   <td style="width:82px;">3</td> 
   <td style="width:114px;">foo.log</td> 
   <td style="width:111px;">foo1.log, foo2.log, foo3.log</td> 
   <td style="width:542px;">第三次滚动，foo2.log重命名为foo3.log，foo1.log重命名为foo2.log，foo.log重命名为foo1.log，新的foo.log被创建作为输出目标。</td> 
  </tr> 
  <tr> 
   <td style="width:82px;">4</td> 
   <td style="width:114px;">foo.log</td> 
   <td style="width:111px;">foo1.log, foo2.log, foo3.log</td> 
   <td style="width:542px;">后面滚动会先删除foo3.log，然后循环如上步骤。</td> 
  </tr> 
 </tbody> 
</table>

配置如下：

<configuration>
      <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>test.log</file>
    
        <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
          <fileNamePattern>tests.%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>

三、TriggerPolicy(触发策略)

TriggerPolicy实现负责指导RollingFileAppender什么时候回滚，该接口如下：

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);
    }

1、SizeBasedTriggeringPolicy

SizeBasedTriggeringPolicy会观察当前日志文件的大小，如果增长到指定值，会通知RollingFileAppender触发滚动。SizeBasedTriggeringPolicy只接受一个参数，也就是maxFileSize，默认值为10MB。maxFileSize选项的值可以是bytes、kilobytes、megabytes、gigabytes。例如：5000000、5000KB、5MB、2GB，前面三个等价。

下面是RollingFileAppender结合SizeBasedTriggeringPolicy配置示例：

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

结语：其它的appender还有SocketAppender、SSLSocketAppender、SMTPAppender等，具体参考：[https://logback.qos.ch/manual/appenders.html\#prudentWithRolling][https_logback.qos.ch_manual_appenders.html_prudentWithRolling]

[ch.qos.logback.core.Appender]: https://logback.qos.ch/xref/ch/qos/logback/core/Appender.html
[ILoggingEvent]: https://logback.qos.ch/apidocs/ch/qos/logback/classic/spi/ILoggingEvent.html
[AccessEvent]: https://logback.qos.ch/apidocs/ch/qos/logback/access/spi/AccessEvent.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xpbmdib21hbmJ1X2x5bA_size_16_color_FFFFFF_t_70]: /images/20220205/898ec8ef6cae4f548e67f234c62a925e.png
[https_logback.qos.ch_manual_appenders.html_prudentWithRolling]: https://logback.qos.ch/manual/appenders.html#prudentWithRolling