ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587670343
##########
src/site/antora/modules/ROOT/pages/manual/async.adoc:
##########
@@ -177,120 +174,108 @@ The below properties can also be specified by creating
a file named
`log4j2.component.properties` and including this file in the classpath
of the application.
-NOTE: System properties were renamed into a more consistent style in
-Log4j 2.10.0. All old property names are still supported which are
-documented xref:manual/configuration.adoc#SystemProperties[here].
-
[[SysPropsAllAsync]]
.System Properties to configure all asynchronous loggers
-[cols="5m,2,10a",options="header"]
+[cols="1,1,5"]
|===
-|System Property |Default Value |Description
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+|
[[log4j2.asyncLoggerExceptionHandler]]`log4j2.asyncLogger{zwsp}ExceptionHandler`
-|log4j2.asyncLoggerExceptionHandler
-|`default handler`
+(`LOG4J_ASYNC_LOGGER_{zwsp}EXCEPTION_HANDLER`)
+|
link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerDefaultExceptionHandler[AsyncLogger{zwsp}DefaultExceptionHandler]
|
-Fully qualified name of a class that implements the
-`com.lmax.disruptor.ExceptionHandler` interface. The class needs to have
-a public zero-argument constructor. If specified, this class will be
-notified when an exception occurs while logging the messages.
+Fully qualified name of a class that implements the
https://lmax-exchange.github.io/disruptor/javadoc/com.lmax.disruptor/com/lmax/disruptor/ExceptionHandler.html[ExceptionHandler]
interface, which will be notified when an exception occurs while logging
messages.
+The class needs to have a public zero-argument constructor.
-If not specified, the default exception handler will print a message and
+The default exception handler will print a message and
stack trace to the standard error output stream.
-|log4j2.asyncLoggerRingBufferSize
-|256 * 1024
+| [[log4j2.asyncLoggerRingBufferSize]]`log4j2.asyncLogger{zwsp}RingBufferSize`
+
+(`LOG4J_ASYNC_LOGGER_{zwsp}RING_BUFFER_SIZE`)
+| `256 × 1024`
+
+`4 × 1024` (GC mode)
|
Size (number of slots) in the RingBuffer used by the asynchronous
-logging subsystem. 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.
-
-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 behaviour
-is determined by the
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy.html[AsyncQueueFullPolicy].
-
-|[[asyncLoggerWaitStrategy]]log4j2.asyncLoggerWaitStrategy
-|`Timeout`
-|Valid values: Block,
-Timeout, Sleep, Yield.
-(See also the <<Custom WaitStrategy>> section below.) +
-`Block` is a strategy that uses a lock and condition variable for the
-I/O thread waiting for log events. Block can be used when throughput and
-low-latency are not as important as CPU resource. Recommended for
-resource constrained/virtualised environments. +
-`Timeout` is a variation of the `Block` strategy that will periodically
-wake up from the lock condition await() call. This ensures that if a
-notification is missed somehow the consumer thread is not stuck but will
-recover with a small latency delay (default 10ms). +
-`Sleep` is a strategy that initially spins, then uses a Thread.yield(),
-and eventually parks for the minimum number of nanos the OS and JVM will
-allow while the I/O thread is waiting for log events. Sleep is a good
-compromise between performance and CPU resource. This strategy has very
-low impact on the application thread, in exchange for some additional
-latency for actually getting the message logged. +
-`Yield` is a strategy that uses a Thread.yield() for waiting for log
-events after an initially spinning. Yield is a good compromise between
-performance and CPU resource, but may use more CPU than Sleep in order
-to get the message logged to disk sooner.
-
-|log4j2.asyncLoggerTimeout
+logging subsystem.
+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.
+
+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 behaviour is determined by the
link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy.html[AsyncQueueFullPolicy].
+
+| [[log4j2.asyncLoggerWaitStrategy]]`log4j2.asyncLogger{zwsp}WaitStrategy`
+
+(`LOG4J_ASYNC_LOGGER_{zwsp}WAIT_STRATEGY`)
+| `Timeout`
+a| Specifies the
https://lmax-exchange.github.io/disruptor/javadoc/com.lmax.disruptor/com/lmax/disruptor/WaitStrategy.html[WaitStrategy]
used by the LMAX Disruptor.
+
+Valid values:
+
+* `Block`: a strategy that uses a lock and condition variable for the I/O
thread waiting for log events.
+Block can be used when throughput and low-latency are not as important as CPU
resource.
+Recommended for resource constrained/virtualised environments.
+
+* `Timeout`: a variation of the `Block` strategy that will periodically wake
up from the lock condition `await()` call.
+This ensures that if a notification is missed somehow the consumer thread is
not stuck but will recover with a small latency delay (see
<<log4j2.asyncLoggerTimeout>>)
+
+* `Sleep`: a strategy that initially spins, then uses a `Thread.yield()`, and
eventually parks for the minimum number of nanos the OS and JVM will allow
while the I/O thread is waiting for log events (see
<<log4j2.asyncLoggerRetries>> and <<log4j2.asyncLoggerSleepTimeNs>>).
+Sleep is a good compromise between performance and CPU resource.
+This strategy has very low impact on the application thread, in exchange for
some additional latency for actually getting the message logged.
+
+* `Yield`: is a strategy that uses a `Thread.yield()` for waiting for log
events after an initially spinning.
+Yield is a good compromise between performance and CPU resource, but may use
more CPU than `Sleep` in order to get the message logged to disk sooner.
+
+* a <<Custom WaitStrategy>>.
Review Comment:
There is actually a reason for that: these are **not** pure description
lists, there is always the possibility to enter a fully qualified class name of
some kind.
In the remodelling done in a63a714f5097916aca0c46aee0e3a1793dda652a I
rephrased the descriptions so that I can use description lists.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
