Log4j2 common configuration

1 Overview

There are many kinds of JAVA commonly used log collection APIs and implementation frameworks. It is more complicated how different APIs and implementation frameworks are compatible with each other, but most log framework implementations also provide compatibility and switching to other log collection methods You can refer to https://my.oschina.net/pingpangkuangmo/blog/410224 ). This article mainly introduces the component list under log4j2 Appenders, and several common appender configurations.

2. Detailed configuration

The log4j2.xml file structure is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xml>
<Configuration>
	<Properties>
		...
	</Properties>

	<Appenders>
		...
	</Appenders>

	<Loggers>
		...
	</Loggers>
</Configuration>

The configuration file consists of three parts: Properties, Appenders and Loggers. Properties configure the basic variables, Loggers is responsible for configuring the log level, Loggers configure the log collection method, layout, output, cleanup and other functions.

2.1. List of appender components

append	label	description
AsyncAppender	<Async>	Used to accept references from other types of appenders and use a separate thread to write to the log asynchronously
CassandraAppender	<Cassandra>	To write logs to Cassandra database, you need to establish keyspace and table in advance
ConsoleAppender	<Console>	The log is written to System.out or System.err, the default is System.out
FailoverAppender	<Failover>	For failover appenders, you can specify the main appender and include a set of appenders. When the main appender fails to write, it will use other appenders in turn until the write is successful or all appenders fail
FileAppender	<File>	Write log to file, use FileManager to execute io
FlumeAppender	<Flume>	Serialize the log and send it to the Flume agent. Optional components are provided by separate jars.
JDBCAppender	<JDBC>	Use standard JDBC to write logs to relational database tables, you must use a connection pool
JMS Appender	<JMS>	Send logs to JMS
JPAAppender	<JPA>	To write logs to relational database tables via JPA, a separate persistence.xml configuration file is required
HttpAppender	<Http>	Send log via http request, use HttpURLConnection to achieve, respond to 2XX status code as success, otherwise throw exception
KafkaAppender	<Kafka>	Send log events to Kafka topic
MemoryMappedFileAppender	<MemoryMappedFile>	2.1 New function, map a part of the specified log file to memory, and write new log events to this memory, and refresh this memory to the storage device when the threshold is reached
NoSQLAppender	-	Use the internal lightweight Provider interface to write log events to the NoSQL database. Currently only the Provider implementation of MongoDB and Apache CouchDB
NoSQLAppender for MongoDB	-	Starting from 2.0.11, two MongoDB modules are provided: log4j-mongodb2, log4j-mongodb3
NoSQLAppender for MongoDB 2	<NoSql name=“databaseAppender”> <MongoDb2> </NoSql>	Write log to MongoDB using MongoDB driver version 2
NoSQLAppender for MongoDB 3	<NoSql name=“databaseAppender”> <MongoDb3> </NoSql>	Write logs to MongoDB using MongoDB driver version 3
NoSQLAppender for Apache CouchDB	<NoSql name=“databaseAppender”> <CouchDb> </NoSql>	Write logs to CouchDB using internal lightweight provider
OutputStreamAppender	-	The OutputStreamAppender cannot be directly configured, but is provided as a basic component to other Appenders, such as File and Socket that can write log events to the output stream
RandomAccessFileAppender	<RandomAccessFile>	Compared with FileAppender, the I / O implementation class used is different. FileAppender uses FileOutputStream and RandomAccessFileAppender uses RandomAccessFile. When bufferedIO = true (default is true), the performance is improved by 20-200%.
RewriteAppender	<Rewrite>	Used to modify log events through RewritePolicy before the log is written to a file by another Appender
RollingFileAppender	<RollingFile>	将日志写入文件，并根据TriggeringPolicy和RolloverPolicy规则将文件归档、清理
RollingRandomAccessFileAppender	<RollingRandomAccessFile>	与RollingFileAppender相比，使用的I/O实现类不同，RollingFileAppender使用FileOutputStream，RollingRandomAccessFileAppender使用RandomAccessFile。bufferedIO=true(默认是true)时，性能提高20-200％ 。
RoutingAppender	<Routing>	配置不同的规则，将日志路由到不同的Appender进行输出
SMTPAppender	<SMTP>	发生指定日志事件时，发送电子邮件
ScriptAppenderSelector	<ScriptAppenderSelector>	根据Script脚本的执行结果来选择AppenderSet中配置的Appender，并将结果输出至ScriptAppenderSelector的name中
SocketAppender	<Socket>	通过tcp或者udp，将日志写入远程目标中
SyslogAppender	<Syslog>	SyslogAppender是一个SocketAppender，它将其输出以符合BSD Syslog或RFC 5424格式的日志写入到远程目标
ZeroMQ/JeroMQ Appender	<JeroMQ>	ZeroMQ Appender使用JeroMQ库将日志事件发送到一个或多个ZeroMQ端点

