src/site/asciidoc/manual/plugins.adoc - logging-log4j2 - Git at Google

 ////
     Licensed to the Apache Software Foundation (ASF) under one or more
     contributor license agreements. See the NOTICE file distributed with
     this work for additional information regarding copyright ownership.
     The ASF licenses this file to You under the Apache License, Version 2.0
     (the "License"); you may not use this file except in compliance with
     the License. You may obtain a copy of the License at

         https://www.apache.org/licenses/LICENSE-2.0

     Unless required by applicable law or agreed to in writing, software
     distributed under the License is distributed on an "AS IS" BASIS,
     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     See the License for the specific language governing permissions and
     limitations under the License.
 ////
 = Plugins
 Ralph Goers <rgoers@apache.org>; Matt Sicker <mattsicker@apache.org>

 Log4j 1.x allowed for extension by requiring class attributes on most of
 the configuration declarations. In the case of some elements, notably
 the PatternLayout, the only way to add new pattern converters was to
 extend the PatternLayout class and add them via code. One goal of Log4j
 2 is to make extending it extremely easy through the use of plugins.

 In Log4j 2 a plugin is declared by adding a
 link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/Plugin.html[`@Plugin`]
 annotation to the class declaration. During initialization the
 link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/Configuration.html[`Configuration`]
 will invoke the
 link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/util/PluginManager.html[`PluginManager`]
 to load the built-in Log4j plugins as well as any custom plugins. The
 `PluginManager` locates plugins by looking in five places:

 1.  Serialized plugin listing files on the classpath. These files are
 generated automatically during the build (more details below).
 2.  (OSGi only) Serialized plugin listing files in each active OSGi
 bundle. A `BundleListener` is added on activation to continue checking
 new bundles after `log4j-core` has started.
 3.  A comma-separated list of packages specified by the
 `log4j.plugin.packages` system property.
 4.  Packages passed to the static `PluginManager.addPackages` method
 (before Log4j configuration occurs).
 5.  The link:./configuration.html#ConfigurationSyntax[packages] declared
 in your log4j2 configuration file.

 If multiple Plugins specify the same (case-insensitive) `name`, then the
 load order above determines which one will be used. For example, to
 override the `File` plugin which is provided by the built-in
 `FileAppender` class, you would need to place your plugin in a JAR file
 in the CLASSPATH ahead of`log4j-core.jar`. This is not recommended;
 plugin name collisions will cause a warning to be emitted. Note that in
 an OSGi environment, the order that bundles are scanned for plugins
 generally follows the same order that bundles were installed into the
 framework. See
 http://www.osgi.org/javadoc/r5/core/org/osgi/framework/BundleContext.html#getBundles()[`getBundles()`]
 and
 http://www.osgi.org/javadoc/r5/core/org/osgi/framework/SynchronousBundleListener.html[`SynchronousBundleListener`].
 In short, name collisions are even more unpredictable in an OSGi environment.
 ////
 TODO: in future, plugins will be able to be annotated with @Order which can override priorities
 ////

 Serialized plugin listing files are generated by an annotation processor
 contained in the log4j-core artifact which will automatically scan your
 code for Log4j 2 plugins and output a metadata file in your processed
 classes. There is nothing extra that needs to be done to enable this;
 the Java compiler will automatically pick up the annotation processor on
 the class path unless you explicitly disable it. In that case, it would
 be important to add another compiler pass to your build process that
 only handles annotation processing using the Log4j 2 annotation
 processor class,
 `org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor`.
 To do this using Apache Maven, add the following execution to your
 _maven-compiler-plugin_ (version 2.2 or higher) build plugin:

 [source,xml]
 ----
 <plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-compiler-plugin</artifactId>
   <version>3.1</version>
   <executions>
     <execution>
       <id>log4j-plugin-processor</id>
       <goals>
         <goal>compile</goal>
       </goals>
       <phase>process-classes</phase>
       <configuration>
         <proc>only</proc>
         <annotationProcessors>
           <annotationProcessor>org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor</annotationProcessor>
         </annotationProcessors>
       </configuration>
     </execution>
   </executions>
 </plugin>
 ----

 As the configuration is processed the appropriate plugins will be
 automatically configured and initialized. Log4j 2 utilizes a few
 different categories of plugins which are described in the following
 sections.

 [#Core]
 == Core

 Core plugins are those that are directly represented by an element in a
 configuration file, such as an Appender, Layout, Logger or Filter.
 Custom plugins that conform to the rules laid out in the next paragraph
 may simply be referenced in the configuration, provided they are
 appropriate configured to be loaded by the PluginManager.

 Every Core plugin must declare a static method annotated with
 `@PluginFactory` or `@PluginBuilderFactory`. The former is used for
 static factory methods that provide all options as method parameters,
 and the latter is used to construct a new `Builder<T>` class whose
 fields are used for injecting attributes and child nodes. To allow the
 `Configuration` to pass the correct parameters to the method, every
 parameter to the method must be annotated as one of the following
 attribute types. Each attribute or element annotation must include the
 name that must be present in the configuration in order to match the
 configuration item to its respective parameter. For plugin builders, the
 names of the fields will be used by default if no name is specified in
 the annotation. There are dozens of plugins in Log4j Core that can be
 used as examples for more complex scenarios including hierarchical
 builder classes (e.g., see `FileAppender`). See
 link:extending.html#Plugin_Builders[Extending Log4j with Plugin
 Builders] for more details.

 === Attribute Types

 link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginAttribute.html[`PluginAttribute`]::
   The parameter must be convertible from a String using a
   link:#TypeConverters[TypeConverter]. Most built-in types are already
   supported, but custom `TypeConverter` plugins may also be provided for
   more type support. Note that `PluginBuilderAttribute` can be used in
   builder class fields as an easier way to provide default values.
 link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginElement.html[`PluginElement`]::
   The parameter may represent a complex object that itself has
   parameters that can be configured. This also supports injecting an
   array of elements.
 link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginConfiguration.html[`PluginConfiguration`]::
   The current `Configuration` object will be passed to the plugin as a
   parameter.
 link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginNode.html[`PluginNode`]::
   The current `Node` being parsed will be passed to the plugin as a
   parameter.
 link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginValue.html[`PluginValue`]::
   The value of the current `Node` or its attribute named `value`.

 === Constraint Validators

 Plugin factory fields and parameters can be automatically validated at
 runtime using constraint validators inspired by the
 http://beanvalidation.org/[Bean Validation spec]. The following
 annotations are bundled in Log4j, but custom
 link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/ConstraintValidator.html[`ConstraintValidators`]
 can be created as well.

 link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/Required.html[`Required`]::
   This annotation validates that a value is non-empty. This covers a
   check for `null` as well as several other scenarios: empty
   `CharSequence` objects, empty arrays, empty `Collection` instances,
   and empty `Map` instances.
 link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/ValidHost.html[`ValidHost`]::
   This annotation validates that a value corresponds to a valid
   hostname. This uses the same validation as
   http://docs.oracle.com/javase/8/docs/api/java/net/InetAddress.html#getByName-java.lang.String-[`InetAddress::getByName`].
 link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/ValidPort.html[`ValidPort`]::
   This annotation validates that a value corresponds to a valid port
   number between 0 and 65535.

 [#Converters]
 == Converters

 Converters are used by
 link:../log4j-core/apidocs/org/apache/logging/log4j/core/layout/PatternLayout.html[`PatternLayout`]
 to render the elements identified by the conversion pattern. Every
 converter must specify its category as "Converter" on the `@Plugin`
 annotation, have a static `newInstance` method that accepts an array of
 `String` as its only parameter and returns an instance of the
 Converter, and must have a `@ConverterKeys` annotation present that
 contains the array of converter patterns that will cause the Converter
 to be selected. Converters that are meant to handle `LogEvent` must
 extend the
 link:../log4j-core/apidocs/org/apache/logging/log4j/core/layout/LogEventPatternConverter.html[`LogEventPatternConverter`]
 class and must implement a format method that accepts a `LogEvent` and a
 `StringBuilder` as arguments. The Converter should append the result of
 its operation to the `StringBuilder`.

 A second type of Converter is the FileConverter - which must have
 "FileConverter" specified in the category attribute of the `@Plugin`
 annotation. While similar to a `LogEventPatternConverter`, instead of a
 single format method these Converters will have two variations; one that
 takes an `Object` and one that takes an array of `Object` instead of
 the `LogEvent`. Both append to the provided `StringBuilder` in the same
 fashion as a `LogEventPatternConverter`. These Converters are typically
 used by the `RollingFileAppender` to construct the name of the file to
 log to.

 If multiple Converters specify the same `ConverterKeys`, then the load
 order above determines which one will be used. For example, to override
 the `%date` converter which is provided by the built-in
 `DatePatternConverter` class, you would need to place your plugin in a
 JAR file in the CLASSPATH ahead of`log4j-core.jar`. This is not
 recommended; pattern ConverterKeys collisions will cause a warning to be
 emitted. Try to use unique ConverterKeys for your custom pattern
 converters.

 [#KeyProviders]
 == KeyProviders

 Some components within Log4j may provide the ability to perform data
 encryption. These components require a secret key to perform the
 encryption. Applications may provide the key by creating a class that
 implements the
 link:../log4j-core/apidocs/org/apache/logging/log4j/core/util/SecretKeyProvider.html[`SecretKeyProvider`]
 interface.

 [#Lookups]
 == Lookups

 Lookups are perhaps the simplest plugins of all. They must declare their
 type as "Lookup" on the plugin annotation and must implement the
 link:../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/StrLookup.html[`StrLookup`]
 interface. They will have two methods; a `lookup` method that accepts a
 `String` key and returns a `String` value and a second `lookup` method that
 accepts both a `LogEvent` and a `String` key and returns a `String`. Lookups
 may be referenced by specifying $\{name:key} where name is the name
 specified in the Plugin annotation and key is the name of the item to
 locate.

 [#TypeConverters]
 == TypeConverters

 link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/convert/TypeConverter.html[`TypeConverter`]s
 are a sort of meta-plugin used for converting strings into other types
 in a plugin factory method parameter. Other plugins can already be
 injected via the `@PluginElement` annotation; now, any type supported by
 the type conversion system can be used in a `@PluginAttribute`
 parameter. Conversion of enum types are supported on demand and do not
 require custom `TypeConverter` classes. A large number of built-in Java
 classes are already supported; see
 link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/convert/TypeConverters.html[`TypeConverters`]
 for a more exhaustive listing.

 Unlike other plugins, the plugin name of a `TypeConverter` is purely
 cosmetic. Appropriate type converters are looked up via the `Type`
 interface rather than via `Class<?>` objects only. Do note that
 `TypeConverter` plugins must have a default constructor.

 [#DeveloperNotes]
 == Developer Notes

 If a plugin class implements
 http://docs.oracle.com/javase/6/docs/api/java/util/Collection.html[`Collection`]
 or http://docs.oracle.com/javase/6/docs/api/java/util/Map.html[`Map`],
 then no factory method is used. Instead, the class is instantiated using
 the default constructor, and all child configuration nodes are added to
 the `Collection` or `Map`.
	////
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	https://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	////
	= Plugins
	Ralph Goers <rgoers@apache.org>; Matt Sicker <mattsicker@apache.org>

	Log4j 1.x allowed for extension by requiring class attributes on most of
	the configuration declarations. In the case of some elements, notably
	the PatternLayout, the only way to add new pattern converters was to
	extend the PatternLayout class and add them via code. One goal of Log4j
	2 is to make extending it extremely easy through the use of plugins.

	In Log4j 2 a plugin is declared by adding a
	link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/Plugin.html[`@Plugin`]
	annotation to the class declaration. During initialization the
	link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/Configuration.html[`Configuration`]
	will invoke the
	link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/util/PluginManager.html[`PluginManager`]
	to load the built-in Log4j plugins as well as any custom plugins. The
	`PluginManager` locates plugins by looking in five places:

	1. Serialized plugin listing files on the classpath. These files are
	generated automatically during the build (more details below).
	2. (OSGi only) Serialized plugin listing files in each active OSGi
	bundle. A `BundleListener` is added on activation to continue checking
	new bundles after `log4j-core` has started.
	3. A comma-separated list of packages specified by the
	`log4j.plugin.packages` system property.
	4. Packages passed to the static `PluginManager.addPackages` method
	(before Log4j configuration occurs).
	5. The link:./configuration.html#ConfigurationSyntax[packages] declared
	in your log4j2 configuration file.

	If multiple Plugins specify the same (case-insensitive) `name`, then the
	load order above determines which one will be used. For example, to
	override the `File` plugin which is provided by the built-in
	`FileAppender` class, you would need to place your plugin in a JAR file
	in the CLASSPATH ahead of`log4j-core.jar`. This is not recommended;
	plugin name collisions will cause a warning to be emitted. Note that in
	an OSGi environment, the order that bundles are scanned for plugins
	generally follows the same order that bundles were installed into the
	framework. See
	http://www.osgi.org/javadoc/r5/core/org/osgi/framework/BundleContext.html#getBundles()[`getBundles()`]
	and
	http://www.osgi.org/javadoc/r5/core/org/osgi/framework/SynchronousBundleListener.html[`SynchronousBundleListener`].
	In short, name collisions are even more unpredictable in an OSGi environment.
	////
	TODO: in future, plugins will be able to be annotated with @Order which can override priorities
	////

	Serialized plugin listing files are generated by an annotation processor
	contained in the log4j-core artifact which will automatically scan your
	code for Log4j 2 plugins and output a metadata file in your processed
	classes. There is nothing extra that needs to be done to enable this;
	the Java compiler will automatically pick up the annotation processor on
	the class path unless you explicitly disable it. In that case, it would
	be important to add another compiler pass to your build process that
	only handles annotation processing using the Log4j 2 annotation
	processor class,
	`org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor`.
	To do this using Apache Maven, add the following execution to your
	_maven-compiler-plugin_ (version 2.2 or higher) build plugin:

	[source,xml]
	----
	<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-compiler-plugin</artifactId>
	<version>3.1</version>
	<executions>
	<execution>
	<id>log4j-plugin-processor</id>
	<goals>
	<goal>compile</goal>
	</goals>
	<phase>process-classes</phase>
	<configuration>
	<proc>only</proc>
	<annotationProcessors>
	<annotationProcessor>org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor</annotationProcessor>
	</annotationProcessors>
	</configuration>
	</execution>
	</executions>
	</plugin>
	----

	As the configuration is processed the appropriate plugins will be
	automatically configured and initialized. Log4j 2 utilizes a few
	different categories of plugins which are described in the following
	sections.

	[#Core]
	== Core

	Core plugins are those that are directly represented by an element in a
	configuration file, such as an Appender, Layout, Logger or Filter.
	Custom plugins that conform to the rules laid out in the next paragraph
	may simply be referenced in the configuration, provided they are
	appropriate configured to be loaded by the PluginManager.

	Every Core plugin must declare a static method annotated with
	`@PluginFactory` or `@PluginBuilderFactory`. The former is used for
	static factory methods that provide all options as method parameters,
	and the latter is used to construct a new `Builder<T>` class whose
	fields are used for injecting attributes and child nodes. To allow the
	`Configuration` to pass the correct parameters to the method, every
	parameter to the method must be annotated as one of the following
	attribute types. Each attribute or element annotation must include the
	name that must be present in the configuration in order to match the
	configuration item to its respective parameter. For plugin builders, the
	names of the fields will be used by default if no name is specified in
	the annotation. There are dozens of plugins in Log4j Core that can be
	used as examples for more complex scenarios including hierarchical
	builder classes (e.g., see `FileAppender`). See
	link:extending.html#Plugin_Builders[Extending Log4j with Plugin
	Builders] for more details.

	=== Attribute Types

	link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginAttribute.html[`PluginAttribute`]::
	The parameter must be convertible from a String using a
	link:#TypeConverters[TypeConverter]. Most built-in types are already
	supported, but custom `TypeConverter` plugins may also be provided for
	more type support. Note that `PluginBuilderAttribute` can be used in
	builder class fields as an easier way to provide default values.
	link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginElement.html[`PluginElement`]::
	The parameter may represent a complex object that itself has
	parameters that can be configured. This also supports injecting an
	array of elements.
	link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginConfiguration.html[`PluginConfiguration`]::
	The current `Configuration` object will be passed to the plugin as a
	parameter.
	link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginNode.html[`PluginNode`]::
	The current `Node` being parsed will be passed to the plugin as a
	parameter.
	link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginValue.html[`PluginValue`]::
	The value of the current `Node` or its attribute named `value`.

	=== Constraint Validators

	Plugin factory fields and parameters can be automatically validated at
	runtime using constraint validators inspired by the
	http://beanvalidation.org/[Bean Validation spec]. The following
	annotations are bundled in Log4j, but custom
	link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/ConstraintValidator.html[`ConstraintValidators`]
	can be created as well.

	link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/Required.html[`Required`]::
	This annotation validates that a value is non-empty. This covers a
	check for `null` as well as several other scenarios: empty
	`CharSequence` objects, empty arrays, empty `Collection` instances,
	and empty `Map` instances.
	link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/ValidHost.html[`ValidHost`]::
	This annotation validates that a value corresponds to a valid
	hostname. This uses the same validation as
	http://docs.oracle.com/javase/8/docs/api/java/net/InetAddress.html#getByName-java.lang.String-[`InetAddress::getByName`].
	link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/ValidPort.html[`ValidPort`]::
	This annotation validates that a value corresponds to a valid port
	number between 0 and 65535.

	[#Converters]
	== Converters

	Converters are used by
	link:../log4j-core/apidocs/org/apache/logging/log4j/core/layout/PatternLayout.html[`PatternLayout`]
	to render the elements identified by the conversion pattern. Every
	converter must specify its category as "Converter" on the `@Plugin`
	annotation, have a static `newInstance` method that accepts an array of
	`String` as its only parameter and returns an instance of the
	Converter, and must have a `@ConverterKeys` annotation present that
	contains the array of converter patterns that will cause the Converter
	to be selected. Converters that are meant to handle `LogEvent` must
	extend the
	link:../log4j-core/apidocs/org/apache/logging/log4j/core/layout/LogEventPatternConverter.html[`LogEventPatternConverter`]
	class and must implement a format method that accepts a `LogEvent` and a
	`StringBuilder` as arguments. The Converter should append the result of
	its operation to the `StringBuilder`.

	A second type of Converter is the FileConverter - which must have
	"FileConverter" specified in the category attribute of the `@Plugin`
	annotation. While similar to a `LogEventPatternConverter`, instead of a
	single format method these Converters will have two variations; one that
	takes an `Object` and one that takes an array of `Object` instead of
	the `LogEvent`. Both append to the provided `StringBuilder` in the same
	fashion as a `LogEventPatternConverter`. These Converters are typically
	used by the `RollingFileAppender` to construct the name of the file to
	log to.

	If multiple Converters specify the same `ConverterKeys`, then the load
	order above determines which one will be used. For example, to override
	the `%date` converter which is provided by the built-in
	`DatePatternConverter` class, you would need to place your plugin in a
	JAR file in the CLASSPATH ahead of`log4j-core.jar`. This is not
	recommended; pattern ConverterKeys collisions will cause a warning to be
	emitted. Try to use unique ConverterKeys for your custom pattern
	converters.

	[#KeyProviders]
	== KeyProviders

	Some components within Log4j may provide the ability to perform data
	encryption. These components require a secret key to perform the
	encryption. Applications may provide the key by creating a class that
	implements the
	link:../log4j-core/apidocs/org/apache/logging/log4j/core/util/SecretKeyProvider.html[`SecretKeyProvider`]
	interface.

	[#Lookups]
	== Lookups

	Lookups are perhaps the simplest plugins of all. They must declare their
	type as "Lookup" on the plugin annotation and must implement the
	link:../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/StrLookup.html[`StrLookup`]
	interface. They will have two methods; a `lookup` method that accepts a
	`String` key and returns a `String` value and a second `lookup` method that
	accepts both a `LogEvent` and a `String` key and returns a `String`. Lookups
	may be referenced by specifying $\{name:key} where name is the name
	specified in the Plugin annotation and key is the name of the item to
	locate.

	[#TypeConverters]
	== TypeConverters

	link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/convert/TypeConverter.html[`TypeConverter`]s
	are a sort of meta-plugin used for converting strings into other types
	in a plugin factory method parameter. Other plugins can already be
	injected via the `@PluginElement` annotation; now, any type supported by
	the type conversion system can be used in a `@PluginAttribute`
	parameter. Conversion of enum types are supported on demand and do not
	require custom `TypeConverter` classes. A large number of built-in Java
	classes are already supported; see
	link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/convert/TypeConverters.html[`TypeConverters`]
	for a more exhaustive listing.

	Unlike other plugins, the plugin name of a `TypeConverter` is purely
	cosmetic. Appropriate type converters are looked up via the `Type`
	interface rather than via `Class<?>` objects only. Do note that
	`TypeConverter` plugins must have a default constructor.

	[#DeveloperNotes]
	== Developer Notes

	If a plugin class implements
	http://docs.oracle.com/javase/6/docs/api/java/util/Collection.html[`Collection`]
	or http://docs.oracle.com/javase/6/docs/api/java/util/Map.html[`Map`],
	then no factory method is used. Instead, the class is instantiated using
	the default constructor, and all child configuration nodes are added to
	the `Collection` or `Map`.