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 <[email protected]> Authored: Sun Feb 5 20:04:14 2017 +0900 Committer: rpopma <[email protected]> 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>
