Author: rgoers
Date: Mon Sep 17 07:11:45 2012
New Revision: 1386490
URL: http://svn.apache.org/viewvc?rev=1386490&view=rev
Log:
Update documentation
Added:
logging/log4j/log4j2/trunk/src/site/xdoc/manual/migration.xml
- copied, changed from r1382400,
logging/log4j/log4j2/trunk/src/site/xdoc/manual/api.xml
Modified:
logging/log4j/log4j2/trunk/src/changes/changes.xml
logging/log4j/log4j2/trunk/src/site/site.xml
logging/log4j/log4j2/trunk/src/site/xdoc/manual/appenders.xml
Modified: logging/log4j/log4j2/trunk/src/changes/changes.xml
URL:
http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/changes/changes.xml?rev=1386490&r1=1386489&r2=1386490&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/src/changes/changes.xml (original)
+++ logging/log4j/log4j2/trunk/src/changes/changes.xml Mon Sep 17 07:11:45 2012
@@ -22,7 +22,10 @@
</properties>
<body>
- <release version="2.0-alpha3" date="TBD" description="">
+ <release version="2.0-alpha3" date="2012-09-17" description="Bug fixes and
enhancements">
+ <action dev="rgoers" type="add">
+ Added AsynchAppender.
+ </action>
<action issue="LOG4J-81" dev="rgoers" type="fix">
PatternLayout was not honoring format modifiers.
</action>
Modified: logging/log4j/log4j2/trunk/src/site/site.xml
URL:
http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/site.xml?rev=1386490&r1=1386489&r2=1386490&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/src/site/site.xml (original)
+++ logging/log4j/log4j2/trunk/src/site/site.xml Mon Sep 17 07:11:45 2012
@@ -46,6 +46,7 @@
<menu name="Manual" inherit="top">
<item name="Introduction" href="/manual/index.html"/>
<item name="Architecture" href="/manual/architecture.html"/>
+ <item name="Log4j 1.x Migration" href="manual/migration.html"/>
<item name="API" href="/manual/api.html" collapse="true">
<item name="Overview" href="manual/api.html#Overview"/>
<item name="Flow Tracing" href="manual/flowtracing.html"/>
Modified: logging/log4j/log4j2/trunk/src/site/xdoc/manual/appenders.xml
URL:
http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/xdoc/manual/appenders.xml?rev=1386490&r1=1386489&r2=1386490&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/src/site/xdoc/manual/appenders.xml (original)
+++ logging/log4j/log4j2/trunk/src/site/xdoc/manual/appenders.xml Mon Sep 17
07:11:45 2012
@@ -45,6 +45,83 @@
<p>
Appenders always have a name so that they can be referenced from
Loggers.
</p>
+ <a name="AsynchAppender"/>
+ <subsection name="AsynchAppender">
+ <p>The AsynchAppender 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. </p>
+ <table border="1" width="100%">
+ <tr>
+ <th>Parameter Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>appender-ref</td>
+ <td>String</td>
+ <td>The name of the Appenders to invoke asynchronously. Multiple
appender-ref
+ elements can be configured.</td>
+ </tr>
+ <tr>
+ <td>blocking</td>
+ <td>boolean</td>
+ <td>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.</td>
+ </tr>
+ <tr>
+ <td>bufferSize</td>
+ <td>integer</td>
+ <td>Specifies the maximum number of events that can be queued.
The default is 128.</td>
+ </tr>
+ <tr>
+ <td>error-ref</td>
+ <td>String</td>
+ <td>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.</td>
+ </tr>
+ <tr>
+ <td>filter</td>
+ <td>Filter</td>
+ <td>A Filter to determine if the event should be handled by this
Appender. More than one Filter
+ may be used by using a CompositeFilter.</td>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>String</td>
+ <td>The name of the Appender.</td>
+ </tr>
+ <tr>
+ <td>suppressExceptions</td>
+ <td>boolean</td>
+ <td>The default is true, causing exceptions to be internally
logged and then ignored. When set to
+ false exceptions will be percolated to the caller.</td>
+ </tr>
+ <caption align="top">AsynchAppender Parameters</caption>
+ </table>
+ <p>
+ A typical AsynchAppender configuration might look like:
+
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="warn" name="MyApp" packages="">
+ <appenders>
+ <File name="MyFile" fileName="logs/app.log">
+ <PatternLayout>
+ <pattern>%d %p %C{1.} [%t] %m%n</pattern>
+ </PatternLayout>
+ </File>
+ <Asynch name="Asynch">
+ <appender-ref ref="MyFile"/>
+ </Asynch>
+ </appenders>
+ <loggers>
+ <root level="error">
+ <appender-ref ref="Asynch"/>
+ </root>
+ </loggers>
+</configuration>
+ ]]></source>
+ </p>
+ </subsection>
<a name="ConsoleAppender"/>
<subsection name="ConsoleAppender">
<p>
@@ -756,7 +833,8 @@
<tr>
<td>appender-ref</td>
<td>String</td>
- <td>The name of the Appender to call after the LogEvent has been
manipulated.</td>
+ <td>The name of the Appenders to call after the LogEvent has
been manipulated. Multiple appender-ref
+ elements can be configured.</td>
</tr>
<tr>
<td>filter</td>
@@ -960,7 +1038,8 @@
<a name="DefaultRolloverStrategy"/>
<h5>Default Rollover Strategy</h5>
<p>
- The default rollover strategy accepts both a date/time pattern
and an integer. If the date/time pattern
+ The default rollover strategy accepts both a date/time pattern
and an integer from the filePattern
+ attribute specified on the RollingFileAppender itself. If the
date/time pattern
is present it will be replaced with the current date and time
values. If the pattern contains an integer
it will be incremented on each rollover. If the pattern
contains both a date/time and integer
in the pattern the integer will be incremented until the
result of the date/time pattern changes. If
@@ -968,6 +1047,9 @@
compression scheme that matches the suffix. The pattern may
also contain lookup references that
can be resolved at runtime such as is shown in the example
below.
</p>
+ <p>The Default rollover strategy also accepts a minimum value
and a maximum value. When a minimim
+ value other than 1 is specified than files with an index lower
than that value will not be
+ deleted when the maximum value is exceeded.</p>
<table border="1" width="100%">
<tr>
<th>Parameter Name</th>
@@ -982,7 +1064,7 @@
<tr>
<td>max</td>
<td>integer</td>
- <td>The maximum value of the counter. Once this values is
reached. Older archives will be
+ <td>The maximum value of the counter. Once this values is
reached older archives will be
deleted on subsequent rollovers.</td>
</tr>
<caption align="top">DefaultRolloverStrategy
Parameters</caption>
@@ -1015,6 +1097,31 @@
</configuration>
]]></source>
</p>
+ <p>
+ This second example shows a rollover strategy that will keep up to
20 files before removing them.
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="warn" name="MyApp" packages="">
+ <appenders>
+ <RollingFile name="RollingFile" fileName="logs/app.log"
+
filePattern="logs/$${date:yyyy-MM}/app-%d{MM-dd-yyyy}-%i.log.gz">
+ <PatternLayout>
+ <pattern>%d %p %C{1.} [%t] %m%n</pattern>
+ </PatternLayout>
+ <Policies>
+ <TimeBasedTriggeringPolicy />
+ <SizeBasedTriggeringPolicy size="250 MB"/>
+ </Policies>
+ <DefaultRolloverStrategy max="20"/>
+ </RollingFile>
+ </appenders>
+ <loggers>
+ <root level="error">
+ <appender-ref ref="RollingFile"/>
+ </root>
+ </loggers>
+</configuration>
+ ]]></source>
+ </p>
</subsection>
<a name="RoutingAppender"/>
<subsection name="RoutingAppender">
@@ -1177,6 +1284,21 @@
</tr>
<caption align="top">SocketAppender Parameters</caption>
</table>
+
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="warn" name="MyApp" packages="">
+ <appenders>
+ <Socket name="socket" host="localhost" port="9500">
+ <SerlializedLayout />
+ </Socket>
+ </appenders>
+ <loggers>
+ <root level="error">
+ <appender-ref ref="socket"/>
+ </root>
+ </loggers>
+</configuration>
+ ]]></source>
</subsection>
<a name="SyslogAppender"/>
<subsection name="SyslogAppender">
Copied: logging/log4j/log4j2/trunk/src/site/xdoc/manual/migration.xml (from
r1382400, logging/log4j/log4j2/trunk/src/site/xdoc/manual/api.xml)
URL:
http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/xdoc/manual/migration.xml?p2=logging/log4j/log4j2/trunk/src/site/xdoc/manual/migration.xml&p1=logging/log4j/log4j2/trunk/src/site/xdoc/manual/api.xml&r1=1382400&r2=1386490&rev=1386490&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/src/site/xdoc/manual/api.xml (original)
+++ logging/log4j/log4j2/trunk/src/site/xdoc/manual/migration.xml Mon Sep 17
07:11:45 2012
@@ -18,60 +18,286 @@
<document>
<properties>
- <title>Log4j 2 API</title>
+ <title>Migration from Log4j 1.x</title>
<author email="[email protected]">Ralph Goers</author>
</properties>
<body>
- <section name="Log4j 2 API">
- <a name="Overview"/>
- <subsection name="Overview">
+ <section name="Migration from Log4j 1.x">
+ <a name="The Log4j 1.x bridge"/>
+ <subsection name="The Log4j 1.x bridge">
<p>
- The Log4Jj 2 API provides the interface that applications should
code to and provides the
- adapter components required for implementers to create a logging
implementation. Although Log4j 2
- is broken up between an API and an implementation, the primary
purpose of doing so was not to
- allow multiple implementations, although that is certainly
possible, but to clearly define
- what classes and methods are safe to use in "normal" application
code.
+ Perhaps the simplest way to convert to using Log4j 2 is to
replace the log4j 1.x jar file with
+ Log4j 2's log4j12-api jar. However, to use this successfully
applications must meet the
+ following requirements:
+ <ol>
+ <li>They must not access methods and classes internal to the
Log4j 1.x implementation such
+ as Appenders, LoggerRepository or Logger's callAppenders
method.</li>
+ <li>They must not be programmatically configuring Log4j.</li>
+ <li>They must not be configuring by calling DomConfigurator or
the PropertiesConfigurator.</li>
+ </ol>
</p>
- <h4>Hello World!</h4>
- <p>
- No introduction would be complete without the customary Hello,
World example. Here is ours. First,
- a Logger with the name "HelloWorld" is obtained from the
LogManager. Next, the logger is used to
- write the "Hello, World!" message, however the message will be
written only if the Logger is
- configured to allow informational messages.
- </p>
- <source> import org.apache.logging.log4j.LogManager;
- import org.apache.logging.log4j.Logger;
-
- public class HelloWorld {
- private static Logger logger = LogManager.getLogger("HelloWorld");
- public static void main(String[] args) {
- logger.info("Hello, World!");
- }
- }</source>
- <p>
- The output from the call to logger.info() will vary
significantly depending on the configuration
- used. See the <a href="./configuration.html">Configuration</a>
section for more details.
- </p>
- <h4>Parameter Substitution</h4>
- <p>
- Frequently the purpose of logging is to provide information
about what is happening in the system,
- which requires including information about the objects being
manipulated. In Log4j 1.x this could
- be accomplished by doing:
- </p>
- <source> if (logger.isDebugEnabled()) {
- logger.debug("Logging in user " + user.getName() + " with id " +
user.getId());
- }</source>
- <p>
- Doing this repeatedly has the effect of making the code feel
like it is more about logging than the
- actual task at hand. In addition, it results in the logging
level being checked twice; once on the
- call to isDebugEnabled and once on the debug method. A better
alternative would be:
+ </subsection>
+ <subsection name="Converting to the Log4j 2 API">
+ <p>For the most part, converting from the Log4j 1.x API to Log4j
2.0 should be fairly simple. Many
+ of the log statements will require no modification. However, the
following changes must be
+ made.
+ <ol>
+ <li>Calls to Logger.getLogger must be modified to
LogManager.getLogger.</li>
+ <li>Calls to Logger.getRootLogger must be replaced woth
LogManager.getLogger("").</li>
+ <li>Calls to logger.setLevel or similar methods are not
supported in the API. Applications
+ should remove these. Equivalent functionality is provided in
the Log4j 2 implementation
+ classes but may leave the application susceptible to changes
in Log4j 2 internals.</li>
+ <li>The Log4j 2 API methods accept String messages instead of
Objects. Applications that
+ wish to log Objects should either wrap the Object in an
ObjectMessage or create a
+ custom Message for the Object.</li>
+ <li>Where appropriate, applications should convert to use
parameterized messages instead of
+ String concatenation.</li>
+ </ol>
</p>
- <source> logger.debug("Logging in user {} with id {}",
user.getName(), user.getId());</source>
+ </subsection>
+ <subsection name="Configuration">
<p>
- With the code above the logging level will only be checked once
and the String construction will
- only occur when debug logging is enabled.
+ Although the Log4j 2 configuration syntax is different than that
of Log4j 1.x, most, if not all, of
+ the same functionality is available. Below are the example
configurations for Log4j 1.x and their
+ counterparts in Log4j 2.
</p>
+
+ <h4>Sample 1</h4>
+ <p>Log4j 1.x XML configuration</p>
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN"
"log4j.dtd">
+<log4j:configuration xmlns:log4j='http://jakarta.apache.org/log4j/'>
+
+ <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%d %-5p [%t] %C{2} (%F:%L)
- %m%n"/>
+ </layout>
+ </appender>
+
+ <category name="org.apache.log4j.xml">
+ <priority value="info" />
+ </category>
+
+ <root>
+ <priority value ="debug" />
+ <appender-ref ref="STDOUT" />
+ </root>
+</log4j:configuration>]]></source>
+ <p>Log4j 2 XML configuration</p>
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="OFF">
+ <appenders>
+ <Console name="STDOUT" target="SYSTEM_OUT">
+ <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </Console>
+ </appenders>
+ <loggers>
+ <logger name="org.apache.log4j.xml" level="info"/>
+ <root level="debug">
+ <appender-ref ref="STDOUT"/>
+ </root>
+ </loggers>
+</configuration>]]></source>
+
+ <h4>Sample 2</h4>
+ <p>Log4j 1.x XML configuration</p>
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN"
"log4j.dtd">
+<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/";>
+
+ <appender name="A1" class="org.apache.log4j.FileAppender">
+ <param name="File" value="A1.log" />
+ <param name="Append" value="false" />
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%t %-5p %c{2} - %m%n"/>
+ </layout>
+ </appender>
+
+ <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%d %-5p [%t] %C{2}
(%F:%L) - %m%n"/>
+ </layout>
+ </appender>
+
+ <category name="org.apache.log4j.xml">
+ <priority value="debug" />
+ <appender-ref ref="A1" />
+ </category>
+
+ <root>
+ <priority value ="debug" />
+ <appender-ref ref="STDOUT" />
+ </root>
+
+</log4j:configuration>]]></source>
+
+ <p>Log4j 2 XML configuration</p>
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="OFF">
+ <appenders>
+ <File name="A1" fileName="A1.log" append="false">
+ <PatternLayout pattern="%t %-5p %c{2} - %m%n"/>
+ </File>
+ <Console name="STDOUT" target="SYSTEM_OUT">
+ <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </Console>
+ </appenders
+ <loggers>
+ <logger name="org.apache.log4j.xml" level="debug">
+ <appender-ref ref="A1"/>
+ </logger>
+ <root level="debug">
+ <appender-ref ref="STDOUT"/>
+ </root>
+ </loggers>
+</configuration>]]></source>
+
+ <h4>Sample 3</h4>
+ <p>Log4j 1.x XML configuration. This example from Log4j 1.x is
misleading. The SocketAppender does not
+ actually use a Layout. Configuring one will have no effect.</p>
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN"
"log4j.dtd">
+ <log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/";>
+ <appender name="A1" class="org.apache.log4j.net.SocketAppender">
+ <param name="RemoteHost" value="localhost"/>
+ <param name="Port" value="5000"/>
+ <param name="LocationInfo" value="true"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%t %-5p %c{2} -
%m%n"/>
+ </layout>
+ </appender>
+ <appender name="STDOUT" class="org.apache.log4j.ConsoleAppender">
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%d %-5p [%t] %C{2}
(%F:%L) - %m%n"/>
+ </layout>
+ </appender>
+ <category name="org.apache.log4j.xml">
+ <priority value="debug"/>
+ <appender-ref ref="A1"/>
+ </category>
+ <root>
+ <priority value="debug"/>
+ <appender-ref ref="STDOUT"/>
+ </root>
+</log4j:configuration>]]></source>
+
+ <p>Log4j 2 XML configuration</p>
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="OFF">
+ <appenders>
+ <Socket name="A1" host="localHost" port="5000">
+ <SerializedLayout/>
+ </Socket>
+ <Console name="STDOUT" target="SYSTEM_OUT">
+ <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </Console>
+ </appenders
+ <loggers>
+ <logger name="org.apache.log4j.xml" level="debug">
+ <appender-ref ref="A1"/>
+ </logger>
+ <root level="debug">
+ <appender-ref ref="STDOUT"/>
+ </root>
+ </loggers>
+</configuration>]]></source>
+
+ <h4>Sample 4</h4>
+ <p>Log4j 1.x XML configuration using the AsynchAppender.</p>
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN"
"log4j.dtd">
+<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/";
+ configDebug="true">
+
+ <appender name="ASYNC" class="org.apache.log4j.AsyncAppender">
+ <appender-ref ref="TEMP"/>
+ </appender>
+
+ <appender name="TEMP" class="org.apache.log4j.FileAppender">
+ <param name="File" value="temp"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%d %-5p [%t] %C{2}
(%F:%L) - %m%n"/>
+ </layout>
+ </appender>
+
+ <root>
+ <priority value="debug"/>
+ <appender-ref ref="ASYNC"/>
+ </root>
+</log4j:configuration>]]></source>
+
+ <p>Log4j 2 XML configuration. </p>
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="OFF">
+ <appenders>
+ <File name="TEMP" fileName="temp" append="false">
+ <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </File>
+ <Asynch name="ASYNC">
+ <appender-ref ref="TEMP"/>
+ </Asynch>
+ </appenders
+ <loggers>
+ <root level="debug">
+ <appender-ref ref="ASYNC"/>
+ </root>
+ </loggers>
+</configuration>]]></source>
+
+
+ <h4>Sample 5</h4>
+ <p>Log4j 1.x XML configuration using the AsynchAppender.</p>
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE log4j:configuration PUBLIC "-//APACHE//DTD LOG4J 1.2//EN"
"log4j.dtd">
+<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/";
configDebug="true">
+
+ <appender name="ASYNC" class="org.apache.log4j.AsyncAppender">
+ <appender-ref ref="TEMP"/>
+ <appender-ref ref="CONSOLE"/>
+ </appender>
+
+ <appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%d %-5p [%t] %C{2}
(%F:%L) - %m%n"/>
+ </layout>
+ </appender>
+
+ <appender name="TEMP" class="org.apache.log4j.FileAppender">
+ <param name="File" value="temp"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern"
+ value="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </layout>
+ </appender>
+
+ <root>
+ <priority value="debug"/>
+ <appender-ref ref="ASYNC"/>
+ </root>
+</log4j:configuration>]]></source>
+
+ <p>Log4j 2 XML configuration. </p>
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="debug">
+ <appenders>
+ <Console name="CONSOLE" target="SYSTEM_OUT">
+ <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </Console>
+ <File name="TEMP" fileName="temp" append="false">
+ <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
+ </File>
+ <Asynch name="ASYNC">
+ <appender-ref ref="TEMP"/>
+ <appender-ref ref="CONSOLE"/>
+ </Asynch>
+ </appenders
+ <loggers>
+ <root level="debug">
+ <appender-ref ref="ASYNC"/>
+ </root>
+ </loggers>
+</configuration>]]></source>
</subsection>
</section>
</body>