2.2.ConsoleAppender

ConsoleAppender比较简单，就是把日志写入System.out或者System.err中，基本配置如下：

<Console name="STDOUT" target="SYSTEM_ERR">
	<PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} %t %5p [%c:%L] - %m%n" />
</Console>

Console一般使用基本配置就可以，唯一要注意的就是输出格式pattern，pattern的配置释义如下：

参数	描述
%c或%logger	输出logName，如 Logger log = LoggerFactory.getLogger(“com.test.logName”); 则输出为“com.test.logName” ，如果格式为%c{参数}，则输出内容参考官网：
%C或%class	输出为所在类的全路径名
d{pattern}或date{pattern}	输出时间，其中pattern可以是保留字，也可以是SimpleDateFormat中的字符。如 %d{DEFAULT} --> 2012-11-02 14:34:02,781 %d{DEFAULT_MICROS} --> 2012-11-02 14:34:02,123456 %d{yyyy-MM-dd HH:mm:ss.SSS} --> 2020-03-31 23:25:13.321 详见log4j PatternLayout
%F或%file	输出所在类名.java，如所在类为com.test.LogTest，则输出为LogTest.java
%l	输出错误的完整位置，全路径类名.方法名(类名.java:行号)，如，com.test.LogTest.testLog(LogTest.java:31)
%L	输出行号
%m或%msg或%message	输出log.error(text)中的text内容
%M或%method	输出方法名
%n	换行符
%t或%thread	输出线程名
%u{“RANDOM” | “TIME”}或uuid	输出uuid
%sn或%sequenceNumber	输出自增序列
%r或%relative	输出从JVM启动到当前时刻的毫秒数
%T或%tid或%threadId	输出线程id
%t或%tn或%thread或%threadName	输出线程id
%tp或%threadPriority	输出线程优先级

2.3.RollingFileAppender

RollingFileAppender是一个OutputStreamAppender，可以根据TriggeringPolicy和RolloverPolicy将文件切割归档，通过RollingFileManager（扩展了OutputStreamManager）来实际执行文件I / O并执行归档。参数如下：

参数	类型	描述
append	boolean	默认为true。如果为true，记录将附加到文件末尾。设置为false时，将在写入新记录之前清除文件
bufferedIO	boolean	默认为true。如果为true，数据先写入缓冲区，如果缓冲区满或者immediateFlush 为true时，数据才被写入磁盘，如果为false直接写入磁盘。文件锁定不能与bufferedIO一起使用
bufferSize	int	缓冲区大小。bufferedIO为true时，此参数有效，默认为8192 bytes
createOnDemand	boolean	默认为false。按需创建文件。仅当日志事件通过所有Filter并且路由到该append时，append才创建文件
filter	Filter	确定事件是否应由此Appender处理，通过CompositeFilter（对应标签为<Filters>）可以使用多个过滤器
fileName	String	要写入的文件名，如果不存在或者父目录不存在，则创建对应的文件或目录
filePattern	String	归档文件的模式，取决于所使用的RolloverPolicy
immediateFlush	boolean	默认为true。如果为true，每次写操作后都会将数据刷新入磁盘，可能会影响性能。 每次写入后刷新仅在使用同步appender时才有用。即使设置为false，异步appender也将在一批事件结束后自动刷新，这也可以确保效率更高的将数据写入磁盘。
layout	Layout	格式化日志输出格式。如果未设置，则默认为’%m%n’
name	String	append名称
policy	TriggeringPolicy	用于确定归档的触发条件
strategy	RolloverStrategy	用于确定归档的文件名称、路径及归档方式
ignoreExceptions	boolean	默认为true。设置为true时，如果记录日志发生异常，此条日志和异常将被忽略。设置为false时，异常将被抛出到调用方。如果此append用在FailoverAppender中，则必须设置为false。
filePermissions	String	创建文件时指定文件的rwx权限，前提是文件系统应支持POSIX文件属性视图
fileOwner	String	文件所有者。出于安全原因，更改文件的所有者可能受到限制，并且不允许操作时会抛出IOException。 如果_POSIX_CHOWN_RESTRICTED对路径有效，则只有有效用户ID等于文件用户ID或具有适当特权的进程才可以更改文件的所有权，前提是文件系统应支持文件所有者属性视图
fileGroup	String	文件组。，前提是文件系统应支持POSIX文件属性视图

