ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587657267
##########
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>>.
+
+|[[log4j2.asyncLoggerTimeout]]`log4j2.asyncLogger{zwsp}Timeout`
+
+(`LOG4J_ASYNC_LOGGER_{zwsp}TIMEOUT`)
|`10`
-|Timeout in milliseconds of `TimeoutBlockingWaitStrategy`. See
-link:#asyncLoggerWaitStrategy[WaitStrategy System Property] for details.
+|Timeout in milliseconds of `Timeout` wait strategy (see
<<log4j2.asyncLoggerWaitStrategy>>).
+
+| [[log4j2.asyncLoggerSleepTimeNs]]`log4j2.asyncLogger{zwsp}SleepTimeNs`
-|log4j2.asyncLoggerSleepTimeNs
-|`100`
-|Sleep time (in nanoseconds) of `SleepingWaitStrategy`. See
-link:#asyncLoggerWaitStrategy[WaitStrategy System Property] for details.
+(`LOG4J_ASYNC_LOGGER_{zwsp}SLEEP_TIME_NS`)
+| `100`
+| Sleep time in nanoseconds of `Sleep` wait strategy (see
<<log4j2.asyncLoggerWaitStrategy>>).
-|log4j2.asyncLoggerRetries
-|`200`
-|Total number of spin cycles and `Thread.yield()` cycles of
`SleepingWaitStrategy`. See
-link:#asyncLoggerWaitStrategy[WaitStrategy System Property] for details.
+| [[log4j2.asyncLoggerRetries]]`log4j2.asyncLogger{zwsp}Retries`
+(`LOG4J_ASYNC_LOGGER_{zwsp}RETRIES`)
+| `200`
+| Total number of spin cycles and `Thread.yield()` cycles of `Sleep` (see
<<log4j2.asyncLoggerWaitStrategy>>).
+|
[[log4j2.asyncLoggerSynchronizeEnqueueWhenQueueFull]]`log4j2.asyncLogger{zwsp}SynchronizeEnqueueWhenQueueFull`
-|AsyncLogger.SynchronizeEnqueueWhenQueueFull
-|`true`
+(`LOG4J_ASYNC_LOGGER_{zwsp}SYNCHRONIZE_ENQUEUE_WHEN_QUEUE_FULL`)
+| `true`
|Synchronizes access to the Disruptor ring buffer for blocking enqueue
operations when the queue is full.
-Users encountered excessive CPU utilization with Disruptor v3.4.2 when the
application
-was logging more than the underlying appender could keep up with and the ring
buffer became full,
-especially when the number of application threads vastly outnumbered the
number of cores.
-CPU utilization is significantly reduced by restricting access to the enqueue
operation. Setting this value
-to `false` may lead to very high CPU utilization when the async logging queue
is full.
-
-|log4j2.asyncLoggerThreadNameStrategy
-|`CACHED`
-|Valid values: CACHED, UNCACHED.
-By default, AsyncLogger caches the thread name in a ThreadLocal variable
-to improve performance. Specify the `UNCACHED` option if your
-application modifies the thread name at runtime (with
-`Thread.currentThread().setName()`) and you want to see the new thread
-name reflected in the log.
-
-|log4j2.clock
-|`SystemClock`
-|Implementation of the `org.apache.logging.log4j.core.time.Clock`
-interface that is used for timestamping the log events when all loggers
-are asynchronous.
-By default, `System.currentTimeMillis` is called on every log event.
-
-`CachedClock` is an optimization intended for low-latency applications
-where time stamps are generated from a clock that updates its internal
-time in a background thread once every millisecond, or every 1024 log
-events, whichever comes first. This reduces logging latency a little, at
-the cost of some precision in the logged time stamps. Unless you are
-logging many events, you may see "jumps" of 10-16 milliseconds between
-log time stamps. WEB APPLICATION WARNING: The use of a background thread
-may cause issues for web applications and OSGi applications so
-CachedClock is not recommended for this kind of applications.
-
-You can also specify the fully qualified class name of a custom class
-that implements the `Clock` interface.
+Users encountered excessive CPU utilization with Disruptor v3.4.2 when the
application was logging more than the underlying appender could keep up with
and the ring buffer became full, especially when the number of application
threads vastly outnumbered the number of cores.
+CPU utilization is significantly reduced by restricting access to the enqueue
operation.
+Setting this value to `false` may lead to very high CPU utilization when the
async logging queue is full.
+
+|
[[log4j2.asyncLoggerThreadNameStrategy]]`log4j2.asyncLogger{zwsp}ThreadNameStrategy`
+
+(`LOG4J_ASYNC_LOGGER_{zwsp}HREAD_NAME_STRATEGY`)
+| `UNCACHED` for JRE 8u102 or later, `CACHED` otherwise
+| Specifies the
link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/ThreadNameCachingStrategy
to use to cache the result of
https://docs.oracle.com/javase/{java-target-version}/docs/api/java/lang/Thread.html#getName()[Thread.getName()].
+
+This setting allows to cache the result of `Thread.getName()` calls:
+
+* a value of `CACHED` stores the name of the current thread in a `ThreadLocal`
field,
+* a value of `UNCACHED` disable caching.
Review Comment:
Fixed
--
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]
