log4j2.x官方文档翻译

最近springboot 1.4项目中用到了log4j2这么个东东，不知道怎么配置就从apache官网找了log4j2的官方文档来看，但是都是英文的，由于自己英文不好，因此就用google翻译了出来，一来是自己看看学习，二来对有需要的同学提供个帮助，不正确的地方欢迎指出。

原文地址：http://logging.apache.org/log4j/2.x/manual/appenders.html

Appenders

Appenders are responsible for delivering LogEvents to their destination. Every Appender must implement the Appender interface. Most Appenders will extend AbstractAppender which adds Lifecycle and Filterable support. Lifecycle allows components to finish initialization after configuration has completed and to perform cleanup during shutdown. Filterable allows the component to have Filters attached to it which are evaluated during event processing.

应用程序负责将LogEvent传递到其目标。 每个Appender必须实现Appender接口。 大多数Appenders将扩展AbstractAppender，它增加了Lifecycle和Filterable支持。 生命周期允许组件在配置完成后完成初始化，并在关闭期间执行清理。 可过滤允许组件具有附加到它的过滤器，它们在事件处理期间被评估。

Appenders usually are only responsible for writing the event data to the target destination. In most cases they delegate responsibility for formatting the event to a layout. Some appenders wrap other appenders so that they can modify the LogEvent, handle a failure in an Appender, route the event to a subordinate Appender based on advanced Filter criteria or provide similar functionality that does not directly format the event for viewing.

附加器通常只负责将事件数据写入目标目标。 在大多数情况下，他们委托将事件格式化为布局的职责。 一些追加器包装其他追加器，以便他们可以修改LogEvent，处理Appender中的失败，根据高级过滤器条件将事件路由到下级Appender，或提供不直接格式化事件以供查看的类似功能。

Appenders always have a name so that they can be referenced from Loggers.

附加器始终具有名称，以便可以从日志记录器引用它们。

AsyncAppender

The AsyncAppender accepts references to other Appenders and causes LogEvents to be written to them on a separate Thread. Note that exceptions while writing to those Appenders will be hidden from the application. The AsyncAppender should be configured after the appenders it references to allow it to shut down properly.

AsyncAppender接受对其他Appender的引用，并导致LogEvents在单独的线程上写入它们。 请注意，写入这些Appenders时的异常将会从应用程序中隐藏。 AsyncAppender应该在其引用的appender之后配置，以允许它正常关闭。

By default, AsyncAppender uses java.util.concurrent.ArrayBlockingQueue which does not require any external libraries. Note that multi-threaded applications should exercise care when using this appender as such: the blocking queue is susceptible to lock contention and our tests showed performance may become worse when more threads are logging concurrently. Consider using lock-free Async Loggers for optimal performance.

默认情况下，AsyncAppender使用java.util.concurrent.ArrayBlockingQueue，它不需要任何外部库。 请注意，多线程应用程序在使用此应用程序时应小心谨慎：阻塞队列容易发生锁争用，我们的测试表明，当更多线程并发记录时，性能可能会变差。 考虑使用无锁的异步记录器以获得最佳性能。

AsyncAppender Parameters

Parameter Name	Type	Description	中文翻译
AppenderRef	String	The name of the Appenders to invoke asynchronously. Multiple AppenderRef elements can be configured.	要异步调用的Appender的名称。 可以配置多个Appender参考元素。
blocking	boolean	If true, the appender will wait until there are free slots in the queue. If false, the event will be written to the error appender if the queue is full. The default is true.	如果为true，则appender将等待，直到队列中有空闲插槽。 如果为false，则如果队列已满，事件将写入错误追加器。 默认值为true。
shutdownTimeout	integer	How many milliseconds the Appender should wait to flush outstanding log events in the queue on shutdown. The default is zero which means to wait forever.	在关闭时，Appender应在等待队列中清除未完成的日志事件多少毫秒。 默认为零，这意味着永远等待。
bufferSize	integer	Specifies the maximum number of events that can be queued. The default is 128. Note that when using a disruptor-style BlockingQueue, this buffer size must be a power of 2.	指定可以排队的事件的最大数量。 默认值为128.请注意，使用disruptor-style BlockingQueue时，此缓冲区大小必须为2的乘方。
errorRef	String	The name of the Appender to invoke if none of the appenders can be called, either due to errors in the appenders or because the queue is full. If not specified then errors will be ignored.	如果由于追加器中的错误或由于队列已满而无法调用任何追加器，则调用的Appender的名称。 如果未指定，则错误将被忽略。
filter	Filter	A Filter to determine if the event should be handled by this Appender. More than one Filter may be used by using a CompositeFilter.	筛选以确定事件是否应由此Appender处理。 通过使用CompositeFilter可以使用多个过滤器。
name	String	The name of the Appender.	Appender的名称。
ignoreExceptions	boolean	The default is true, causing exceptions encountered while appending events to be internally logged and then ignored. When set to false exceptions will be propagated to the caller, instead. You must set this to false when wrapping this Appender in a FailoverAppender.	默认值为true，导致在将事件附加到内部记录然后忽略时遇到异常。 当设置为false时，异常将被传播到调用者。 在FailoverAppender中包装此Appender时，必须将此值设置为false。
includeLocation	boolean	Extracting location is an expensive operation (it can make logging 5 - 20 times slower). To improve performance, location is not included by default when adding a log event to the queue. You can change this by setting includeLocation="true".	提取位置是一个昂贵的操作（它可以使记录慢5 - 20倍）。 为了提高性能，在将日志事件添加到队列时，默认情况下不包括位置。 您可以通过设置includeLocation =“true”来更改此设置。
BlockingQueueFactory	BlockingQueueFactory	This element overrides what type of BlockingQueue to use. See below documentation for more details.	此元素覆盖要使用的BlockingQueue的类型。 有关详细信息，请参阅以下文档。