2.3.1.TriggeringPolicy

TriggeringPolicy是控制日志文件归档的触发条件。总共有四种类型的TriggeringPolicy，可以组合（CompositeTriggeringPolicy）多种触发策略来控制归档，标签为<Policies>，如果配置了多种策略，则只要有一种策略返回true，就返回true。

<Policies>
  <!-- <CronTriggeringPolicy schedule="0 0 * * * ?"/> -->
  <OnStartupTriggeringPolicy minSize="2" />
  <SizeBasedTriggeringPolicy size="20 MB" />
  <TimeBasedTriggeringPolicy />
</Policies>

四种类型如下：

• OnStartupTriggeringPolicy
  如果日志文件的时间比JVM的启动时间早，或者达到minSize的值，则会触发归档。
  minSize：触发文件归档的最小值，默认为1。
• SizeBasedTriggeringPolicy
  当文件达到指定大小后，触发归档。大小可以通过size指定，单位为KB、MB、GB。与TimeBasedTriggeringPolicy配合使用时，filePattern中必须包含%i，否则文件每次归档时都会覆盖当前文件，因为TimeBasedTriggeringPolicy不会让文件名中的时间戳改变。如果不使用TimeBasedTriggeringPolicy，则SizeBasedTriggeringPolicy会让时间戳改变。
• TimeBasedTriggeringPolicy
  当前时间与当前日志文件时间不匹配时，TimeBasedTriggeringPolicy会触发归档。参数如下：

参数	描述
interval	基于filePattern中配置的最小时间单位进行来控制归档频率，默认值为1。如：filePattern中最小时间单位为小时，如果interval=1，则1小时归档一次；如果interval=2，则2小时归档一次。
modulate	默认为false。指明是否对interval进行调节，若modulate为true，会以0为开始对interval进行偏移计算。例如，最小时间粒度为小时，当前为3:00，interval为4，则后面归档时间依次为4:00，8:00，12:00，16:00
maxRandomDelay	指示随机延迟过渡的最大秒数。默认情况下，该值为0，表示没有延迟。此设置在配置了多个应用程序以同时滚动日志文件的服务器上很有用，并且可以在整个时间上分散这样做的负担。

• CronTriggeringPolicy
  基于cron表达式触发归档。此策略由计时器控制，并且与处理日志事件异步，因此上一个或下一个时间段的日志事件可能会出现在当前日志文件的开头或结尾。filePattern属性应包含一个时间戳，否则目标文件将在每次归档时被覆盖。参数如下：

参数	描述
schedule	cron表达式，该表达式与Quartz调度程序中允许的表达式相同。详见CronExpression
EvaluationOnStartup	启动时，将根据文件的最后修改时间戳评估cron表达式。如果cron表达式指示应该在该时间和当前时间之间归档，则文件将立即被归档。

2.3.2.RolloverPolicy

用来控制文件归档方式，目前有两种类型如下：

2.3.2.1.DefaultRolloverStrategy

通过接收filePattern属性中日期/时间模式（%d）和整数（%i）来控制归档方式。如果存在日期/时间模式，则将在归档时使用当前时间替换filePattern中配置的日期/时间部分，如果模式包含整数，则它将在每次归档时递增。如果归档时在模式中同时包含日期/时间和整数，则整数将递增，直到日期/时间部分也将被替换。如果文件模式以“ .gz”，“.zip”，“.bz2”，“.deflate”，“.pack200”或“ .xz”结尾，则将使用与后缀匹配的压缩方案来压缩文件。 bzip2, Deflate, Pack200 and XZ格式要求有Apache Commons Compress组件，另外xz格式还要求有XZ for Java组件。
DefaultRolloverStrategy参数如下：

参数	描述
fileIndex	默认值为max。可选值为：min、max，2.8之后新增nomax。文件归档及新文件创建规则后面介绍。
min	计数器的最小值。预设值为1。
max	计数器的最大值。一旦达到此值，较旧的归档文件将在以后的转换中被删除。预设值为7。
compressionLevel	将压缩级别设置为0-9，其中0 =无，1 =最佳速度，直到9 =最佳压缩。仅针对ZIP文件实现
tempCompressedFilePattern	压缩期间归档日志文件的文件名的模式。

