Google Git
Sign in
apache / logging-log4j-site / d0d0de55986756593c08e5d2b8059541eacaf428 / . / log4j-2.0-beta4 / manual / plugins.html
blob: c114275ee3e0f31a8be340efc5078e818dd3f31c [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- Generated by Apache Maven Doxia at Jan 28, 2013 -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>
Log4j 2 Plugins - Apache Log4j 2</title>
<link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="../css/site.css" type="text/css" />
<script type="text/javascript" src="../js/jquery.min.js"></script>
<script type="text/javascript" src="../js/bootstrap.min.js"></script>
<script type="text/javascript" src="../js/prettify.min.js"></script>
<script type="text/javascript" src="../js/site.js"></script>
<meta name="author" content="Ralph Goers" />
<meta name="Date-Revision-yyyymmdd" content="20130128" />
<meta http-equiv="Content-Language" content="en" />
</head>
<body class="composite">
<img class="logo-left" src="../images/ls-logo.jpg" alt="Apache logging services logo" />
<img class="logo-right" src="../images/logo.jpg" alt="Apache log4j logo" />
<div class="clear"></div>
<div class="navbar">
<div class="navbar-inner">
<div class="container-fluid">
<a class="brand" href="http://logging.apache.org/log4j/2.x/">Apache Log4j 2 &trade;</a>
<ul class="nav">
<li>
<a href="http://wiki.apache.org/logging" class="external" target="_blank" title="Logging Wiki">Logging Wiki</a>
</li>
<li>
<a href="http://www.apache.org/" class="external" target="_blank" title="Apache">Apache</a>
</li>
<li>
<a href="../../../" title="Logging Services">Logging Services</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container-fluid">
<table class="layout-table">
<tr>
<td class="sidebar">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-home"></i>Apache Log4j™ 2</li>
<li class="none">
<a href="../index.html" title="About">About</a>
</li>
<li class="none">
<a href="../download.html" title="Download">Download</a>
</li>
<li class="none">
<a href="../build.html" title="Build and Install">Build and Install</a>
</li>
<li class="none">
<a href="../changelog.html" title="Changelog">Changelog</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-book"></i>Manual</li>
<li class="none">
<a href="../manual/index.html" title="Introduction">Introduction</a>
</li>
<li class="none">
<a href="../manual/architecture.html" title="Architecture">Architecture</a>
</li>
<li class="none">
<a href="../manual/migration.html" title="Log4j 1.x Migration">Log4j 1.x Migration</a>
</li>
<li class="collapsed">
<a href="../manual/api.html" title="API">API</a>
</li>
<li class="collapsed">
<a href="../manual/configuration.html" title="Configuration">Configuration</a>
</li>
<li class="expanded active">
<a href="../manual/plugins.html" title="Plugins">Plugins</a>
<ul>
<li class="none">
<a href="../manual/plugins.html#Core" title="Core">Core</a>
</li>
<li class="none">
<a href="../manual/plugins.html#Converters" title="Converters">Converters</a>
</li>
<li class="none">
<a href="../manual/plugins.html#Lookups" title="Lookups">Lookups</a>
</li>
</ul>
</li>
<li class="collapsed">
<a href="../manual/lookups.html" title="Lookups">Lookups</a>
</li>
<li class="collapsed">
<a href="../manual/appenders.html" title="Appenders">Appenders</a>
</li>
<li class="collapsed">
<a href="../manual/layouts.html" title="Layouts">Layouts</a>
</li>
<li class="collapsed">
<a href="../manual/filters.html" title="Filters">Filters</a>
</li>
<li class="none">
<a href="../manual/jmx.html" title="JMX">JMX</a>
</li>
<li class="none">
<a href="../manual/logsep.html" title="Logging Separation">Logging Separation</a>
</li>
<li class="collapsed">
<a href="../manual/extending.html" title="Extending Log4j">Extending Log4j</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-cog"></i>Components</li>
<li class="none">
<a href="../log4j-api/index.html" title="API">API</a>
</li>
<li class="none">
<a href="../log4j-core/index.html" title="Implementation">Implementation</a>
</li>
<li class="none">
<a href="../log4j-jcl/index.html" title="Commons Logging Bridge">Commons Logging Bridge</a>
</li>
<li class="none">
<a href="../log4j-1.2-api/index.html" title="Log4J 1.2 API">Log4J 1.2 API</a>
</li>
<li class="none">
<a href="../log4j-slf4j-impl/index.html" title="SLF4J Binding">SLF4J Binding</a>
</li>
<li class="none">
<a href="../log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter">Log4j 2 to SLF4J Adapter</a>
</li>
<li class="none">
<a href="../log4j-flume-ng/index.html" title="Apache Flume">Apache Flume</a>
</li>
<li class="none">
<a href="../log4j-web/index.html" title="Log4j Web">Log4j Web</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-info-sign"></i>Project Information</li>
<li class="none">
<a href="../dependencies.html" title="Dependencies">Dependencies</a>
</li>
<li class="none">
<a href="../dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a>
</li>
<li class="none">
<a href="../dependency-management.html" title="Dependency Management">Dependency Management</a>
</li>
<li class="none">
<a href="../team-list.html" title="Project Team">Project Team</a>
</li>
<li class="none">
<a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a>
</li>
<li class="none">
<a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
</li>
<li class="none">
<a href="../license.html" title="Project License">Project License</a>
</li>
<li class="none">
<a href="../source-repository.html" title="Source Repository">Source Repository</a>
</li>
<li class="none">
<a href="../project-summary.html" title="Project Summary">Project Summary</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-cog"></i>Project Reports</li>
<li class="none">
<a href="../changes-report.html" title="Changes Report">Changes Report</a>
</li>
<li class="none">
<a href="../jira-report.html" title="JIRA Report">JIRA Report</a>
</li>
<li class="none">
<a href="../surefire-report.html" title="Surefire Report">Surefire Report</a>
</li>
<li class="none">
<a href="../rat-report.html" title="RAT Report">RAT Report</a>
</li>
</ul>
</div>
<div id="poweredBy">
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
<img class="poweredBy" alt="Built by Maven" src="../images/maven-feather.png" />
</a>
</div>
</td>
<td class="content">
<!-- 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
http://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. -->
<div class="section"><h2>Plugins<a name="Plugins"></a></h2>
<a name="Introduction"></a>
<div class="section"><h3>Introduction<a name="Introduction"></a></h3>
<p>
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 of
goals of Log4j 2 is to make extending it extremely easy through the use of plugins.
</p>
<p>
In Log4j 2 a plugin is declared by adding a Plugin annotation to the class declaration. During
initialization the Configuration will invoke the PluginManager to locate all the Log4j plugins
that are located in the declared <a href="./configuration.html#ConfigurationSyntax">packages</a>.
As the configuration is processed the appropriate plugins will be automatically configured and
initialized. Log4j 2 utilizes a few different types of plugins which are described in the follownig
sections.
</p>
</div>
<a name="Core"></a>
<div class="section"><h3>Core<a name="Core"></a></h3>
<p>
Core plugins are those that are directly represented by an element in a configuration file, such as an
Appender, 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.
</p>
<p>
Every Core plugin must declare a static method that is marked with a PluginFactory annotation. 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.
</p>
<div class="section"><h4>Attribute Types<a name="Attribute_Types"></a></h4>
<dl>
<dt>PluginAttr</dt>
<dd>The parameter must resolve to a String, although it can be the String representation of a
boolean. numeric value, or any other Object that can be created from a String value.</dd>
<dt>PluginElement</dt>
<dd>The parameter may represent a complex object that itself has parameters that can be configured.</dd>
<dt>PluginConfiguration</dt>
<dd>The current Configuration object will be passed to the plugin as a parameter.</dd>
</dl>
</div></div>
<a name="Converters"></a>
<div class="section"><h3>Converters<a name="Converters"></a></h3>
<p>
Converters are used by
<a href="../log4j-core/apidocs/org/apache/logging/log4j/core/layout/PatternLayout.html">PatternLayout</a>
to render the elements identified by the conversion pattern. Every converter must specify its type as
&quot;Converter&quot; on the Plugin attribute, have a static newInstance method that accepts an array of Strings 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 LogEvents must extend the 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.
</p>
<p>
A second type of Converter is the FileConverter - which must have &quot;FileConverter&quot; specified in the
type 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 Objects 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.
</p>
</div>
<a name="Lookups"></a>
<div class="section"><h3>Lookups<a name="Lookups"></a></h3>
<p>
Lookups are perhaps the simplest plugins of all. They must declare their type as &quot;Lookup&quot; on the
plugin annotation and must implement the 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 ${<i>name</i>:key} where <i>name</i> is the name specified in the Plugin annotation and
key is the name of the item to locate.
</p>
</div>
<a name="Plugin_Preloading"></a>
<div class="section"><h3>Plugin Preloading<a name="Plugin_Preloading"></a></h3>
Scanning for annotated classes dynamically takes a bit of time during application initialization. Log4j
avoids this by scanning its classes during the build. In the Maven build, the PluginManager is invoked as
shown below and then the resulting Map is stored in a file in the jar being constructed. Log4j will locate
all the files created this way and and preload them, which shortens startup time considerably. Adding the
following plugin definition to your project's pom.xml will cause the plugin manager to be called during the
build. It will store the resulting file in the correct location under the directory specified in the first
argument after scanning all the components located under the package specified in the second argument.
<div class="prettyprint linenums"><pre>&lt;plugin&gt;
&lt;groupId&gt;org.codehaus.mojo&lt;/groupId&gt;
&lt;artifactId&gt;exec-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;1.2.1&lt;/version&gt;
&lt;executions&gt;
&lt;execution&gt;
&lt;phase&gt;process-classes&lt;/phase&gt;
&lt;goals&gt;
&lt;goal&gt;java&lt;/goal&gt;
&lt;/goals&gt;
&lt;/execution&gt;
&lt;/executions&gt;
&lt;configuration&gt;
&lt;mainClass&gt;org.apache.logging.log4j.core.config.plugins.PluginManager&lt;/mainClass&gt;
&lt;arguments&gt;
&lt;argument&gt;${project.build.outputDirectory}&lt;/argument&gt;
&lt;argument&gt;org.myorg.myproject.log4j&lt;/argument&gt;
&lt;/arguments&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</pre></div>
</div>
</div>
</td>
</tr>
</table>
</div>
<div class="footer">
<p>Copyright &copy; 1999-2013 <a class="external" href="http://www.apache.org">Apache Software Foundation</a>. All Rights Reserved.</p>
<p>Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p>
<p>Site powered by <a class="external" href="http://twitter.github.com/bootstrap/">Twitter Bootstrap</a>. Icons from <a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p>
</div>
</div>
</body>
</html>