There are also a few system properties that can be used to maintain application throughput even when the underlying appender cannot keep up with the logging rate and the queue is filling up. See the details for system properties log4j2.AsyncQueueFullPolicy and log4j2.DiscardThreshold.

还有一些系统属性可用于维护应用程序吞吐量，即使底层追加器无法跟上记录速率和队列正在填满。 请参阅系统属性log4j2.AsyncQueueFullPolicy和log4j2.DiscardThreshold的详细信息。

A typical AsyncAppender configuration might look like:

典型的AsyncAppender配置可能如下所示：

  
    
      
        %d %p %c{1.} [%t] %m%n
      
    
    
      
    
  
  
    
      
    
  

Starting in Log4j 2.7, a custom implementation of BlockingQueue or TransferQueue can be specified using a BlockingQueueFactory plugin. To override the default BlockingQueueFactory, specify the plugin inside an element like so:

从Log4j 2.7开始，可以使用BlockingQueueFactory插件指定BlockingQueue或TransferQueue的自定义实现。 要覆盖默认的BlockingQueueFactory，请在元素中指定插件，如下所示：

FailoverAppender

The FailoverAppender wraps a set of appenders. If the primary Appender fails the secondary appenders will be tried in order until one succeeds or there are no more secondaries to try.

故障切换应用程序重复一组追加器。 如果主Appender失败，则二级追加器将按顺序尝试，直到一个成功或没有更多次要尝试。

FailoverAppender Parameters

Parameter Name	Type	Description	中文翻译
filter	Filter	A Filter to determine if the event should be handled by this Appender. More than one Filter may be used by using a CompositeFilter.	筛选以确定事件是否应由此Appender处理。 通过使用CompositeFilter可以使用多个过滤器。
primary	String	The name of the primary Appender to use.	要使用的主要Appender的名称。	故障转移
failovers	String[]	The names of the secondary Appenders to use.	要使用的辅助应用程序的名称。
name	String	The name of the Appender.	Appender的名称。
retryIntervalSeconds	integer	The number of seconds that should pass before retrying the primary Appender. The default is 60.	重试主Appender之前应该经过的秒数。 默认值为60。
ignoreExceptions	boolean	The default is true, causing exceptions encountered while appending events to be internally logged and then ignored. When set to false exceptions will be propagated to the caller, instead.	默认值为true，导致在将事件附加到内部记录然后忽略时遇到异常。 当设置为false时，异常将被传播到调用者。
target	String	Either "SYSTEM_OUT" or "SYSTEM_ERR". The default is "SYSTEM_ERR".	“SYSTEM_OUT”或“SYSTEM ERROR”。 默认值为“SYSTEM ERR”。

A Failover configuration might look like:

故障转移配置可能如下所示：

  
    
      
        %d %p %c{1.} [%t] %m%n
      
      
    
    
      
    
    
      
        
      
    
  
  
    
      
    
  

FileAppender

The FileAppender is an OutputStreamAppender that writes to the File named in the fileName parameter. The FileAppender uses a FileManager (which extends OutputStreamManager) to actually perform the file I/O. While FileAppenders from different Configurations cannot be shared, the FileManagers can be if the Manager is accessible. For example, two web applications in a servlet container can have their own configuration and safely write to the same file if Log4j is in a ClassLoader that is common to both of them.