fileIndex设值不同，则文件归档及新文件创建及计数器递增方法都不同，计数器递增有三种方式，如下：

• 方式一：fileIndex值为max
  假设将DefaultRolloverStrategy的min属性设置为1，将max属性设置为3，fileName是“ foo.log”，filePattern是“ foo-％i.log”,归档规则如下：

归档数	当前日志文件	归档文件	描述
0	foo.log	-	所有日志记录都将转到初始文件
1	foo.log	foo-1.log	第一次归档，foo.log重命名为foo-1.log。创建新的foo.log文件并继续写入
2	foo.log	foo-2.log，foo-1.log	第二次归档，foo.log重命名为foo-2.log。创建新的foo.log文件并继续写入
3	foo.log	foo-3.log，foo-2.log，foo-1.log	第三次归档，foo.log重命名为foo-3.log。创建新的foo.log文件并继续写入
4	foo.log	foo-3.log，foo-2.log，foo-1.log	第四次和随后的归档，foo-1.log被删除，foo-2.log被重命名为foo-1.log，foo-3.log被重命名为foo-2.log，foo.log被重命名为foo-3.log。创建新的foo.log文件并继续写入。

• 方式二：fileIndex值为min

假设将DefaultRolloverStrategy的min属性设置为1，将max属性设置为3，fileName是“ foo.log”，filePattern是“ foo-％i.log”,归档规则如下：

归档数	当前日志文件	归档文件	描述
0	foo.log	-	所有日志记录都将转到初始文件
1	foo.log	foo-1.log	第一次归档，foo.log重命名为foo-1.log。创建新的foo.log文件并继续写入
2	foo.log	foo-1.log，foo-2.log	第二次归档，将foo-1.log重命名为foo-2.log，并将foo.log重命名为foo-1.log。创建新的foo.log文件并继续写入
3	foo.log	foo-1.log，foo-2.log，foo-3.log	第三次归档，将foo-2.log重命名为foo-3.log，将foo-1.log重命名为foo-2.log，将foo.log重命名为foo-1.log。创建新的foo.log文件并继续写入
4	foo.log	foo-1.log，foo-2.log，foo-3.log	第四次和随后的归档，删除foo-3.log，将foo-2.log重命名为foo-3.log，将foo-1.log重命名为foo-2.log，将foo.log重命名为foo -1.log。创建新的foo.log文件并继续写入。

• 方式三：fileIndex值为nomax
  nomax为2.8新增属性，设置为nomax时，将忽略DefaultRolloverStrategy的最大值和最小值，每次归档生成的新文件相对于前一个文件编号加1，没有最大文件数限制。

2.3.2.2.DirectWriteRolloverStrategy

将日志事件直接写入由filePattern表示的文件。使用此策略文件不会执行重命名。如果是基于大小的触发策略，将在指定的时间段内写入多个文件，它们从1开始编号，并不断递增直到发生基于时间归档。
注意：如果filePattern的后缀表示应该进行压缩，则在关闭应用程序时不会压缩当前文件。此外，如果时间更改使得filePattern不再与当前文件匹配，则启动时也不会对其进行压缩。
DirectWriteRolloverStrategy模式参数如下：

参数	描述
maxFiles	与文件格式匹配的时间段内允许的最大文件数。如果超出文件数量，则最早的文件将被删除。如果指定，则该值必须大于1。如果该值小于零或省略，则文件数量将不受限制。
compressionLevel	将压缩级别设置为0-9，其中0 =无，1 =最佳速度，直到9 =最佳压缩。仅针对ZIP文件实现。
tempCompressedFilePattern	压缩期间归档日志文件的文件名的模式。

2.3.2.3.归档保留策略

DefaultRolloverStrategy模式下，Log4j-2.5引入了Delete（删除）操作（标签为<delete>），与 max属性所提供的功能相比，Log4j-2.5使用户可以更好地控制在归档时删除哪些文件。删除操作使用户可以配置一个或多个条件，以选择要相对于基本目录删除的文件。

注意：可以删除任何文件，而不仅仅是删除日志文件，因此请谨慎使用此操作！使用testMode参数，可以测试配置，而不会意外删除错误的文件。
delete参数如下：

