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 2017/02/05 11:04:30 UTC
logging-log4j2 git commit: improve documentation on
AsyncQueueFullPolicy
Repository: logging-log4j2
Updated Branches:
refs/heads/master 8cf9e4fbd -> 933a1e1fd
improve documentation on AsyncQueueFullPolicy
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/933a1e1f
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/933a1e1f
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/933a1e1f
Branch: refs/heads/master
Commit: 933a1e1fdb64d638e3a9bd49dc5dfd7465447f0f
Parents: 8cf9e4f
Author: rpopma <rp...@apache.org>
Authored: Sun Feb 5 20:04:14 2017 +0900
Committer: rpopma <rp...@apache.org>
Committed: Sun Feb 5 20:04:14 2017 +0900
----------------------------------------------------------------------
.../log4j/core/async/AsyncQueueFullPolicy.java | 22 ++++++++++++++++++++
src/site/xdoc/manual/appenders.xml | 8 ++++++-
src/site/xdoc/manual/async.xml | 10 +++++++++
3 files changed, 39 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/933a1e1f/log4j-core/src/main/java/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy.java
----------------------------------------------------------------------
diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy.java
index f164a5a..f3406fb 100644
--- a/log4j-core/src/main/java/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy.java
+++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy.java
@@ -21,6 +21,28 @@ import org.apache.logging.log4j.Level;
/**
* Policy for deciding whether to discard the event, enqueue it or log the event on the current thread when the queue
* is full.
+ * <p>
+ * The asynchronous logging queue may become full when the application is logging faster than the underlying appender
+ * can keep up with for a long enough time to fill up the bounded queue. When this happens, the logging subsystem has to
+ * choose what to do with the event:
+ * </p>
+ * <ul>
+ * <li>Enqueue the event. This will block until the background thread removes a log event from the queue and space for
+ * new events becomes available in the queue. There is a risk of causing deadlock here when the new logging call was
+ * made while processing another logging call, for example when Log4j calls {@code toString()} on a message
+ * parameter, and the parameter object makes a logging call from its {@code toString()} method.</li>
+ * <li>Bypass the queue and send the event directly to the underlying appenders. This is the default policy used by
+ * Log4j since 2.7: see {@link DefaultAsyncQueueFullPolicy}. The benefit of this approach is that
+ * events will not get lost, but the disadvantage is that the resulting log file will be confusing for users,
+ * since log events will appear in the log file in random order: new events that are directly logged are followed
+ * by older log events taken from the queue.</li>
+ * <li>Discard the event. Log4j offers a variation of this policy where log events that are more verbose than
+ * a certain threshold are discarded, and other events are sent to the underlying appenders.
+ * See {@link DiscardingAsyncQueueFullPolicy} for defaults.</li>
+ * </ul>
+ * <p>
+ * See {@link AsyncQueueFullPolicyFactory} for how to install a custom policy.
+ * </p>
*
* @see AsyncQueueFullPolicyFactory
* @since 2.6
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/933a1e1f/src/site/xdoc/manual/appenders.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/appenders.xml b/src/site/xdoc/manual/appenders.xml
index 467bf0f..bd60dfc 100644
--- a/src/site/xdoc/manual/appenders.xml
+++ b/src/site/xdoc/manual/appenders.xml
@@ -98,7 +98,13 @@
<td>bufferSize</td>
<td>integer</td>
<td>Specifies the maximum number of events that can be queued. The default is 128. Note that when using a
- disruptor-style <tt>BlockingQueue</tt>, this buffer size must be a power of 2.</td>
+ disruptor-style <tt>BlockingQueue</tt>, this buffer size must be a power of 2.
+ <p>
+ When the application is logging faster than the underlying appender can keep up with
+ for a long enough time to fill up the queue, the behavious is determined by the
+ <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy.html">AsyncQueueFullPolicy</a>.
+ </p>
+ </td>
</tr>
<tr>
<td>errorRef</td>
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/933a1e1f/src/site/xdoc/manual/async.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/async.xml b/src/site/xdoc/manual/async.xml
index 1f1a15d..db337b7 100644
--- a/src/site/xdoc/manual/async.xml
+++ b/src/site/xdoc/manual/async.xml
@@ -215,6 +215,11 @@
Make this value large enough to deal with bursts of activity. The minimum size is 128.
The RingBuffer will be pre-allocated at first use and will never grow or shrink
during the life of the system.
+ <p>
+ When the application is logging faster than the underlying appender can keep up with
+ for a long enough time to fill up the queue, the behavious is determined by the
+ <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy.html">AsyncQueueFullPolicy</a>.
+ </p>
</td>
</tr>
<tr>
@@ -385,6 +390,11 @@
Make this value large enough to deal with bursts of activity. The minimum size is 128.
The RingBuffer will be pre-allocated at first use and will never grow
or shrink during the life of the system.
+ <p>
+ When the application is logging faster than the underlying appender can keep up with
+ for a long enough time to fill up the queue, the behavious is determined by the
+ <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy.html">AsyncQueueFullPolicy</a>.
+ </p>
</td>
</tr>
<tr>