FileAppender是一个OutputStreamAppender，用于写入fileName参数中指定的文件。 FileAppender使用FileManager（扩展OutputStreamManager）来实际执行文件I / O。 虽然不能共享来自不同配置的FileAppender，但如果管理器可访问，则FileManager可以是。 例如，servlet容器中的两个Web应用程序可以有自己的配置，并且如果Log4j在两个共同的ClassLoader中，则可以安全地写入同一个文件。

FileAppender Parameters

Parameter Name	Type	Description	中文翻译
append	boolean	When true - the default, records will be appended to the end of the file. When set to false, the file will be cleared before new records are written.	当为true时 - 默认情况下，记录将附加到文件的结尾。 当设置为false时，将在写入新记录之前清除文件。
bufferedIO	boolean	When true - the default, records will be written to a buffer and the data will be written to disk when the buffer is full or, if immediateFlush is set, when the record is written. File locking cannot be used with bufferedIO. Performance tests have shown that using buffered I/O significantly improves performance, even if immediateFlush is enabled.	当为true时，默认情况下，记录将被写入缓冲区，并且当缓冲区已满时，或者如果设置了immediateFlush，则在写入记录时将数据写入磁盘。 文件锁定不能与bufferedIO一起使用。 性能测试表明，即使启用了immediateFlush，使用缓冲I / O也能显着提高性能。
bufferSize	int	When bufferedIO is true, this is the buffer size, the default is 8192 bytes.	当bufferedIO为true时，这是缓冲区大小，默认为8192字节。
createOnDemand	boolean	The appender creates the file on-demand. The appender only creates the file when a log event passes all filters and is routed to this appender. Defaults to false.	追加器根据需要创建文件。 追加器仅在日志事件通过所有过滤器并被路由到此追加器时创建文件。 默认为false。
filter	Filter	A Filter to determine if the event should be handled by this Appender. More than one Filter may be used by using a CompositeFilter.	筛选以确定事件是否应由此Appender处理。 通过使用CompositeFilter可以使用多个过滤器。
fileName	String	The name of the file to write to. If the file, or any of its parent directories, do not exist, they will be created.	要写入的文件的名称。 如果文件或其任何父目录不存在，将创建它们。
immediateFlush	boolean	When set to true - the default, each write will be followed by a flush. This will guarantee the data is written to disk but could impact performance.Flushing after every write is only useful when using this appender with synchronous loggers. Asynchronous loggers and appenders will automatically flush at the end of a batch of events, even if immediateFlush is set to false. This also guarantees the data is written to disk but is more efficient.	当设置为true时 - 默认情况下，每次写入后都将进行flush。 这将确保数据写入磁盘，但可能会影响性能。每次写入后刷新仅在同步记录器使用此附加器时有用。 即使immediateFlush设置为false，异步记录器和追加器也将在一批事件结束时自动刷新。 这也保证了数据被写入磁盘，但是更有效率。
layout	Layout	The Layout to use to format the LogEvent. If no layout is supplied the default pattern layout of "%m%n" will be used.	用于格式化LogEvent的布局。 如果没有提供布局，将使用“％m％n”的默认模式布局。
locking	boolean	When set to true, I/O operations will occur only while the file lock is held allowing FileAppenders in multiple JVMs and potentially multiple hosts to write to the same file simultaneously. This will significantly impact performance so should be used carefully. Furthermore, on many systems the file lock is "advisory" meaning that other applications can perform operations on the file without acquiring a lock. The default value is false.	设置为true时，只有在保持文件锁定的情况下才会进行I / O操作，允许多个JVM中的FileAppender和潜在的多个主机同时写入同一文件。 这将显着影响性能，因此应谨慎使用。 此外，在许多系统上，文件锁是“咨询”，意味着其他应用程序可以对文件执行操作而不获取锁。 默认值为false。
name	String	The name of the Appender.	Appender的名称。
ignoreExceptions	boolean	The default is true, causing exceptions encountered while appending events to be internally logged and then ignored. When set to false exceptions will be propagated to the caller, instead. You must set this to false when wrapping this Appender in a FailoverAppender.	默认值为true，导致在将事件附加到内部记录然后忽略时遇到异常。 当设置为false时，异常将被传播到调用者。 在FailoverAppender中包装此Appender时，必须将此值设置为false。

Here is a sample File configuration:

这里是一个示例文件配置：

  
    
      
        %d %p %c{1.} [%t] %m%n
      
    
  
  
    
      
    
  

FlumeAppender

This is an optional component supplied in a separate jar.

Apache Flume is a distributed, reliable, and available system for efficiently collecting, aggregating, and moving large amounts of log data from many different sources to a centralized data store. The FlumeAppender takes LogEvents and sends them to a Flume agent as serialized Avro events for consumption.