参数	描述
basePath	必需。从此处开始扫描要删除的文件的基本路径。
maxDepth	要访问的目录的最大级别数。值为0表示仅访问起始文件，除非安全管理器拒绝。Integer.MAX_VALUE的值指示应访问所有级别。默认值为1，表示仅指定基本路径中的文件。
followLinks	是否遵循符号链接。默认为false。
testMode	如果为true，则不会删除文件，而是在INFO级别打印一条消息到状态记录器。使用此功能可以测试配置是否按预期工作。默认为false。
pathSorter	一个实现PathSorter 接口的插件， 用于在选择要删除的文件之前对文件进行排序。默认设置是首先对最近修改的文件进行排序。
pathConditions	如果未指定ScriptCondition，则为必需。 可以指定一个或多个PathCondition元素。如果指定了多个PathCondition元素，则需要所有的PathCondition结果都为true才会进行删除。PathCondition也可以嵌套。如果进行嵌套，则是先判断外层的PathCondition，然后进行内层的判断。如果没有嵌套，则是按顺序进行判断。 也可以创建自定义条件或使用内置条件： IfFileName 如果文件名与此参数匹配则结果为true，此参数为正则表达式或 glob的文件。 IfLastModified 最后修改时间早于或等于此参数则结果为true，此参数为duration。 IfAccumulatedFileCount 文件数超过指定个数则结果为true，此参数为整型。 IfAccumulatedFileSize 所有文件总大小达到此参数则结果为true，此参数为KB、MB、GB。 IfAll 如果此标签下的所有条件都配置成功（逻辑与），则结果为true。 IfAny 如果此标签下的任何一个条件匹配成功（逻辑或），则结果为true。 IfNot 如果此标签下的所有条件都不匹配（逻辑非），则结果为true。
scriptCondition	如果未指定PathConditions，则为必需。指定脚本的ScriptCondition元素。ScriptCondition应该包含一个Script，ScriptRef或ScriptFile元素，该元素指定要执行的逻辑。（有关配置ScriptFiles和ScriptRefs的更多示例，另请参阅ScriptFilter文档。）该脚本传递了许多参数，包括在basePath下找到的路径列表（最大maxDepth），并且必须返回包含要删除的路径的列表。

3.日志归档+日志清理配置demo

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xml>
<Configuration status="WARN">
	<Properties>
		<Property name="logDir">/export/Logs/meeting/</Property>
		<Property name="logFile">gltLog</Property>
	</Properties>

	<Appenders>
		<Console name="STDOUT" target="SYSTEM_ERR">
			<PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} %t %5p [%c:%L] - %m%n" />
		</Console>

		<!--日志名称及归档的压缩包名称及规则-->
		<RollingFile name="RollingFile" fileName="${logDir}/${logFile}.log"
					 filePattern="${logDir}/$${date:yyyy-MM}/${logFile}.%d{yyyy-MM-dd}-%i.log.gz">

			<!--日志输出格式-->
			<PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} %t %5p [%c:%L] - %m%n" />

			<!--满足任何一个policy即进行归档-->
			<Policies>
				<!--当前日志与开始日期不匹配（RollingFile中配置的filePattern中配置的最小时间单位不匹配时）时进行归档-->
				<TimeBasedTriggeringPolicy/>
				<!--文件超过5M进行归档-->
				<SizeBasedTriggeringPolicy size="5 MB" />
			</Policies>

			<!--归档的文件最大数量-->
			<DefaultRolloverStrategy max="10">
				<!--删除规则-->
				<Delete basePath="${logDir}" maxDepth="2">
					<!--匹配文件规则-->
					<IfFileName glob="*.log.gz">
						<IfLastModified age="7d">
							<IfAny>
								<!--logDir下文件总大小超过50M，进行删除-->
								<IfAccumulatedFileSize exceeds="50 MB" />
								<!--logDir下文件总数量超过10，进行删除-->
								<IfAccumulatedFileCount exceeds="10" />
							</IfAny>
						</IfLastModified>
					</IfFileName>
				</Delete>
			</DefaultRolloverStrategy>
		</RollingFile>
	</Appenders>

	<Loggers>
		<Root level="debug">
			<AppenderRef ref="STDOUT" />
			<AppenderRef ref="RollingFile" />
		</Root>
	</Loggers>
</Configuration>

4.总结

log4j 2.x相对于1.x增加了大量的api及高级特性，由于目前很少用到其他appender组件，本文仅仅列了下所有的appender组件的作用，只介绍了几个常用的appender组件，后面用到其他组件在总结吧。