logback TimeBasedRollingPolicy的fileNamePattern和file配置详解

本文主要介绍 fileNamePattern和file两个配置项

1. file配置项

1. file配置项是作为RollingFileAppender的一个配置项而被定义，即继承于RollingFileAppender的其他子类都可以使用file配置项。
2. file主要是用来指定日志输出的文件名

2. fileNamePattern配置项

1. fileNamePattern配置项是作为TimeBasedRollingPolicy的一个配置项被定义。
2. 该配置项主要是用来定制化一个日志的流转策略

TimeBasedRollingPolicy类的定义

可以看出来，TimeBasedRollingPolicy继承了RollingPolicyBase且实现了TriggeringPolicy接口。根据我们上文所说的，这样的policy可以同时实现流转策略和触发策略两种功能。那么在实现这两种功能的过程中，fileNamePattern这个配置项就完成了很大的一部分工作

fileNamePattern的格式

1. string类型，必选。
2. 定义了归档之后的文件名。
3. 设置的值必须包含一个固定文件名和一个放在适当位置的%d的约定标识符。
   1. %d包括日期和时间的格式（被java.text.SimpleDateFormat定义）。
   2. %d的默认值yyyy-MM-dd。
   3. 日志文件滚动归档的周期也是根据%d推断出来的。
   4. 注意：如果其中包含了\或者是/都会被当做是文件分隔符

3. fileNamePattern和file的搭配使用（解耦）

因为在TimeBasedRollingPolicy中，fileNamePattern是必选配置项，file是可选配置项，所以需要考虑下面两种情况：

1. 同时设置了fileNamePattern和file：
   file设置的值决定了实时输出的日志文件名，因为file是一个固定字符串。所以也就意味着当前生效的日志文件名是不会随着时间而发生变化的。例如，设置file的值为a.log。那么日志的直接输出文件永远是a.log
   fileNamePattern设置的值决定了归档日志文件名，根据%d的不同，归档文件的文件名也会有所差异，且归档的触发策略也会因%d的不同而有所不同
2. 只设置了fileNamePattern，没有设置file：
   不管是实时生效日志文件名还是归档文件名都是通过fileNamePattern计算出来的，会随着时间的变化而发生日志文件名的差异

4. fileNamePattern的不同%d配置举例说明

4.1 /Wombat/foo.% d (天级更新)

1. 当没有指定具体的格式的时候 ，那么就使用默认格式yyyy-MM-dd。
2. 每天0点进行日志滚动
3. 因为没有设置file配置项，那么在2006年12月23日，日志会输出到文件/wombat/foo.2006-12-23。
   在24号0点的时候，日志会定向输出到/wombat/foo.2006-12-24
4. 如果设置了file配置项的值为 /wombat/foo.txt，那么在2006年12月23号的时候，会输出日志到 /wombat/foo.txt。在24号零点的时候 /wombat/foo.txt会被重命名为 /wombat/foo.txt.2006-12-23。一个新的文件 /wombat/foo.txt将会被创建，用来接收24号输出的日志

4.2 /wombat/%d{yyyy/MM}/foo.txt （月级更新）

1. 在每个月月初的时候，进行日志滚动
2. 如果没有设置file配置项，那么在2006年12月的时候，日志会输出到/wombat/2006/12/foo.txt，等到过了12月，到达2007年1月的时候，日志会被重定向到/wombat/2007/01/foo.txt
3. 如果设置了file配置项的值为/wombat/foo.txt，那么实时日志将总是输出到/wombat/foo.txt。且在2006年12月的时候，日志会输出到/wombat/foo.txt，等到过了12月，到达2007年1月的时候，/wombat/foo.txt会被重命名为/wombat/2006/12/foo.txt，并且会创建一个/wombat/foo.txt用来接收2007年1月份的日志。等到1月31号结束到达2月1号的时候，/wombat/foo.txt会被重命名为/wombat/2007/01/foo.txt，依次类推

4.3 wombat/foo.%d{yyyy-ww}.log （周级更新）

1. 每周的第一天进行日志的滚动，注意这里每周的第一天的判断是依赖于本地的日历系统
   关于file配置项设置与否的差异和上述描述类似

4.4 /wombat/foo%d{yyyy-MM-dd_HH}.log （小时级更新）

1. 每一个小时滚动一次日志
2. 关于file配置项设置与否的差异和上述描述类似

4.5 wombat/foo%d{yyyy-MM-dd_HH-mm}.log （分钟级更新）

1. 每一分钟滚动一次日志
2. 关于file配置项设置与否的差异和上述描述类似

4.6 wombat/foo%d{yyyy-MM-dd_HH-mm, UTC}.log （指定时区）

1. 每一分钟滚动一次日志，在UTC时区下
2. 关于file配置项设置与否的差异和上述描述类似

4.7 foo/%d{yyyy-MM,aux}/%d.log （aux 主从使用）

1. 可以看到有两个%d标识符，其中第一个有aux修饰，另一个没有，那么就说明，没有aux修饰的日期为主，有aux修饰的为辅。也可以理解为没有aux修饰的格式为实时写入日志的格式，有aux修改的为归档日志的存储格式
   那么在这个例子中，归档日志被存储在/foo/2006-12/这个文件夹中。因为主%d没有指明具体的日期时间格式，所以默认为是YYYY-MM-dd。所以日志的文件名为2006-12-01.log

注：
任何一个正斜杠或者是反斜杠都会被当做是目录分隔符。而且当目录不存在的时候也会自动创建，所以我们可以很容易的就把日志放在我们的目标目录

4.8 wombat/foo.%d.gz （压缩使用）

1. TimeBasedRollingPolicy 也是支持日志的自动压缩的，如果日志文件名是以 .gz 或者.zip结尾的话， 那么就会触发这一操作
2. 因为没有指定具体的日期时间格式，所以也是天级滚动日志
3. 如果没有设置file配置项，那么在2006年12月23日的时候，日志会输出到/wombat/foo.2006-12-23，等到2006年12月24日的时候，日志会被重定向到/wombat/foo.2006-12-24。而且/wombat/foo.2006-12-23会被压缩到/wombat/foo.2006-12-23.gz
4. 如果设置了file配置项的值为/wombat/foo.txt，那么实时日志将总是输出到/wombat/foo.txt。么在2006年12月23日的时候，日志会输出到/wombat/foo.txt，等到2006年12月24日的时候，/wombat/foo.txt会被重命名为/wombat/foo.2006-12-23.gz，并且会创建一个/wombat/foo.txt用来接收2006年12月24日的日志

5. fileNamePattern 主要作用

1. 计算出日志滚动的周期
2. 计算出每一个归档日志文件的文件名。

两个不同的pattern可能决定的是同样的滚动周期，比如说是yyyy-MM和yyyy@MM，都是指定了月级别的滚动，但是区别在于他们计算出来的归档日志文件的文件名不同

6. 日志滚动的驱动因素

由于技术原因，日志滚动并不是受时间驱动，而是受event输出的驱动。例如在2002年3月8日。fileNamePattern 被设置为fileNamePattern ，那么就由3.9号0点之后的第一个event来触发滚动操作。如果在0点到20分之间都没有日志，21分的时候才有第一个event到达，那么日志的滚动就是在21分的时候触发，而不是0分。因此，根据event的到达率，可能会有一些延迟。但是不管是怎么延迟，滚动算法是不会发生变化的。因为在某一时间段内的日志输出在该时间段内正确的日志文件中