The Flume Appender supports three modes of operation.

It can act as a remote Flume client which sends Flume events via Avro to a Flume Agent configured with an Avro Source.
It can act as an embedded Flume Agent where Flume events pass directly into Flume for processing.
It can persist events to a local BerkeleyDB data store and then asynchronously send the events to Flume, similar to the embedded Flume Agent but without most of the Flume dependencies.
Usage as an embedded agent will cause the messages to be directly passed to the Flume Channel and then control will be immediately returned to the application. All interaction with remote agents will occur asynchronously. Setting the "type" attribute to "Embedded" will force the use of the embedded agent. In addition, configuring agent properties in the appender configuration will also cause the embedded agent to be used.

这是在单独的jar中提供的可选组件。

Apache Flume是一个分布式，可靠和可用的系统，用于从大量不同的源有效地收集，聚合和移动大量日志数据到集中式数据存储。 FlumeAppender使用LogEvents并将其作为序列化Avro事件发送到Flume代理以供消费。
Flume Appender支持三种操作模式。
它可以充当远程Flume客户端，通过Avro将Flume事件发送到配置了Avro Source的Flume代理。
它可以充当嵌入式Flume代理，其中Flume事件直接传递到Flume进行处理。
它可以将事件持久化到本地BerkeleyDB数据存储，然后异步发送事件到Flume，类似于嵌入Flume代理，但没有大多数Flume依赖。
作为嵌入式代理的用法将导致消息被直接传递到Flume信道，然后控制将立即返回到应用程序。所有与远程代理的交互都将异步进行。将“type”属性设置为“嵌入”将强制使用嵌入式代理。此外，在追加器配置中配置代理属性还将导致使用嵌入的代理。

FileAppender Parameters

