You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by rp...@apache.org on 2015/12/23 14:38:49 UTC
[10/11] logging-log4j2 git commit: LOG4J2-1080 documentation
LOG4J2-1080 documentation
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/c484ec61
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/c484ec61
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/c484ec61
Branch: refs/heads/master
Commit: c484ec61f5db1eebb7bf818448a8af41342bab08
Parents: d97cd82
Author: rpopma <rp...@apache.org>
Authored: Wed Dec 23 22:15:37 2015 +0900
Committer: rpopma <rp...@apache.org>
Committed: Wed Dec 23 22:15:37 2015 +0900
----------------------------------------------------------------------
src/site/xdoc/manual/appenders.xml | 83 ++++++++++++++------------
src/site/xdoc/manual/async.xml | 16 ++++-
src/site/xdoc/manual/configuration.xml.vm | 39 ++++++++++--
3 files changed, 95 insertions(+), 43 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/c484ec61/src/site/xdoc/manual/appenders.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/appenders.xml b/src/site/xdoc/manual/appenders.xml
index 97679dd..69ed1a0 100644
--- a/src/site/xdoc/manual/appenders.xml
+++ b/src/site/xdoc/manual/appenders.xml
@@ -120,6 +120,13 @@
</tr>
</table>
<p>
+ 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
+ <a href="configuration.html#AsyncEventRouter"><tt>log4j2.AsyncEventRouter</tt>,
+ <tt>log4j2.DiscardThreshold</tt> and <tt>log4j2.DiscardQueueRatio</tt></a>.
+ </p>
+ <p>
A typical AsyncAppender configuration might look like:
</p>
@@ -1256,8 +1263,8 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<td>layout</td>
<td>Layout</td>
<td>
- The Layout to use to format the LogEvent. If you do not specify a layout, the appender will send the
- <a class="javadoc" href="http://logging.apache.org/log4j/2.x/log4j-api/apidocs/org/apache/logging/log4j/message/Message.html#getFormattedMessage())">formatted message</a>
+ The Layout to use to format the LogEvent. If you do not specify a layout, the appender will send the
+ <a class="javadoc" href="http://logging.apache.org/log4j/2.x/log4j-api/apidocs/org/apache/logging/log4j/message/Message.html#getFormattedMessage())">formatted message</a>
to Kafka as a UTF-8 encoded string.
</td>
</tr>
@@ -2004,7 +2011,7 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<p>
You can use this policy to make loggers in third party code less chatty by changing event levels.
The LoggerNameLevelRewritePolicy will rewrite log event levels for a given logger name prefix.
- You configure a LoggerNameLevelRewritePolicy with a logger name prefix and a pairs of levels,
+ You configure a LoggerNameLevelRewritePolicy with a logger name prefix and a pairs of levels,
where a pair defines a source level and a target level.
</p>
<table>
@@ -2025,8 +2032,8 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
</tr>
</table>
<p>
- The following configuration shows a RewriteAppender configured to map level INFO to DEBUG and level
- WARN to INFO for all loggers that start with <code>com.foo.bar</code>.
+ The following configuration shows a RewriteAppender configured to map level INFO to DEBUG and level
+ WARN to INFO for all loggers that start with <code>com.foo.bar</code>.
</p>
<pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" name="MyApp">
@@ -2263,11 +2270,11 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
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
- the file pattern ends with ".gz", ".zip", ".bz2", ".deflate", ".pack200", or ".xz" the resulting archive
- will be compressed using the compression scheme that matches the suffix. The formats bzip2, Deflate,
+ the file pattern ends with ".gz", ".zip", ".bz2", ".deflate", ".pack200", or ".xz" the resulting archive
+ will be compressed using the compression scheme that matches the suffix. The formats bzip2, Deflate,
Pack200 and XZ require <a href="http://commons.apache.org/proper/commons-compress/">Apache Commons Compress</a>.
- In addition, XZ requires <a href="http://tukaani.org/xz/java.html">XZ for Java</a>.
- The pattern may also contain lookup references that can be resolved at runtime such as is shown in the example
+ In addition, XZ requires <a href="http://tukaani.org/xz/java.html">XZ for Java</a>.
+ 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 supports two variations for incrementing the counter. The first is
@@ -2526,7 +2533,7 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<tr>
<td>pathSorter</td>
<td>PathSorter</td>
- <td>A plugin implementing the
+ <td>A plugin implementing the
<a href="../log4j-core/apidocs/org/apache/logging/log4j/core/appender/rolling/action/PathSorter.html">PathSorter</a>
interface to sort the files before selecting the files to delete. The default is to sort most recently
modified files first.</td>
@@ -2542,8 +2549,8 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
If conditions are not nested they may be evaluated in any order.
</p>
<p>
- Conditions can also be combined with the logical operators AND, OR and NOT by using the
- <tt>IfAll</tt>, <tt>IfAny</tt> and <tt>IfNot</tt> composite conditions.
+ Conditions can also be combined with the logical operators AND, OR and NOT by using the
+ <tt>IfAll</tt>, <tt>IfAny</tt> and <tt>IfNot</tt> composite conditions.
</p>
<p>Users can create custom conditions or use the built-in conditions:</p>
<ul>
@@ -2568,7 +2575,7 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<td>ScriptCondition</td>
<td><p><em>Required if no PathConditions are specified.</em> A ScriptCondition element specifying a script.</p>
<p>
- The ScriptCondition should contain a <a href="#ScriptCondition">Script,
+ The ScriptCondition should contain a <a href="#ScriptCondition">Script,
ScriptRef or ScriptFile</a> element that specifies the logic to be executed.
(See also the <a href="filters.html#Script">ScriptFilter</a> documentation for more examples of
configuring ScriptFiles and ScriptRefs.)
@@ -2590,15 +2597,15 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<tr>
<td>glob</td>
<td>String</td>
- <td><em>Required if regex not specified.</em>
- Matches the relative path (relative to the base path) using a limited pattern language that resembles regular expressions but with a
+ <td><em>Required if regex not specified.</em>
+ Matches the relative path (relative to the base path) using a limited pattern language that resembles regular expressions but with a
<a href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/FileSystem.html#getPathMatcher(java.lang.String)">simpler syntax</a>.
</td>
</tr>
<tr>
<td>regex</td>
<td>String</td>
- <td><em>Required if glob not specified.</em>
+ <td><em>Required if glob not specified.</em>
Matches the relative path (relative to the base path) using a regular expression as defined by the
<a href="https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">Pattern</a> class.
</td>
@@ -2608,7 +2615,7 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<td>PathCondition[]</td>
<td>An optional set of nested <a href="#DeletePathCondition">PathConditions</a>. If any nested conditions
exist they all need to accept the file before it is deleted. Nested conditions are only evaluated if the
- outer condition accepts a file (if the path name matches).
+ outer condition accepts a file (if the path name matches).
</td>
</tr>
</table>
@@ -2623,7 +2630,7 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<tr>
<td>age</td>
<td>String</td>
- <td><em>Required.</em>
+ <td><em>Required.</em>
Specifies a <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/appender/rolling/action/Duration.html#parse(CharSequence)">duration</a>.
The condition accepts files that are as old or older than the specified duration.
</td>
@@ -2633,7 +2640,7 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<td>PathCondition[]</td>
<td>An optional set of nested <a href="#DeletePathCondition">PathConditions</a>. If any nested conditions
exist they all need to accept the file before it is deleted. Nested conditions are only evaluated if the
- outer condition accepts a file (if the file is old enough).
+ outer condition accepts a file (if the file is old enough).
</td>
</tr>
</table>
@@ -2648,7 +2655,7 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<tr>
<td>exceeds</td>
<td>int</td>
- <td><em>Required.</em>
+ <td><em>Required.</em>
The threshold count from which files will be deleted.
</td>
</tr>
@@ -2657,7 +2664,7 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<td>PathCondition[]</td>
<td>An optional set of nested <a href="#DeletePathCondition">PathConditions</a>. If any nested conditions
exist they all need to accept the file before it is deleted. Nested conditions are only evaluated if the
- outer condition accepts a file (if the threshold count has been exceeded).
+ outer condition accepts a file (if the threshold count has been exceeded).
</td>
</tr>
</table>
@@ -2672,7 +2679,7 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<tr>
<td>exceeds</td>
<td>String</td>
- <td><em>Required.</em>
+ <td><em>Required.</em>
The threshold accumulated file size from which files will be deleted.
The size can be specified in bytes, with the suffix KB, MB or GB, for example <tt>20MB</tt>.
</td>
@@ -2682,7 +2689,7 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<td>PathCondition[]</td>
<td>An optional set of nested <a href="#DeletePathCondition">PathConditions</a>. If any nested conditions
exist they all need to accept the file before it is deleted. Nested conditions are only evaluated if the
- outer condition accepts a file (if the threshold accumulated file size has been exceeded).
+ outer condition accepts a file (if the threshold accumulated file size has been exceeded).
</td>
</tr>
</table>
@@ -2723,9 +2730,9 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
triggering policies, will create up to 100 archives on the same day (1-100) that are stored in a directory
based on the current year and month, and will compress each
archive using gzip and will roll every hour.
-
- During every rollover, this configuration will delete files that match "*/app-*.log.gz"
- and are 30 days old or older,
+
+ During every rollover, this configuration will delete files that match "*/app-*.log.gz"
+ and are 30 days old or older,
but keep the most recent 100 GB or the most recent 10 files, whichever comes first.
</p>
@@ -2848,16 +2855,16 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<ScriptCondition>
<Script name="superstitious" language="groovy"><![CDATA[
import java.nio.file.*;
-
- def result = [];
+
+ def result = [];
def pattern = ~/\d*\/app-(\d*)\.log\.gz/;
-
+
pathList.each { pathWithAttributes ->
def relative = basePath.relativize pathWithAttributes.path
statusLogger.trace 'SCRIPT: relative path=' + relative + " (base=$basePath)";
-
+
// remove files dated Friday the 13th
-
+
def matcher = pattern.matcher(relative.toString());
if (matcher.find()) {
def dateString = matcher.group(1);
@@ -3727,8 +3734,8 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<a name="JeroMQAppender"/>
<subsection name="ZeroMQ/JeroMQ Appender">
<p>
- The ZeroMQ appender uses the <a href="https://github.com/zeromq/jeromq">JeroMQ</a> library to send log
- events to one or more ZeroMQ endpoints.
+ The ZeroMQ appender uses the <a href="https://github.com/zeromq/jeromq">JeroMQ</a> library to send log
+ events to one or more ZeroMQ endpoints.
</p>
<p>
This is a simple JeroMQ configuration:
@@ -3736,7 +3743,7 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<Configuration name="JeroMQAppenderTest" status="TRACE">
<Appenders>
- <JeroMQ name="JeroMQAppender">
+ <JeroMQ name="JeroMQAppender">
<Property name="endpoint">tcp://*:5556</Property>
<Property name="endpoint">ipc://info-topic</Property>
</JeroMQ>
@@ -3746,7 +3753,7 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<AppenderRef ref="JeroMQAppender"/>
</Root>
</Loggers>
-</Configuration>]]></pre>
+</Configuration>]]></pre>
<p>
The table below describes all options. Please consult the JeroMQ and ZeroMQ documentation for details.
</p>
@@ -3765,8 +3772,8 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<tr>
<td>Layout</td>
<td>layout</td>
- <td>The Layout of the Appender. If you do not specify a layout, the appender uses the default
- pattern appender returned by
+ <td>The Layout of the Appender. If you do not specify a layout, the appender uses the default
+ pattern appender returned by
<a href="https://logging.apache.org/log4j/2.x/log4j-core/apidocs/org/apache/logging/log4j/core/layout/PatternLayout.html#createDefaultLayout()">PatternLayout.createDefaultLayout()</a>.</td>
</tr>
<tr>
@@ -3884,7 +3891,7 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity {
<td>boolean</td>
<td>The ZMQ_XPUB_VERBOSE option. Defaults to false.</td>
</tr>
- </table>
+ </table>
</subsection>
</section>
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/c484ec61/src/site/xdoc/manual/async.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/async.xml b/src/site/xdoc/manual/async.xml
index eb9e16b..0f6a754 100644
--- a/src/site/xdoc/manual/async.xml
+++ b/src/site/xdoc/manual/async.xml
@@ -265,12 +265,19 @@
of applications.
</p>
<p>
- You can also specify a fully qualified class name of a custom class that implements the
+ You can also specify the fully qualified class name of a custom class that implements the
<tt>Clock</tt> interface.
</p>
</td>
</tr>
</table>
+ <p>
+ 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
+ <a href="configuration.html#AsyncEventRouter"><tt>log4j2.AsyncEventRouter</tt>,
+ <tt>log4j2.DiscardThreshold</tt> and <tt>log4j2.DiscardQueueRatio</tt></a>.
+ </p>
</subsection>
<a name="MixedSync-Async" />
<subsection name="Mixing Synchronous and Asynchronous Loggers">
@@ -379,6 +386,13 @@
</td>
</tr>
</table>
+ <p>
+ 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
+ <a href="configuration.html#AsyncEventRouter"><tt>log4j2.AsyncEventRouter</tt>,
+ <tt>log4j2.DiscardThreshold</tt> and <tt>log4j2.DiscardQueueRatio</tt></a>.
+ </p>
</subsection>
<a name="Location" />
<subsection name="Location, location, location...">
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/c484ec61/src/site/xdoc/manual/configuration.xml.vm
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/configuration.xml.vm b/src/site/xdoc/manual/configuration.xml.vm
index a417151..93b4663 100644
--- a/src/site/xdoc/manual/configuration.xml.vm
+++ b/src/site/xdoc/manual/configuration.xml.vm
@@ -71,9 +71,9 @@
<li>Log4j will inspect the <code>"log4j.configurationFile"</code> system property and, if set, will attempt to
load the configuration using the <code>ConfigurationFactory</code> that matches the file
extension.</li>
- <li>If no system property is set the properties ConfigurationFactory will look for
+ <li>If no system property is set the properties ConfigurationFactory will look for
<code>log4j2-test.properties</code> in the classpath.</li>
- <li>If no such file is found the YAML ConfigurationFactory will look for
+ <li>If no such file is found the YAML ConfigurationFactory will look for
<code>log4j2-test.yaml</code> or <code>log4j2-test.yml</code> in the classpath.</li>
<li>If no such file is found the JSON ConfigurationFactory will look for
<code>log4j2-test.json</code> or <code>log4j2-test.jsn</code> in the classpath.</li>
@@ -280,7 +280,7 @@ public class Bar {
<subsection name="Automatic Reconfiguration">
<p>
When configured from a File, Log4j has the ability to automatically detect changes to the configuration
- file and reconfigure itself. If the <code>monitorInterval</code> attribute is specified on the configuration
+ file and reconfigure itself. If the <code>monitorInterval</code> attribute is specified on the configuration
element and is set to a non-zero value then the file will be checked the next time a log event is evaluated
and/or logged and the monitorInterval has elapsed since the last check. The example below shows how
to configure the attribute so that the configuration file will be checked for changes only after at
@@ -948,7 +948,7 @@ rootLogger.appenderRef.stdout.ref = STDOUT
<p>
While this is useful, there are many more places properties can originate from. To accommodate this,
Log4j also supports the syntax <code>${dollar}{prefix:name}</code> where the prefix identifies tells Log4j
- that variable name should be evaluated in a specific context.
+ that variable name should be evaluated in a specific context.
See the <a href="lookups.html">Lookups</a> manual page for more details.
The contexts that are built in to Logj4 are:
</p>
@@ -1872,6 +1872,37 @@ public class AwesomeTest {
the value at the time of the call to the logger is the value that is logged.
</td>
</tr>
+ <tr>
+ <td><a name="AsyncEventRouter"/>log4j2.AsyncEventRouter</td>
+ <td> </td>
+ <td>
+ <p>Used by Async Loggers and the AsyncAppender to maintain application throughput even when
+ the underlying appender cannot keep up with the logging rate and the queue is filling up.</p>
+ <p>If no value is specified (the default) events are never discarded. If the queue is full, the
+ logger call blocks until the event can be added to the queue.</p>
+ <p>Specify <tt>Discard</tt> to drop events whose level is equal or less than the threshold level
+ (INFO by default) when the queue has been filled to the discard ratio (0.8 by default).</p>
+ <p>It is also possible to specify the fully qualified class name of a custom class that implements the
+ <tt>org.apache.logging.log4j.core.async.AsyncEventRouter</tt> interface.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>log4j2.DiscardThreshold</td>
+ <td>INFO</td>
+ <td>Used by the DiscardingAsyncEventRouter to determine which events to drop when the queue
+ becomes too full. By default, <tt>INFO</tt>, <tt>DEBUG</tt> and <tt>TRACE</tt> level
+ events are discarded when the queue has been filled up to or beyond the discard ratio.
+ This property only has effect if <tt>Discard</tt> is specified as the
+ <tt>log4j2.AsyncEventRouter</tt>.</td>
+ </tr>
+ <tr>
+ <td>log4j2.DiscardQueueRatio</td>
+ <td>0.8</td>
+ <td>Used by the DiscardingAsyncEventRouter to determine when the queue is becoming too full.
+ By default, events may be discarded when the queue is 80% full or more.
+ This property only has effect if <tt>Discard</tt> is specified as the
+ <tt>log4j2.AsyncEventRouter</tt>.</td>
+ </tr>
</table>
</subsection>