| <!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 Jun 9, 2012 |
| | Rendered using Apache Maven Fluido Skin |
| --> |
| <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" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <title> |
| Log4j 2 Plugins</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| |
| |
| <script type="text/javascript" src="../js/apache-maven-fluido.min.js"></script> |
| |
| |
| <meta name="author" content="Ralph Goers" /> |
| <meta name="Date-Revision-yyyymmdd" content="20120609" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| |
| </head> |
| <body class="topBarDisabled"> |
| |
| |
| |
| |
| <div class="container-fluid"> |
| <div id="banner"> |
| <div class="pull-left"> |
| <a href="../../../" id="bannerLeft"> |
| <img src="../images/ls-logo.jpg" alt="Apache Logging Services™"/> |
| </a> |
| </div> |
| <div class="pull-right"> <div id="bannerRight"> |
| <img src="../images/logo.jpg" /> |
| </div> |
| </div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| |
| |
| <li id="publishDate">Last Published: 2012-06-09</li> |
| <li class="divider">|</li> <li id="projectVersion">Version: 2.0-alpha1-SNAPSHOT</li> |
| |
| |
| |
| |
| |
| <li class="pull-right"> <a href="http://wiki.apache.org/logging" class="externalLink" title="Logging Wiki">Logging Wiki</a> |
| </li> |
| |
| <li class="divider pull-right">|</li> |
| |
| <li class="pull-right"> <a href="http://www.apache.org/" class="externalLink" title="Apache">Apache</a> |
| </li> |
| |
| <li class="divider pull-right">|</li> |
| |
| <li class="pull-right"> <a href="../../../" title="Logging Services">Logging Services</a> |
| </li> |
| |
| <li class="divider pull-right">|</li> |
| |
| <li class="pull-right"> <a href="../../" title="Log4j">Log4j</a> |
| </li> |
| |
| <li class="divider pull-right">|</li> |
| |
| <li class="pull-right"> <a href="../../companions" title="Log4j Companions">Log4j Companions</a> |
| </li> |
| |
| </ul> |
| </div> |
| |
| <div class="row-fluid"> |
| <div id="leftColumn" class="span3"> |
| <div class="well sidebar-nav"> |
| |
| |
| <h3>Apache Log4j™ 2</h3> |
| <ul> |
| <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> |
| <h3>Manual</h3> |
| <ul> |
| <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="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"> |
| <strong>Plugins</strong> |
| <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> |
| <h3>Logging Adapters</h3> |
| <ul> |
| <li class="none"> |
| <a href="../log4j12-api/api.html" title="Log4j 1.x API">Log4j 1.x API</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j2-jcl/api.html" title="Commons Logging">Commons Logging</a> |
| </li> |
| <li class="none"> |
| <a href="../slf4j-impl/api.html" title="SLF4J">SLF4J</a> |
| </li> |
| </ul> |
| <h3>Components</h3> |
| <ul> |
| <li class="none"> |
| <a href="../log4j-api/index.html" title="API">API</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-core/index.html" title="Impl">Impl</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j12-api/index.html" title="Log4J 1.2 API">Log4J 1.2 API</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="../slf4j-impl/index.html" title="SLF4J Binding">SLF4J Binding</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-flume-og/index.html" title="Flume OG">Flume OG</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-flume-ng/index.html" title="Flume NG">Flume NG</a> |
| </li> |
| </ul> |
| <h3>Project Documentation</h3> |
| <ul> |
| <li class="collapsed"> |
| <a href="../project-info.html" title="Project Information">Project Information</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../project-reports.html" title="Project Reports">Project Reports</a> |
| </li> |
| </ul> |
| |
| |
| |
| <hr class="divider" /> |
| |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img class="poweredBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /> |
| </a> |
| </div> |
| </div> |
| </div> |
| |
| <div id="bodyColumn" class="span9" > |
| |
| <!-- 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="../log4j2-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 |
| "Converter" 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 "FileConverter" 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 "Lookup" 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> |
| </div> |
| |
| |
| </div> |
| </div> |
| |
| <hr/> |
| |
| <footer> |
| <div class="container-fluid"> |
| <div class="row span16">Copyright © 1999-2012 |
| <a href="http://www.apache.org">Apache Software Foundation</a>. |
| All Rights Reserved. |
| |
| </div> |
| |
| |
| |
| </div> |
| </footer> |
| </body> |
| </html> |