Parameter Name	Type	Description	中文翻译
agents	Agent[]	An array of Agents to which the logging events should be sent. If more than one agent is specified the first Agent will be the primary and subsequent Agents will be used in the order specified as secondaries should the primary Agent fail. Each Agent definition supplies the Agents host and port. The specification of agents and properties are mutually exclusive. If both are configured an error will result.	应向其发送日志记录事件的代理程序数组。 如果指定了多个代理，则第一个代理将是主要代理，如果主要代理失败，则后续代理将以指定的次序使用。 每个代理定义提供代理主机和端口。 代理和属性的规范是相互排斥的。 如果两者都配置，将导致错误。
agentRetries	integer	The number of times the agent should be retried before failing to a secondary. This parameter is ignored when type="persistent" is specified (agents are tried once before failing to the next).	代理在失败之前应重试的次数。 当指定type =“persistent”时将忽略此参数（代理在尝试失败前尝试一次）。
batchSize	integer	Specifies the number of events that should be sent as a batch. The default is 1. This parameter only applies to the Flume Appender.	指定应作为批处理发送的事件数。 默认值为1.此参数仅适用于Flume Appender。
compress	boolean	When set to true the message body will be compressed using gzip	当设置为true时，消息体将使用gzip进行压缩
connectTimeoutMillis	integer	The number of milliseconds Flume will wait before timing out the connection.	Flume在超时连接之前将等待的毫秒数。
dataDir	String	Directory where the Flume write ahead log should be written. Valid only when embedded is set to true and Agent elements are used instead of Property elements.	应写入Flume向前写日志的目录。 仅当embedded设置为true并且使用代理元素而不是Property元素时有效。
filter	Filter	A Filter to determine if the event should be handled by this Appender. More than one Filter may be used by using a CompositeFilter.	筛选以确定事件是否应由此Appender处理。 通过使用CompositeFilter可以使用多个过滤器。
eventPrefix	String	The character string to prepend to each event attribute in order to distinguish it from MDC attributes. The default is an empty string	为每个事件属性预先添加的字符串，以便与MDC属性区分开。 默认值为空字符串。
flumeEventFactory	FlumeEventFactory	Factory that generates the Flume events from Log4j events. The default factory is the FlumeAvroAppender itself.	从Log4j事件生成Flume事件的工厂。 默认工厂是FlumeAvroAppender本身。
layout	Layout	The Layout to use to format the LogEvent. If no layout is specified RFC5424Layout will be used.	用于格式化LogEvent的布局。 如果未指定布局，将使用RFC5424Layout。
lockTimeoutRetries	integer	The number of times to retry if a LockConflictException occurs while writing to Berkeley DB. The default is 5.	写入Berkeley DB时发生LockConflictException时重试的次数。 默认值为5。
maxDelayMillis	integer	The maximum number of milliseconds to wait for batchSize events before publishing the batch.	发布批处理之前等待batchSize事件的最大毫秒数。
mdcExcludes	String	A comma separated list of mdc keys that should be excluded from the FlumeEvent. This is mutually exclusive with the mdcIncludes attribute.	应该从FlumeEvent中排除的mdc键的逗号分隔列表。 这与mdcIncludes属性互斥。
mdcIncludes	String	A comma separated list of mdc keys that should be included in the FlumeEvent. Any keys in the MDC not found in the list will be excluded. This option is mutually exclusive with the mdcExcludes attribute.	应该包含在FlumeEvent中的mdc键的逗号分隔列表。 在列表中找不到的MDC中的任何键将被排除。 此选项与mdcExcludes属性互斥。
mdcRequired	String	A comma separated list of mdc keys that must be present in the MDC. If a key is not present a LoggingException will be thrown.	必须在MDC中存在的mdc键的逗号分隔列表。 如果一个键不存在，将抛出一个LoggingException。
mdcPrefix	String	A string that should be prepended to each MDC key in order to distinguish it from event attributes. The default string is "mdc:".	应该为每个MDC键添加一个字符串，以便将它与事件属性区分开来。 默认字符串为“mdc：”。
name	String	The name of the Appender.	Appender的名称。
properties	Property[]	One or more Property elements that are used to configure the Flume Agent. The properties must be configured without the agent name (the appender name is used for this) and no sources can be configured. Interceptors can be specified for the source using "sources.log4j-source.interceptors". All other Flume configuration properties are allowed. Specifying both Agent and Property elements will result in an error. When used to configure in Persistent mode the valid properties are: "keyProvider" to specify the name of the plugin to provide the secret key for encryption.	用于配置Flume代理的一个或多个Property元素。 必须配置属性，而不使用代理名称（为此使用附加程序名称），并且不能配置任何源。 可以使用“sources.log4j-source.interceptors”为源指定拦截器。 允许所有其他Flume配置属性。 指定代理和属性元素将导致错误。 当用于在持久模式下配置时，有效的属性是：“keyProvider”指定插件的名称，以提供用于加密的密钥。
requestTimeoutMillis	integer	The number of milliseconds Flume will wait before timing out the request.	Flume在超时请求之前将等待的毫秒数。
ignoreExceptions	boolean	The default is true, causing exceptions encountered while appending events to be internally logged and then ignored. When set to false exceptions will be propagated to the caller, instead. You must set this to false when wrapping this Appender in a FailoverAppender.	默认值为true，导致在将事件附加到内部记录然后忽略时遇到异常。 当设置为false时，异常将被传播到调用者。 在FailoverAppender中包装此Appender时，必须将此值设置为false。
type	enumeration	One of "Avro", "Embedded", or "Persistent" to indicate which variation of the Appender is desired.	“Avro”，“Embedded”或“Persistent”之一，用于指示需要Appender的变体。

A sample FlumeAppender configuration that is configured with a primary and a secondary agent, compresses the body, and formats the body using the RFC5424Layout:

使用主代理和辅助代理配置的样本FlumeAppender配置，压缩主体并使用RFC5424Layout格式化主体：

A sample FlumeAppender configuration that is configured with a primary and a secondary agent, compresses the body, formats the body using the RFC5424Layout, and persists encrypted events to disk:

使用主代理和辅助代理配置的示例FlumeAppender配置，压缩正文，使用RFC5424Layout格式化正文，并将加密事件保留到磁盘：

  
    
      
      
      
      MySecretProvider
    
  
  
    
      
    
  

A sample FlumeAppender configuration that is configured with a primary and a secondary agent, compresses the body, formats the body using RFC5424Layout and passes the events to an embedded Flume Agent.

配置有主代理和辅助代理的样本FlumeAppender配置压缩主体，使用RFC5424Layout格式化主体，并将事件传递到嵌入的Flume代理。

A sample FlumeAppender configuration that is configured with a primary and a secondary agent using Flume configuration properties, compresses the body, formats the body using RFC5424Layout and passes the events to an embedded Flume Agent.

使用Flume配置属性配置有主代理和辅助代理的样本FlumeAppender配置压缩主体，使用RFC5424Layout格式化主体，并将事件传递到嵌入的Flume代理。

  
    
      file
      file
      target/file-channel/checkpoint
      target/file-channel/data
      agent1 agent2
      file
      avro
      192.168.10.101
      8800
      100
      file
      avro
      192.168.10.102
      8800
      100
      group1
      agent1 agent2
      failover
      10
      5
      
    
    
      
    
  
  
    
      
    
    
      
    
  

未完，待续