logback文档阅读

spring/logback/logback.md

@@ -571,3 +571,152 @@ timestamp元素接收两个必填属性，`key`和`datePattern`，并接收一
 - timeReference : 默认情况下，timestamp元素的值为当前配置文件被解析的事件，也可以将其设为`contextBirth`，即context创建时间
 
 #### RollingFileAppender
+`RollingFileAppender`继承了FileAppender，并且支持了滚动日志的能力。RollgingAppender拥有如下子组件：
+- `RollingPolicy`：负责如何执行日志滚动操作
+- `TriggeringPolicy`：负责决定是否/何时出发日志滚动
+
+RollingFileAppender同时需要RollingPolicy和TriggerPolicy组件，但是如果RollingPolicy实现了TriggerPolicy接口，那么只需要RollingPolicy即可。
+
+如下是RollingFileAppender的属性：
+- file: 值为String类型，如果日志只被写到RollingPolicy指定的目标设备，那么file属性可以为空
+- append：是否追加
+- encoder：同FileOutputStream
+- rollingPolicy：值为`RollingPolicy`类型
+- triggeringPolicy：值为`TriggeringPolicy`类型
+- prudent
+
+##### RollingPolicy
+`RollingPolicy`负责日志滚动过程，其中涉及文件移动和重命名。
+
+RollingPolicy接口展示如下：
+```java
+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);
+}
+```
+其中，各方法代表含义如下：
+- rollober: 将当前日志文件归档
+- getActiveFileName：计算当前日志文件的文件名（实时日志将会被写入到其中）
+- getCompressionMode: 决定压缩模式
+- setParent：设置关联的FileAppender
+
+##### TimeBasedRollingPolicy
+TimeBasedRollingPolicy是最常用的rollingPolicy，其基于时间来执行滚动操作，可以通过其设置按天或按月滚动。
+
+TimeBasedRollingPolicy同时实现了RollingPolicy和TriggeringPolicy接口。
+
+TimeBasedRollingPolicy接收一个必填的`fileNamePattern`参数，并且拥有可选填参数：
+- `fileNamePattern`: 该属性定义了已经被滚动（已被归档）文件的文件名，该属性的应该含有文件名，并且在适当位置加上`%d转换说明符`(%d{yyyy-MM-dd})。
+  > ##### %d转换说明符
+  > %d转换说明符包含一个date-and-time格式的字符串，该格式和SimpleDateFormat相同。如果该date-and-time被省略，那么默认为yyyy-MM-dd.
+  >
+  > 可以在fileNamePattern中含有多个%d转换说明符，但是只能有一个`主%d转换说明符`，主%d转换说明符用于推断滚动周期。其他说有的%d转换说明符都需要通过`aux`来进行修饰(`%d{yyyy/MM, aux}`)。
+  >
+  > 示例如下
+  > 
+  > `/var/log/%d{yyyy/MM, aux}/myapplication.%d{yyyy-MM-dd}.log`.
+
+  滚动周期的值将会从date-and-time表达式来推断。
+
+  RollingFileAppender中，file属性可以被省略或设置为null。如果为RollingFileAppender设置了file属性，那么可以解耦当前日志和已经被归档的日志。如果file属性的值，那么当前日志路径就是file文件的值，此时当前日志的路径不会随着日期的变动而改变。
+
+  但是，在省略file属性的情形下，那么当前日志文件路径将会根据fileNamePattern来计算
+
+- `maxHistory`: `maxHistory`指定了保留归档日志的最大数量，会对旧日志进行异步删除。
+  
+  如果将maxHistory设置为0，将会禁用旧日志删除。默认情况下，maxHistory被设置为0。
+  
+- `totalSizeCap`：`totalSizeCap`控制了所有归档日志文件的最大大小，当最大小超过阈值时，最老的文件将会被删除。`totalSizeCap`需要`maxHistory`属性也被设置，通常，totalSizeCap都在maxHistory之后被应用。
+
+默认情况下，totalSizeCap被设置为0，代表不会有总大小的阈值限制。
+
+- `cleanHistoryOnStart`：如果该属性被设置为true，当appender启动时归档日志将会被清除。
+
+TimeBasedRollingPolicy支持文件自动压缩，如果`fileNamePattern`后缀以`.gz`或`.zip`结尾，文件压缩将会自动被应用。
+
+示例如下
+```
+/wombat/foo.%d.gz
+```
+上述示例当前日志被输出到`/wombat/foo.yyyy-MM-dd`文件中，但是在第二天触发归档后，文件将会被压缩到`/wombat/foo.yyyy-MM-dd.gz`中。
+
+
+TimeBasedRollingPolicy示例如下：
+```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 capped at 3GB total size -->
+      <maxHistory>30</maxHistory>
+      <totalSizeCap>3GB</totalSizeCap>
+
+    </rollingPolicy>
+
+    <encoder>
+      <pattern>%-4relative [%thread] %-5level %logger{35} -%kvp- %msg%n</pattern>
+    </encoder>
+  </appender> 
+
+  <root level="DEBUG">
+    <appender-ref ref="FILE" />
+  </root>
+</configuration>
+```
+
+#### SizeAndTimeBasedRollingPolicy
+SizeAndTimeBasedRollingPolicy支持配置单个日志文件的最大大小，其除了支持%d转换符外，还支持%i转换符，%i转换符也是必填的。每当当前日志文件达到最大文件大小时，其都会递增`%i`序列号，并且旧日志文件将会被归档。序列号从0开始。
+
+SizeAndTimeBasedRollingPolicy还包含如下属性：
+- `maxFileSize`：每当当前日志文件达到`maxFileSize`指定的大小时，其都会递增序列号，序列号默认为0.
+
+  maxFileSize为FileSize类型，可以通过`KB, MB, GB`等单位来指定。
+
+- `checkIncrement`：检查当前日志文大小的间隔时间，默认为60s
+
+```xml
+<configuration>
+  <appender name="ROLLING" class="ch.qos.logback.core.rolling.RollingFileAppender">
+    <file>mylog.txt</file>
+    <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
+      <!-- rollover daily -->
+      <fileNamePattern>mylog-%d{yyyy-MM-dd}.%i.txt</fileNamePattern>
+       <!-- each file should be at most 100MB, keep 60 days worth of history, but at most 20GB -->
+       <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>
+```
+
+#### Encoder
+通常，PatternLayoutEncoder，其pattern可以指定为如下形式：
+```xml
+<encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
+    <Pattern>
+      %d{dd-MM-yyyy HH:mm:ss.SSS} [%thread] %-5level %logger{36}.%M - %msg%n
+    </Pattern>
+</encoder>
+```