You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@logging.apache.org by "ppkarwasz (via GitHub)" <gi...@apache.org> on 2024/04/30 17:41:55 UTC
[PR] Revamp configuration properties (logging-log4j2)
ppkarwasz opened a new pull request, #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552
This PR:
* removes the names of pre-2.10 property names from the documentation,
* adds a note about fuzzy matching of properties and a list of all prefixes reserved by Log4j,
* splits the system properties into sections according to the component that they apply to,
* updates the description of configuration properties based on the way they are used in the current code.
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1586701230
##########
src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc:
##########
@@ -122,67 +126,9 @@ logging:
Note that Log4j currently does not directly support encrypting the password.
However, Log4j does use Spring's standard APIs to access properties in the Spring configuration so any customizations made to Spring's property handling would apply to the properties Log4j uses as well.
-If more extensive authentication is required an `AuthorizationProvider` can be implemented and the fully qualified class name in the `log4j2.authorizationProvider` system property, in log4j2.component.properties or in Spring's bootstrap.yml using either the `log4j2.authorizationProvider` key or with the key `logging.auth.authorizationProvider`.
+If more extensive authentication is required an `AuthorizationProvider` can be implemented and the fully qualified class name in the xref:manual/configuration.adoc#log4j2.configurationAuthorizationProvider[log4j2.configurationAuthorizationProvider] system property, in `log4j2.component.properties` or in Spring's `bootstrap.yml` using either the `log4j2.authorizationProvider` key or with the key `logging.auth.authorizationProvider`.
Review Comment:
Neither do I. ;-)
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587656204
##########
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()].
Review Comment:
Fixed in 5e9134f9c59fe610c5bd7895354eec0535ad6acf
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587658521
##########
src/site/antora/modules/ROOT/pages/manual/layouts.adoc:
##########
Review Comment:
We should probably add a Spotless configuration to format AsciiDoc files in a way compatible with IDEA.
I reverted the changes.
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1585509159
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -32,7 +32,7 @@ Log4j 2 and onwards use `log4j2.xml`.
====
You can also specify the full path of the configuration file using a system property: +
-`-Dlog4j2.configurationFile=/path/to/log4j2.xml`
+`-Dxref:manual/configuration.adoc#log4j2.configurationFile[log4j2.configurationFile]=/path/to/log4j2.xml`
Review Comment:
@ppkarwasz, please don't use links inside code blocks. I think it is very error-prone. I would rather compose this as follows:
```
You can also specify the full path of the configuration file using the xref:manual/configuration.adoc#log4j2.configurationFile[`log4j2.configurationFile`] system property:
[source,bash]
----
-Dlog4j2.configurationFile=/path/to/log4j2.xml
----
```
I also doubt if using a `.` (dot) in the anchor name works at all. Can you double check this, please? That is, does the link work? Does it cause warning during compilation? etc.
##########
src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc:
##########
@@ -122,67 +126,9 @@ logging:
Note that Log4j currently does not directly support encrypting the password.
However, Log4j does use Spring's standard APIs to access properties in the Spring configuration so any customizations made to Spring's property handling would apply to the properties Log4j uses as well.
-If more extensive authentication is required an `AuthorizationProvider` can be implemented and the fully qualified class name in the `log4j2.authorizationProvider` system property, in log4j2.component.properties or in Spring's bootstrap.yml using either the `log4j2.authorizationProvider` key or with the key `logging.auth.authorizationProvider`.
+If more extensive authentication is required an `AuthorizationProvider` can be implemented and the fully qualified class name in the xref:manual/configuration.adoc#log4j2.configurationAuthorizationProvider[log4j2.configurationAuthorizationProvider] system property, in `log4j2.component.properties` or in Spring's `bootstrap.yml` using either the `log4j2.authorizationProvider` key or with the key `logging.auth.authorizationProvider`.
-TLS can be enabled by adding the following system properties or defining them in log4j2.component.properties
-
-|===
-| Property | Optional or Default Value | Description
-
-| log4j2.trustStoreLocation
-| Optional
-| The location of the trust store.
-If not provided the default trust store will be used.
-
-| log4j2.trustStorePassword
-| Optional
-| Password needed to access the trust store.
-
-| log4j2.trustStorePasswordFile
-| Optional
-| The location of a file that contains the password for the trust store.
-
-| log4j2.trustStorePasswordEnvironmentVariable
-| Optional
-| The name of the environment variable that contains the trust store password.
-
-| log4j2.trustStoreKeyStoreType
-| Required if keystore location provided
-| The type of key store.
-
-| log4j2.trustStoreKeyManagerFactoryAlgorithm
-| Optional
-| Java cryptographic algorithm.
-
-| log4j2.keyStoreLocation
-| Optional
-| The location of the key store.
-If not provided the default key store will be used.
-
-| log4j2.keyStorePassword
-| Optional
-| Password needed to access the key store.
-
-| log4j2.keyStorePasswordFile
-| Optional
-| The location of a file that contains the password for the key store.
-
-| log4j2.keyStorePasswordEnvironmentVariable
-| Optional
-| The name of the environment variable that contains the key store password.
-
-| log4j2.keyStoreType
-| Required if trust store location provided.
-| The type of key store.
-
-| log4j2.keyStoreKeyManagerFactoryAlgorithm
-| Optional
-| Java cryptographic algorithm.
-
-| log4j2.sslVerifyHostName
-| false
-| true or false
-|===
+For the properties required by TLS configuration see xref:manual/configuration.adoc#transport-security[Transport Security].
Review Comment:
```suggestion
For the properties required by TLS configuration see xref:manual/configuration.adoc#transport-security[the Transport Security configuration].
```
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
Review Comment:
AFAIK, `foo#field` is used for instance members, whereas `foo.field` is used for class members.
```suggestion
| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter.ISO_INSTANT]
```
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
Review Comment:
Can you add an explicit reference name to _every_ section, please? This is of crucial importance to avoid breaking links. People tend to change section names without noticing that they implicitly change the reference name and, hence, break the existing links too.
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
+| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates.
+
+| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()]
+| Sets the timezone id used by status logger. See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html[ZoneId] for the accepted formats.
+
+|===
+
+=== Simple logger
+
+The simple logger implementation contained in `log4j-api` can be configured using these properties:
+
+.Simple logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.simplelogLevel]]`log4j2.simplelogLevel`
+
+(`LOG4J_SIMPLELOG_LEVEL`)
+| ERROR
+| Default level for new logger instances.
+
+| [[log4j2.simplelog.loggerName.level]]`log4j2.simplelog.<loggerName>.level`
+
+(`LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL`)
+| value of <<log4j2.simplelogLevel>>
+| Log level for a logger instance named `<loggerName>`.
+
+| [[log4j2.simplelogShowContextMap]]`log4j2.simplelogShowContextMap`
+
+(`LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP`)
+| false
+| If `true`, the full thread context map is included in each log message.
+
+| [[log4j2.simplelogShowlogname]]`log4j2.simplelogShowlogname`
+
+(`LOG4J_SIMPLELOG_SHOWLOGNAME`)
+| false
+| If `true`, the logger name is included in each log message.
+
+| [[log4j2.simplelogShowShortLogname]]`log4j2.simplelogShowShortLogname`
+
+(`LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME`)
+| true
+| If `true`, only the last component of a logger name is included in each log message.
+
+| [[log4j2.simplelogShowdatetime]]`log4j2.simplelogShowdatetime`
+
+(`LOG4J_SIMPLELOG_SHOWDATETIME`)
+| false
+| If `true`, a timestamp is included in each log message.
+
+| [[log4j2.simplelogDateTimeFormat]]`log4j2.simplelogDateTimeFormat`
+
+(`LOG4J_SIMPLELOG_DATE_TIME_FORMAT`)
+| `yyyy/MM/dd HH:mm:ss:SSS zzz`
+| Date-time format to use. Ignored if <<log4j2.simplelogShowdatetime>> is `false`.
+
+| [[log4j2.simplelogLogFile]]`log4j2.simplelogLogFile`
+
+(`LOG4J_SIMPLELOG_LOG_FILE`)
+| System.err
+a| Specifies the output stream used by all loggers:
+
+* `System.err` logs to the standard error output stream,
+* `System.out` logs to the standard output stream,
+* any other value is interpreted as a file name.
+
+|===
+
+[#simple-logger-thread-context]
+=== Thread context (Simple Logger)
+
+The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
+
+[WARNING]
+====
+These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API.
+
+The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
+
+The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
+====
+
+.Thread context configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableThreadContext]]`log4j2.disableThreadContext`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT`)
+| false
+| If `true`, the `ThreadContext` stack and map are disabled.
+
+| [[log4j2.disableThreadContextStack]]`log4j2.disableThreadContextStack`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_STACK`)
+| false
+| If `true`, the `ThreadContext` stack is disabled.
+
+| [[log4j2.disableThreadContextMap]]`log4j2.disableThreadContextMap`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_MAP`)
+| false
+| If `true`, the `ThreadContext` map is disabled.
+
+| [[log4j2.threadContextMap]]`log4j2.threadContextMap`
+
+(`LOG4J_THREAD_CONTEXT_MAP`)
+| `WebApp`
+
+(GC-free mode: `CopyOnWrite`)
+a| Fully specified class name of a custom `ThreadContextMap` implementation class or one of the predefined constants:
+
+* `NoOp`: to disable the thread context,
+* `WebApp`: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks,
+* `CopyOnWrite`: a copy-on-write implementation,
+* `GarbageFree`: a garbage-free implementation.
+
+| [[isThreadContextMapInheritable]]`log4j2.isThreadContextMapInheritable`
+
+(`LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`)
+| false
+| If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
+
+| [[log4j2.garbagefreeThreadContextMap]]`log4j2.garbagefreeThreadContextMap`
+
+(`LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP`)
+| false
+| If set to `true` selects a garbage-free thread context map implementation.
+Requires <<log4j2.enableThreadlocals>> to be also `true`.
+
+|===
+
+== Log4j Core
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration_new.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
+
+=== Async components
+
+The behavior of all three async components (`AsyncLogger`, `AsyncLoggerConfig` and `AsyncAppender`) can be tuned using these properties:
+
+.Common async component configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.formatMsgAsync]]`log4j2.formatMsgAsync`
+
+(`LOG4J_FORMAT_MSG_ASYNC`)
+| false
+| If `false`, Log4j will make sure the message is formatted in the caller thread, otherwise the formatting will occur on the asynchronous thread.
+
+**Remark**: messages annotated with link:../javadoc/log4j-api/org/apache/logging/log4j/message/AsynchronouslyFormattable[AsynchronouslyFormattable] will be formatted on the async thread regardless of this setting.
+
+| [[log4j2.asyncQueueFullPolicy]]`log4j2.asyncQueueFullPolicy`
+
+(`LOG4J_ASYNC_QUEUE_FULL_POLICY`)
+| `Default`
+a| Determines the link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy[AsyncQueueFullPolicy] to use when the underlying async component cannot keep up with the logging rate and the queue is filling up.
+
+It accepts the following values:
+
+* `Default`: blocks the calling thread until the event can be added to the queue.
+
+* `Discard`: when the queue is full, it drops the events whose level is equal or less than the threshold level (see <<log4j2.discardThreshold>>).
+
+* the fully qualified class name of a custom implementation
+
+| [[log4j2.discardThreshold]]`log4j2.discardThreshold`
+
+(`LOG4J_DISCARD_THRESHOLD`)
+| `INFO`
+| Determines the threshold level used by a `Discard` queue full policy.
+Log events whose level is equal or less specific than the threshold level will be discarded during a queue full event.
+See also <<log4j2.asyncQueueFullPolicy>>.
+
+|===
+
+==== `AsyncLogger`
+
+Additional properties supported by `AsyncLogger` are documented in the xref:manual/async.adoc#SysPropsAllAsync[System Properties to configure all asynchronous loggers] table.
+
+==== `AsyncLoggerConfig`
+
+Additional properties supported by `AsyncLoggerConfig` are documented in the xref:manual/async.adoc#SysPropsMixedSync-Async[System Properties to configure mixed asynchronous and normal loggers] table.
+
+=== Context selector
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ContextSelector[ContextSelector] component specifies the strategy used by Log4j to create new logger contexts.
+The choice of `ContextSelector` determines in particular:
+
+* how loggers are divided among logger contexts.
+See xref:manual/logsep.adoc[Log Separation] for details.
+
+* the `Logger` implementation used by Log4j Core.
+See xref:manual/async.adoc[Async Logging] as an example of this usage.
+
+.Context selector configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.contextSelector]]`log4j2.contextSelector`
+
+(`LOG4J_CONTEXT_SELECTOR`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[ClassLoaderContextSelector]
+a|
+Specifies the fully qualified class name of the `ContextSelector` implementation to use.
+
+The implementations available by default are:
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/BasicContextSelector[org.apache.logging.log4j
+.core.selector.BasicContextSelector]: creates a single logger context and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/BasicAsyncLoggerContextSelector[org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector]: creates a single logger context and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[org.apache.logging.log4j.core.selector.ClassLoaderContextSelector]: creates a separate logger context per classloader and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector[org.apache.logging.log4j.core.async.AsyncLoggerContextSelector]: creates a separate logger context per classloader and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/osgi/BundleContextSelector[org.apache.logging.log4j.core.osgi.BundleContextSelector]: creates a separate logger context per OSGi bundle and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/JndiContextSelector[org.apache.logging.log4j.core.selector.JndiContextSelector]: creates loggers contexts based on a JNDI lookup and synchronous loggers.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application]] for details.
+
+|===
+
+=== Configuration factory
+
+Since configuration factories are used to parse the configuration file, they can **only** be configured through global configuration properties.
+
+[WARNING]
+====
+Log4j Core supports both local and remote configuration files.
+If a remote configuration file is used, its transport must be secured.
+See <<transport-security>> for details.
+====
+
+.Configuration factory properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationFactory]]`log4j2.configurationFactory`
+
+(`LOG4J_CONFIGURATION_FACTORY`)
+|
+|
+Specifies the fully qualified class name of the **preferred** link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory[ConfigurationFactory] to use.
+
+Log4j will attempt to use the provided configuration factory before any other factory implementation.
+
+| [[log4j2.configurationFile]]`log4j2.configurationFile`
+
+(`LOG4J_CONFIGURATION_FILE`)
+| xref:manual/configuration.adoc#AutomaticConfiguration[automatically detected]
+a|
+Specifies a comma-separated list of URIs or file paths to Log4j 2 configuration files.
+
+If a relative URL is provided, it is interpreted as:
+
+* path to a file, if the file exists,
+* a classpath resource otherwise.
+
+See also xref:manual/configuration.adoc#AutomaticConfiguration[Automatic Configuration].
+
+| [[log4j2.level]]`log4j2.level`
+
+(`LOG4J_LEVEL`)
+| `ERROR`
+a|
+Specifies the level of the root logger if:
+
+* the default configuration is used,
+
+* or the configuration file does not specify a level for the root logger.
+
+| [[log4j2.mergeStrategy]]`log4j2.mergeStrategy`
+
+(`LOG4J_MERGE_STRATEGY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/DefaultMergeStrategy[DefaultMergeStrategy]
+|
+Specifies the fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/MergeStrategy[MergeStrategy] implementation used to merge multiple configuration files into one.
+
+|===
+
+=== Garbage Collection
+
+.GC properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+
+| [[log4j2.enableDirectEncoders]]`log4j2.enableDirectEncoders`
+
+(`LOG4J_ENABLE_DIRECT_ENCODERS`)
+| `true`
+|
+If `true`, garbage-aware layouts will directly encode log events into https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html[ByteBuffers] provided by appenders.
+
+This prevents the creation temporary multiple `String` and `char[]` temporary objects.
+
+| [[log4j2.initialReusableMsgSize]]`log4j2.initialReusableMsgSize`
+
+(`LOG4J_INITIAL_REUSABLE_MSG_SIZE`)
+| 128
+| In GC-free mode, this property determines the initial size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+| [[log4j2.maxReusableMsgSize]]`log4j2.maxReusableMsgSize`
+
+(`LOG4J_MAX_REUSABLE_MSG_SIZE`)
+| 518
+| In GC-free mode, this property determines the maximum size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+The default value allows is equal to `2 × (2 × log4j.initialReusableMsgSize + 2) + 2` and allows the
+``StringBuilder`` to be resized twice by the current JVM resize algorithm.
+
+| [[log4j2.layoutStringBuilderMaxSize]]`log4j2.layout{zwsp}StringBuilderMaxSize`
+
+(`LOG4J_LAYOUT_{zwsp}STRING_BUILDER_MAX_SIZE`)
+| 2048
+| This property determines the maximum size of the reusable ``StringBuilder``sused to format link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent[LogEvents].
+
+| [[log4j2.unboxRingbufferSize]]`log4j2.unboxRingbufferSize`
+
+(`LOG4J_UNBOX_RINGBUFFER_SIZE`)
+| 32
+|
+The link:../javadoc/log4j-api/org/apache/logging/log4j/util/Unbox[Unbox] utility class can be used by users to format primitive values without incurring in the boxing allocation cost.
+
+This property specifies the maximum number of primitive arguments to a log message that will be cached and usually does not need to be changed.
+
+|===
+
+=== JANSI
+
+If the https://fusesource.github.io/jansi/[JANSI] library is on the runtime classpath of the application, the following property can be used to control its usage:
+
+.JANSI properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.skipJansi]]`log4j2.skipJansi`
+
+(`LOG4J_SKIP_JANSI`)
+| `true`
+a| If the following conditions are satisfied:
+
+* Log4j runs on Windows,
+* this property is set to `false`,
+
+Log4j will use the JANSI library to color the output of the console appender.
+
+|===
+
+=== JNDI
+
+Due to the inherent security problems of https://docs.oracle.com/javase/tutorial/jndi/overview/[JNDI], its usage in Log4j is restricted to the `java:` protocol.
+
+Moreover, each JNDI usage must be **explicitly** enabled by the user through the following configuration properties.
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.enableJndiContextSelector]]`log4j2.enableJndiContextSelector`
+
+(`LOG4J_ENABLE_JNDI_CONTEXT_SELECTOR`)
+| `false`
+|
+When `true` the `JndiContextSelector` is enabled for the `java:` protocol.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application] for more details.
+
+| [[log4j2.enableJndiJdbc]]`log4j2.enableJndiJdbc`
+
+(`LOG4J_ENABLE_JNDI_JDBC`)
+| `false`
+| When `true`, a Log4j JDBC Appender can use JNDI to retrieve a https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[DataSource] using the `java:` protocol.
+
+| [[log4j2.enableJndiJms]]`log4j2.enableJndiJms`
+
+(`LOG4J_ENABLE_JNDI_JMS`)
+| `false`
+| When `true`, a Log4j JMS Appender can use JNDI to retrieve the necessary components using the `java:` protocol.
+
+| [[log4j2.enableJndiLookup]]`log4j2.enableJndiLookup`
+
+(`LOG4J_ENABLE_JNDI_LOOKUP`)
+| `false`
+| When `true`, the Log4j JNDI Lookup can use the `java:` protocol.
+
+|===
+
+=== JMX
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableJmx]]`log4j2.disableJmx`
+
+(`LOG4J_DISABLE_JMX`)
+| `true`
+|
+If `false`, Log4j configuration objects like ``LoggerContext``s, ``Appender``s, ``Logger``s, etc.
+will be instrumented with ``MBean``s and can be remotely monitored and managed.
+
+| [[log4j2.jmxNotifyAsync]]`log4j2.jmxNotifyAsync`
+
+(`LOG4J_JMX_NOTIFY_ASYNC`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true`, Log4j's JMX notifications are sent from a separate background thread, otherwise they are sent from the caller thread.
+
+|===
+
+[#log4j-core-thread-context]
+=== Thread context (Log4j Core)
+
+Log4j Core supports the same properties as Simple Logger for the configuration of the thread context.
+See <<simple-logger-thread-context>> for more details.
+
+[#transport-security]
+=== Transport security
+
+Since configuration files can be used to load arbitrary classes into a Log4j Core `Configuration`, users need to ensure that all the configuration elements come from trusted sources (cf. link:/security#threat-common-config-sources[Thread model] for more information).
+
+In order to protect the user Log4j disables the `http` URI scheme by default and provides several configuration options to ensure secure transport of configuration files:
+
+:jsse-default-keystores: https://docs.oracle.com/en/java/javase/21/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-7D9F43B8-AABF-4C5B-93E6-3AFB18B66150
+
+.Transport security properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationAllowedProtocols]]`log4j2.configuration{zwsp}AllowedProtocols`
+
+(`LOG4J_CONFIGURATION_{zwsp}ALLOWED_PROTOCOLS`)
+| file, https, jar
+|
+A comma separated list of URL protocols that may be used to load any kind of configuration source.
+
+To completely prevent accessing the configuration via the Java https://docs.oracle.com/javase/8/docs/api/java/net/URL.html[URL class] specify a value of `_none`.
+
+// TODO: What about 'jar:http:'?
+
+| [[log4j2.configurationAuthorizationProvider]]`log4j2.configuration{zwsp}AuthorizationProvider`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_PROVIDER`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/BasicAuthorizationProvider[BasicAuthorizationProvider]
+| The fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/AuthorizationProvider[AuthorizationProvider] implementation to use with `http` and `https` URL protocols.
+
+3+h| HTTP Basic authentication
+
+| [[log4j2.configurationAuthorizationEncoding]]`log4j2.configuration{zwsp}AuthorizationEncoding`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_ENCODING`)
+| UTF-8
+| The encoding used in Basic Authentication (cf. https://datatracker.ietf.org/doc/html/rfc7617[RFC 7617]).
+
+| [[log4j2.configurationPassword]]`log4j2.configurationPassword`
+
+(`LOG4J_CONFIGURATION_PASSWORD`)
+|
+| The password to use in HTTP Basic authentication.
+
+If used in conjunction with <<log4j2.configurationPasswordDecryptor>> the contents of this variable are
+interpreted by the decryptor.
+
+| [[log4j2.configurationPasswordDecryptor]]`log4j2.configuration{zwsp}PasswordDecryptor`
+
+(`LOG4J_CONFIGURATION_{zwsp}PASSWORD_DECRYPTOR`)
+|
+| Fully qualified class name of an implementation of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/PasswordDecryptor[PasswordDecryptor] to use for the value of the <<log4j2.configurationPassword>> property.
+
+By default, the literal value of the password is used.
+
+| [[log4j2.configurationUsername]]`log4j2.configurationUsername`
+
+(`LOG4J_CONFIGURATION_USERNAME`)
+|
+| The username used in HTTP Basic authentication.
+
+3+h| TLS server authentication properties
+
+| [[log4j2.trustStoreLocation]]`log4j2.trustStoreLocation`
+
+(`LOG4J_TRUST_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java trust store]
+| The location of the trust store.
+
+| [[log4j2.trustStorePassword]]`log4j2.trustStorePassword`
+
+(`LOG4J_TRUST_STORE_PASSWORD`)
+|
+| The password for the trust store.
+
+| [[log4j2.trustStorePasswordFile]]`log4j2.trustStore{zwsp}PasswordFile`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the trust store.
+
+| [[log4j2.trustStorePasswordEnvironmentVariable]]`log4j2.trustStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains password for the trust store.
+
+| [[log4j2.trustStoreType]]`log4j2.trustStoreType`
+
+(`LOG4J_TRUST_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.trustStoreKeyManagerFactoryAlgorithm]]`log4j2.trustStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_TRUST_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+| [[log4j2.sslVerifyHostName]]`log4j2.sslVerifyHostName`
+
+(`LOG4J_SSL_VERIFY_HOST_NAME`)
+| false
+| If `true` enables verification of the name of the TLS server.
+
+3+h| TLS client authentication properties
+
+| [[log4j2.keyStoreLocation]]`log4j2.keyStoreLocation`
+
+(`LOG4J_KEY_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java key store]
+| The location of the private key store.
+
+| [[log4j2.keyStorePassword]]`log4j2.keyStorePassword`
+
+(`LOG4J_KEY_STORE_PASSWORD`)
+|
+| The password for the private key store.
+
+| [[log4j2.keyStorePasswordFile]]`log4j2.keyStore{zwsp}PasswordFile`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the private key store.
+
+| [[log4j2.keyStorePasswordEnvironmentVariable]]`log4j2.keyStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains the password for the private key store.
+
+| [[log4j2.keyStoreType]]`log4j2.keyStoreType`
+
+(`LOG4J_KEY_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.keyStoreKeyManagerFactoryAlgorithm]]`log4j2.keyStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_KEY_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+|===
+
+=== Miscellaneous properties
+
+.Miscellaneous configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.clock]]`log4j2.clock`
+
+(`LOG4J_CLOCK`)
+| `SystemClock`
+a|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/Clock[Clock] implementation used to timestamp log events.
+
+The possible values are:
+
+* `SystemClock`: uses the best available system clock as time source.
+See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/Clock.html#systemDefaultZone--[Clock#systemDefaultZone] for details.
+
+* `SystemMillisClock`: same as `SystemClock`, but truncates the result to a millisecond.
+
+* `CachedClock`: uses a separate thread to update the timestamp value.
+See link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/CachedClock[JavaDoc] for details.
+
+* `CoarseCachedClock`: alternative implementation of `CachedClock` with a slightly lower precision.
+See link:..//javadoc/log4j-core/org/apache/logging/log4j/core/util/CoarseCachedClock[JavaDoc] for details.
+
+* the fully qualified name of a custom implementation.
+
+| [[log4j2.contextDataInjector]]`log4j2.contextDataInjector`
+
+(`LOG4J_CONTEXT_DATA_INJECTOR`)
+| depends on the `ThreadContextMap` implementation
+| Fully specified class name of a link:../javadoc/log4j-core/org/apache/logging/log4j/core/ContextDataInjector[ContextDataInjector] implementation.
+
+The default implementation uses all implementations of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ContextDataProvider[ContextDataProvider] registered with `ServiceLoader`.
+
+| [[log4j2.logEventFactory]]`log4j2.logEventFactory`
+
+(`LOG4J_LOG_EVENT_FACTORY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/DefaultLogEventFactory[DefaultLogEventFactory]
+
+(GC-free mode: link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/ReusableLogEventFactory[ReusableLogEventFactory])
+|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/LogEventFactory[LogEventFactory]
+implementation to use to create log events.
+
+| [[log4j2.shutdownHookEnabled]]`log4j2.shutdownHookEnabled`
+
+(`LOG4J_SHUTDOWN_HOOK_ENABLED`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true` a shutdown hook will be installed to stop all logger contexts when the system stops.
+
+| [[log4j2.shutdownCallbackRegistry]]`log4j2.shutdownCallbackRegistry`
+
+(`LOG4J_SHUTDOWN_CALLBACK_REGISTRY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/DefaultShutdownCallbackRegistry[DefaultShutdownCallbackRegistry]
+|
+The fully qualified class name of a link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry[ShutdownCallbackRegistry] implementation.
+Integrators can use this to customize the shutdown order of the JVM.
+
+The default implementation executes all shutdown actions in a separate `Thread` registered through https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#addShutdownHook-java.lang.Thread-[Runtime#addShutdownHook()].
+
+
+| [[log4j2.uuidSequence]]`log4j2.uuidSequence`
+
+(`LOG4J_UUID_SEQUENCE`)
+| 0
+|
+Provides a `long` see to the UUID generator used by the `%uuid` pattern converter.
+
+Can be used to assure uniqueness of UUIDs generated by multiple JVMs on the same machine.
Review Comment:
Shouldn't this better be moved to the `PL` docs?
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
+| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates.
+
+| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()]
+| Sets the timezone id used by status logger. See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html[ZoneId] for the accepted formats.
+
+|===
+
+=== Simple logger
+
+The simple logger implementation contained in `log4j-api` can be configured using these properties:
+
+.Simple logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.simplelogLevel]]`log4j2.simplelogLevel`
+
+(`LOG4J_SIMPLELOG_LEVEL`)
+| ERROR
+| Default level for new logger instances.
+
+| [[log4j2.simplelog.loggerName.level]]`log4j2.simplelog.<loggerName>.level`
+
+(`LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL`)
+| value of <<log4j2.simplelogLevel>>
+| Log level for a logger instance named `<loggerName>`.
+
+| [[log4j2.simplelogShowContextMap]]`log4j2.simplelogShowContextMap`
+
+(`LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP`)
+| false
+| If `true`, the full thread context map is included in each log message.
+
+| [[log4j2.simplelogShowlogname]]`log4j2.simplelogShowlogname`
+
+(`LOG4J_SIMPLELOG_SHOWLOGNAME`)
+| false
+| If `true`, the logger name is included in each log message.
+
+| [[log4j2.simplelogShowShortLogname]]`log4j2.simplelogShowShortLogname`
+
+(`LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME`)
+| true
+| If `true`, only the last component of a logger name is included in each log message.
+
+| [[log4j2.simplelogShowdatetime]]`log4j2.simplelogShowdatetime`
+
+(`LOG4J_SIMPLELOG_SHOWDATETIME`)
+| false
+| If `true`, a timestamp is included in each log message.
+
+| [[log4j2.simplelogDateTimeFormat]]`log4j2.simplelogDateTimeFormat`
+
+(`LOG4J_SIMPLELOG_DATE_TIME_FORMAT`)
+| `yyyy/MM/dd HH:mm:ss:SSS zzz`
+| Date-time format to use. Ignored if <<log4j2.simplelogShowdatetime>> is `false`.
+
+| [[log4j2.simplelogLogFile]]`log4j2.simplelogLogFile`
+
+(`LOG4J_SIMPLELOG_LOG_FILE`)
+| System.err
+a| Specifies the output stream used by all loggers:
+
+* `System.err` logs to the standard error output stream,
+* `System.out` logs to the standard output stream,
+* any other value is interpreted as a file name.
+
+|===
+
+[#simple-logger-thread-context]
+=== Thread context (Simple Logger)
+
+The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
+
+[WARNING]
+====
+These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API.
+
+The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
+
+The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
+====
+
+.Thread context configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableThreadContext]]`log4j2.disableThreadContext`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT`)
+| false
+| If `true`, the `ThreadContext` stack and map are disabled.
+
+| [[log4j2.disableThreadContextStack]]`log4j2.disableThreadContextStack`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_STACK`)
+| false
+| If `true`, the `ThreadContext` stack is disabled.
+
+| [[log4j2.disableThreadContextMap]]`log4j2.disableThreadContextMap`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_MAP`)
+| false
+| If `true`, the `ThreadContext` map is disabled.
+
+| [[log4j2.threadContextMap]]`log4j2.threadContextMap`
+
+(`LOG4J_THREAD_CONTEXT_MAP`)
+| `WebApp`
+
+(GC-free mode: `CopyOnWrite`)
+a| Fully specified class name of a custom `ThreadContextMap` implementation class or one of the predefined constants:
+
+* `NoOp`: to disable the thread context,
+* `WebApp`: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks,
+* `CopyOnWrite`: a copy-on-write implementation,
+* `GarbageFree`: a garbage-free implementation.
+
+| [[isThreadContextMapInheritable]]`log4j2.isThreadContextMapInheritable`
+
+(`LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`)
+| false
+| If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
+
+| [[log4j2.garbagefreeThreadContextMap]]`log4j2.garbagefreeThreadContextMap`
+
+(`LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP`)
+| false
+| If set to `true` selects a garbage-free thread context map implementation.
+Requires <<log4j2.enableThreadlocals>> to be also `true`.
+
+|===
+
+== Log4j Core
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration_new.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
+
+=== Async components
+
+The behavior of all three async components (`AsyncLogger`, `AsyncLoggerConfig` and `AsyncAppender`) can be tuned using these properties:
+
+.Common async component configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.formatMsgAsync]]`log4j2.formatMsgAsync`
+
+(`LOG4J_FORMAT_MSG_ASYNC`)
+| false
+| If `false`, Log4j will make sure the message is formatted in the caller thread, otherwise the formatting will occur on the asynchronous thread.
+
+**Remark**: messages annotated with link:../javadoc/log4j-api/org/apache/logging/log4j/message/AsynchronouslyFormattable[AsynchronouslyFormattable] will be formatted on the async thread regardless of this setting.
+
+| [[log4j2.asyncQueueFullPolicy]]`log4j2.asyncQueueFullPolicy`
+
+(`LOG4J_ASYNC_QUEUE_FULL_POLICY`)
+| `Default`
+a| Determines the link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy[AsyncQueueFullPolicy] to use when the underlying async component cannot keep up with the logging rate and the queue is filling up.
+
+It accepts the following values:
+
+* `Default`: blocks the calling thread until the event can be added to the queue.
+
+* `Discard`: when the queue is full, it drops the events whose level is equal or less than the threshold level (see <<log4j2.discardThreshold>>).
+
+* the fully qualified class name of a custom implementation
+
+| [[log4j2.discardThreshold]]`log4j2.discardThreshold`
+
+(`LOG4J_DISCARD_THRESHOLD`)
+| `INFO`
+| Determines the threshold level used by a `Discard` queue full policy.
+Log events whose level is equal or less specific than the threshold level will be discarded during a queue full event.
+See also <<log4j2.asyncQueueFullPolicy>>.
+
+|===
+
+==== `AsyncLogger`
+
+Additional properties supported by `AsyncLogger` are documented in the xref:manual/async.adoc#SysPropsAllAsync[System Properties to configure all asynchronous loggers] table.
+
+==== `AsyncLoggerConfig`
+
+Additional properties supported by `AsyncLoggerConfig` are documented in the xref:manual/async.adoc#SysPropsMixedSync-Async[System Properties to configure mixed asynchronous and normal loggers] table.
+
+=== Context selector
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ContextSelector[ContextSelector] component specifies the strategy used by Log4j to create new logger contexts.
+The choice of `ContextSelector` determines in particular:
+
+* how loggers are divided among logger contexts.
+See xref:manual/logsep.adoc[Log Separation] for details.
+
+* the `Logger` implementation used by Log4j Core.
+See xref:manual/async.adoc[Async Logging] as an example of this usage.
+
+.Context selector configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.contextSelector]]`log4j2.contextSelector`
+
+(`LOG4J_CONTEXT_SELECTOR`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[ClassLoaderContextSelector]
+a|
+Specifies the fully qualified class name of the `ContextSelector` implementation to use.
+
+The implementations available by default are:
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/BasicContextSelector[org.apache.logging.log4j
+.core.selector.BasicContextSelector]: creates a single logger context and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/BasicAsyncLoggerContextSelector[org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector]: creates a single logger context and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[org.apache.logging.log4j.core.selector.ClassLoaderContextSelector]: creates a separate logger context per classloader and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector[org.apache.logging.log4j.core.async.AsyncLoggerContextSelector]: creates a separate logger context per classloader and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/osgi/BundleContextSelector[org.apache.logging.log4j.core.osgi.BundleContextSelector]: creates a separate logger context per OSGi bundle and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/JndiContextSelector[org.apache.logging.log4j.core.selector.JndiContextSelector]: creates loggers contexts based on a JNDI lookup and synchronous loggers.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application]] for details.
+
+|===
+
+=== Configuration factory
+
+Since configuration factories are used to parse the configuration file, they can **only** be configured through global configuration properties.
+
+[WARNING]
+====
+Log4j Core supports both local and remote configuration files.
+If a remote configuration file is used, its transport must be secured.
+See <<transport-security>> for details.
+====
+
+.Configuration factory properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationFactory]]`log4j2.configurationFactory`
+
+(`LOG4J_CONFIGURATION_FACTORY`)
+|
+|
+Specifies the fully qualified class name of the **preferred** link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory[ConfigurationFactory] to use.
+
+Log4j will attempt to use the provided configuration factory before any other factory implementation.
+
+| [[log4j2.configurationFile]]`log4j2.configurationFile`
+
+(`LOG4J_CONFIGURATION_FILE`)
+| xref:manual/configuration.adoc#AutomaticConfiguration[automatically detected]
+a|
+Specifies a comma-separated list of URIs or file paths to Log4j 2 configuration files.
+
+If a relative URL is provided, it is interpreted as:
+
+* path to a file, if the file exists,
+* a classpath resource otherwise.
+
+See also xref:manual/configuration.adoc#AutomaticConfiguration[Automatic Configuration].
+
+| [[log4j2.level]]`log4j2.level`
+
+(`LOG4J_LEVEL`)
+| `ERROR`
+a|
+Specifies the level of the root logger if:
+
+* the default configuration is used,
+
+* or the configuration file does not specify a level for the root logger.
+
+| [[log4j2.mergeStrategy]]`log4j2.mergeStrategy`
+
+(`LOG4J_MERGE_STRATEGY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/DefaultMergeStrategy[DefaultMergeStrategy]
+|
+Specifies the fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/MergeStrategy[MergeStrategy] implementation used to merge multiple configuration files into one.
+
+|===
+
+=== Garbage Collection
+
+.GC properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+
+| [[log4j2.enableDirectEncoders]]`log4j2.enableDirectEncoders`
+
+(`LOG4J_ENABLE_DIRECT_ENCODERS`)
+| `true`
+|
+If `true`, garbage-aware layouts will directly encode log events into https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html[ByteBuffers] provided by appenders.
+
+This prevents the creation temporary multiple `String` and `char[]` temporary objects.
+
+| [[log4j2.initialReusableMsgSize]]`log4j2.initialReusableMsgSize`
+
+(`LOG4J_INITIAL_REUSABLE_MSG_SIZE`)
+| 128
+| In GC-free mode, this property determines the initial size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+| [[log4j2.maxReusableMsgSize]]`log4j2.maxReusableMsgSize`
+
+(`LOG4J_MAX_REUSABLE_MSG_SIZE`)
+| 518
+| In GC-free mode, this property determines the maximum size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+The default value allows is equal to `2 × (2 × log4j.initialReusableMsgSize + 2) + 2` and allows the
+``StringBuilder`` to be resized twice by the current JVM resize algorithm.
+
+| [[log4j2.layoutStringBuilderMaxSize]]`log4j2.layout{zwsp}StringBuilderMaxSize`
+
+(`LOG4J_LAYOUT_{zwsp}STRING_BUILDER_MAX_SIZE`)
+| 2048
+| This property determines the maximum size of the reusable ``StringBuilder``sused to format link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent[LogEvents].
+
+| [[log4j2.unboxRingbufferSize]]`log4j2.unboxRingbufferSize`
+
+(`LOG4J_UNBOX_RINGBUFFER_SIZE`)
+| 32
+|
+The link:../javadoc/log4j-api/org/apache/logging/log4j/util/Unbox[Unbox] utility class can be used by users to format primitive values without incurring in the boxing allocation cost.
+
+This property specifies the maximum number of primitive arguments to a log message that will be cached and usually does not need to be changed.
+
+|===
+
+=== JANSI
+
+If the https://fusesource.github.io/jansi/[JANSI] library is on the runtime classpath of the application, the following property can be used to control its usage:
+
+.JANSI properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.skipJansi]]`log4j2.skipJansi`
+
+(`LOG4J_SKIP_JANSI`)
+| `true`
+a| If the following conditions are satisfied:
+
+* Log4j runs on Windows,
+* this property is set to `false`,
+
+Log4j will use the JANSI library to color the output of the console appender.
+
+|===
+
+=== JNDI
+
+Due to the inherent security problems of https://docs.oracle.com/javase/tutorial/jndi/overview/[JNDI], its usage in Log4j is restricted to the `java:` protocol.
+
+Moreover, each JNDI usage must be **explicitly** enabled by the user through the following configuration properties.
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.enableJndiContextSelector]]`log4j2.enableJndiContextSelector`
+
+(`LOG4J_ENABLE_JNDI_CONTEXT_SELECTOR`)
+| `false`
+|
+When `true` the `JndiContextSelector` is enabled for the `java:` protocol.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application] for more details.
+
+| [[log4j2.enableJndiJdbc]]`log4j2.enableJndiJdbc`
+
+(`LOG4J_ENABLE_JNDI_JDBC`)
+| `false`
+| When `true`, a Log4j JDBC Appender can use JNDI to retrieve a https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[DataSource] using the `java:` protocol.
+
+| [[log4j2.enableJndiJms]]`log4j2.enableJndiJms`
+
+(`LOG4J_ENABLE_JNDI_JMS`)
+| `false`
+| When `true`, a Log4j JMS Appender can use JNDI to retrieve the necessary components using the `java:` protocol.
+
+| [[log4j2.enableJndiLookup]]`log4j2.enableJndiLookup`
+
+(`LOG4J_ENABLE_JNDI_LOOKUP`)
+| `false`
+| When `true`, the Log4j JNDI Lookup can use the `java:` protocol.
+
+|===
+
+=== JMX
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableJmx]]`log4j2.disableJmx`
+
+(`LOG4J_DISABLE_JMX`)
+| `true`
+|
+If `false`, Log4j configuration objects like ``LoggerContext``s, ``Appender``s, ``Logger``s, etc.
+will be instrumented with ``MBean``s and can be remotely monitored and managed.
+
+| [[log4j2.jmxNotifyAsync]]`log4j2.jmxNotifyAsync`
+
+(`LOG4J_JMX_NOTIFY_ASYNC`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true`, Log4j's JMX notifications are sent from a separate background thread, otherwise they are sent from the caller thread.
+
+|===
+
+[#log4j-core-thread-context]
+=== Thread context (Log4j Core)
+
+Log4j Core supports the same properties as Simple Logger for the configuration of the thread context.
+See <<simple-logger-thread-context>> for more details.
+
+[#transport-security]
+=== Transport security
+
+Since configuration files can be used to load arbitrary classes into a Log4j Core `Configuration`, users need to ensure that all the configuration elements come from trusted sources (cf. link:/security#threat-common-config-sources[Thread model] for more information).
+
+In order to protect the user Log4j disables the `http` URI scheme by default and provides several configuration options to ensure secure transport of configuration files:
+
+:jsse-default-keystores: https://docs.oracle.com/en/java/javase/21/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-7D9F43B8-AABF-4C5B-93E6-3AFB18B66150
+
+.Transport security properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationAllowedProtocols]]`log4j2.configuration{zwsp}AllowedProtocols`
+
+(`LOG4J_CONFIGURATION_{zwsp}ALLOWED_PROTOCOLS`)
+| file, https, jar
+|
+A comma separated list of URL protocols that may be used to load any kind of configuration source.
+
+To completely prevent accessing the configuration via the Java https://docs.oracle.com/javase/8/docs/api/java/net/URL.html[URL class] specify a value of `_none`.
+
+// TODO: What about 'jar:http:'?
+
+| [[log4j2.configurationAuthorizationProvider]]`log4j2.configuration{zwsp}AuthorizationProvider`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_PROVIDER`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/BasicAuthorizationProvider[BasicAuthorizationProvider]
+| The fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/AuthorizationProvider[AuthorizationProvider] implementation to use with `http` and `https` URL protocols.
+
+3+h| HTTP Basic authentication
+
+| [[log4j2.configurationAuthorizationEncoding]]`log4j2.configuration{zwsp}AuthorizationEncoding`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_ENCODING`)
+| UTF-8
+| The encoding used in Basic Authentication (cf. https://datatracker.ietf.org/doc/html/rfc7617[RFC 7617]).
+
+| [[log4j2.configurationPassword]]`log4j2.configurationPassword`
+
+(`LOG4J_CONFIGURATION_PASSWORD`)
+|
+| The password to use in HTTP Basic authentication.
+
+If used in conjunction with <<log4j2.configurationPasswordDecryptor>> the contents of this variable are
+interpreted by the decryptor.
+
+| [[log4j2.configurationPasswordDecryptor]]`log4j2.configuration{zwsp}PasswordDecryptor`
+
+(`LOG4J_CONFIGURATION_{zwsp}PASSWORD_DECRYPTOR`)
+|
+| Fully qualified class name of an implementation of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/PasswordDecryptor[PasswordDecryptor] to use for the value of the <<log4j2.configurationPassword>> property.
+
+By default, the literal value of the password is used.
+
+| [[log4j2.configurationUsername]]`log4j2.configurationUsername`
+
+(`LOG4J_CONFIGURATION_USERNAME`)
+|
+| The username used in HTTP Basic authentication.
+
+3+h| TLS server authentication properties
+
+| [[log4j2.trustStoreLocation]]`log4j2.trustStoreLocation`
+
+(`LOG4J_TRUST_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java trust store]
+| The location of the trust store.
+
+| [[log4j2.trustStorePassword]]`log4j2.trustStorePassword`
+
+(`LOG4J_TRUST_STORE_PASSWORD`)
+|
+| The password for the trust store.
+
+| [[log4j2.trustStorePasswordFile]]`log4j2.trustStore{zwsp}PasswordFile`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the trust store.
+
+| [[log4j2.trustStorePasswordEnvironmentVariable]]`log4j2.trustStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains password for the trust store.
+
+| [[log4j2.trustStoreType]]`log4j2.trustStoreType`
+
+(`LOG4J_TRUST_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.trustStoreKeyManagerFactoryAlgorithm]]`log4j2.trustStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_TRUST_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+| [[log4j2.sslVerifyHostName]]`log4j2.sslVerifyHostName`
+
+(`LOG4J_SSL_VERIFY_HOST_NAME`)
+| false
+| If `true` enables verification of the name of the TLS server.
+
+3+h| TLS client authentication properties
+
+| [[log4j2.keyStoreLocation]]`log4j2.keyStoreLocation`
+
+(`LOG4J_KEY_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java key store]
+| The location of the private key store.
+
+| [[log4j2.keyStorePassword]]`log4j2.keyStorePassword`
+
+(`LOG4J_KEY_STORE_PASSWORD`)
+|
+| The password for the private key store.
+
+| [[log4j2.keyStorePasswordFile]]`log4j2.keyStore{zwsp}PasswordFile`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the private key store.
+
+| [[log4j2.keyStorePasswordEnvironmentVariable]]`log4j2.keyStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains the password for the private key store.
+
+| [[log4j2.keyStoreType]]`log4j2.keyStoreType`
+
+(`LOG4J_KEY_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.keyStoreKeyManagerFactoryAlgorithm]]`log4j2.keyStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_KEY_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+|===
+
+=== Miscellaneous properties
+
+.Miscellaneous configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.clock]]`log4j2.clock`
+
+(`LOG4J_CLOCK`)
+| `SystemClock`
+a|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/Clock[Clock] implementation used to timestamp log events.
+
+The possible values are:
+
+* `SystemClock`: uses the best available system clock as time source.
+See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/Clock.html#systemDefaultZone--[Clock#systemDefaultZone] for details.
+
+* `SystemMillisClock`: same as `SystemClock`, but truncates the result to a millisecond.
+
+* `CachedClock`: uses a separate thread to update the timestamp value.
+See link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/CachedClock[JavaDoc] for details.
+
+* `CoarseCachedClock`: alternative implementation of `CachedClock` with a slightly lower precision.
+See link:..//javadoc/log4j-core/org/apache/logging/log4j/core/util/CoarseCachedClock[JavaDoc] for details.
+
+* the fully qualified name of a custom implementation.
+
+| [[log4j2.contextDataInjector]]`log4j2.contextDataInjector`
+
+(`LOG4J_CONTEXT_DATA_INJECTOR`)
+| depends on the `ThreadContextMap` implementation
+| Fully specified class name of a link:../javadoc/log4j-core/org/apache/logging/log4j/core/ContextDataInjector[ContextDataInjector] implementation.
+
+The default implementation uses all implementations of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ContextDataProvider[ContextDataProvider] registered with `ServiceLoader`.
+
+| [[log4j2.logEventFactory]]`log4j2.logEventFactory`
+
+(`LOG4J_LOG_EVENT_FACTORY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/DefaultLogEventFactory[DefaultLogEventFactory]
+
+(GC-free mode: link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/ReusableLogEventFactory[ReusableLogEventFactory])
+|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/LogEventFactory[LogEventFactory]
+implementation to use to create log events.
+
+| [[log4j2.shutdownHookEnabled]]`log4j2.shutdownHookEnabled`
+
+(`LOG4J_SHUTDOWN_HOOK_ENABLED`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true` a shutdown hook will be installed to stop all logger contexts when the system stops.
+
+| [[log4j2.shutdownCallbackRegistry]]`log4j2.shutdownCallbackRegistry`
+
+(`LOG4J_SHUTDOWN_CALLBACK_REGISTRY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/DefaultShutdownCallbackRegistry[DefaultShutdownCallbackRegistry]
+|
+The fully qualified class name of a link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry[ShutdownCallbackRegistry] implementation.
+Integrators can use this to customize the shutdown order of the JVM.
+
+The default implementation executes all shutdown actions in a separate `Thread` registered through https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#addShutdownHook-java.lang.Thread-[Runtime#addShutdownHook()].
+
+
+| [[log4j2.uuidSequence]]`log4j2.uuidSequence`
+
+(`LOG4J_UUID_SEQUENCE`)
+| 0
+|
+Provides a `long` see to the UUID generator used by the `%uuid` pattern converter.
+
+Can be used to assure uniqueness of UUIDs generated by multiple JVMs on the same machine.
+
+| [[log4j2.messageFactory]]`log4j2.messageFactory`
+
+(`LOG4J_MESSAGE_FACTORY`)
+| link:../javadoc/log4j-api/org/apache/logging/log4j/message/ParameterizedMessageFactory[ParameterizeMessageFactory]
+
+(GC-free mode: link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessageFactory[ReusableMessageFactory])
+| Default message factory used by loggers if no factory was specified.
+
+| [[log4j2.flowMessageFactory]]`log4j2.flowMessageFactory`
+
+(`LOG4J_FLOW_MESSAGE_FACTORY`)
+| link:../javadoc/log4j-api/org/apache/logging/log4j/message/DefaultFlowMessageFactory[DefaultFlowMessageFactory]
+| Default flow message factory used by Loggers.
+
+| [[log4j2.loggerContextStacktraceOnStart]]`log4j2.loggerContext{zwsp}StacktraceOnStart`
+
+(`LOG4J_LOGGER_CONTEXT_{zwsp}STACKTRACE_ON_START`)
+| `false`
+| Prints a stacktrace to the xref:manual/configuration.adoc#StatusMessages[status logger] at `DEBUG` level when the LoggerContext is started.
+
+For debug purposes only.
+
+| [[log4j2.scriptEnableLanguages]]`log4j2.scriptEnableLanguages`
+
+(`LOG4J_SCRIPT_ENABLE_LANGUAGES`)
+|
+| The list of script languages that are allowed to execute.
+
+The names specified must correspond to those returned by https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/script/ScriptEngineFactory.html#getNames--[ScriptEngineFactory#getNames()].
+
+|===
+
+== JUL-to-Log4j API bridge
+
+The JUL-to-Log4j API bridge provides the following configuration properties:
+
+.JUL configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.julLevelConverter]]`log4j2.julLevelConverter`
+
+(`LOG4J_JUL_LEVEL_CONVERTER`)
+|
+|
+Fully qualified name of an alternative `org.apache.logging.log4j.jul.LevelConverter` implementation.
+
+See xref:log4j-jul.adoc#default-level-conversions[Default Level Conversions] for the default implementation.
+
+| [[log4j2.julLoggerAdapter]]`log4j2.julLoggerAdapter`
+
+(`LOG4J_JUL_LOGGER_ADAPTER`)
+| depends on classpath
+a|
+This property allows users to choose between two implementation of the logging bridge:
+
+* `org.apache.logging.log4j.jul.CoreLoggerAdapter` (default if `log4j-core` present) allows users to modify the Log4j Core configuration through the JUL https://docs.oracle.com/javase/8/docs/api/java/util/logging/Logger.html[Logger] interface,
+
+* `org.apache.logging.log4j.jul.ApiLoggerAdapter` (default if `log4j-core` absent) disables the level mutators in the JUL `Logger` interface.
+
+|===
+
+== Log4j Spring Boot
+
+The Log4j Spring Boot module supports the following configuration properties:
+
+.Spring Boot configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableCloudConfigLoggingSystem]]`log4j2.disable{zwsp}CloudConfigLoggingSystem`
+
+(`LOG4J_DISABLE_{zwsp}CLOUD_CONFIG_LOGGING_SYSTEM`)
+| `false`
+| Disables the usage of the Spring Boot `Log4j2CloudConfigLoggingSystem`.
+
+|===
+
+[#property-sources]
Review Comment:
I would have expected this section at the top, before starting to list properties.
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
Review Comment:
Reference names for level-1 headers are redundant.
```suggestion
```
##########
src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc:
##########
@@ -24,7 +24,11 @@ Spring Boot applications initialize logging 3 times.
. SpringApplication declares a Logger.
This Logger will be initialized using Log4j's "normal" mechanisms.
-Thus a system property named log4j2.configurationFile will be checked to see if a specific configuration file has been provided, otherwise it will search for a configuration file on the classpath.
+Thus a system property named xref:manual/configuration.adoc#log4j2.configurationFile[log4j2.configurationFile] will be
+checked
+to see if a
+specific configuration
+file has been provided, otherwise it will search for a configuration file on the classpath.
Review Comment:
```suggestion
Thus the xref:manual/configuration.adoc#log4j2.configurationFile[`log4j2.configurationFile`] system property will be checked to see if a specific configuration file has been provided, otherwise it will search for a configuration file on the classpath.
```
##########
src/site/antora/modules/ROOT/pages/log4j-jmx-gui.adoc:
##########
@@ -23,5 +23,5 @@ The client GUI can be run as a stand-alone application or as a JConsole plug-in.
====
The Java VM to be monitored has to enable Log4j JMX support, set the following system property when starting the Java VM:
-`log4j2.disableJmx=false`
+`xref:manual/configuration.adoc#log4j2.disableJmx[log4j2.disableJmx]=false`
Review Comment:
See my earlier comment – please don't use links inside code blocks.
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
Review Comment:
```suggestion
In this mode Log4j uses ``ThreadLocal``s for object pooling to prevent object allocations.
```
##########
src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc:
##########
@@ -122,67 +126,9 @@ logging:
Note that Log4j currently does not directly support encrypting the password.
However, Log4j does use Spring's standard APIs to access properties in the Spring configuration so any customizations made to Spring's property handling would apply to the properties Log4j uses as well.
-If more extensive authentication is required an `AuthorizationProvider` can be implemented and the fully qualified class name in the `log4j2.authorizationProvider` system property, in log4j2.component.properties or in Spring's bootstrap.yml using either the `log4j2.authorizationProvider` key or with the key `logging.auth.authorizationProvider`.
+If more extensive authentication is required an `AuthorizationProvider` can be implemented and the fully qualified class name in the xref:manual/configuration.adoc#log4j2.configurationAuthorizationProvider[log4j2.configurationAuthorizationProvider] system property, in `log4j2.component.properties` or in Spring's `bootstrap.yml` using either the `log4j2.authorizationProvider` key or with the key `logging.auth.authorizationProvider`.
Review Comment:
I read this sentence 3 times and I still don't understand what it is trying to say.
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -127,9 +127,9 @@ Note the `2` in the file name!
(See xref:manual/configuration.adoc[the Configuration page] for more details.)
. Increase the logging verbosity of the internal status logger: +
-`-Dlog4j2.statusLoggerLevel=TRACE`
+`-Dxref:manual/configuration.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel]=TRACE`
-. Enable all internal debug logging: `-Dlog4j2.debug`.
+. Enable all internal debug logging: `-Dxref:manual/configuration.adoc#log4j2.debug[log4j2.debug]`.
Review Comment:
See my earlier comment – please don't use links inside code blocks.
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
Review Comment:
Let's not advocate for a broken feature:
```suggestion
Can be overridden by <<log4j2.debug>>.
```
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
+| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates.
+
+| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()]
Review Comment:
```suggestion
| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId.systemDefault()]
```
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
+| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates.
+
+| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()]
+| Sets the timezone id used by status logger. See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html[ZoneId] for the accepted formats.
+
+|===
+
+=== Simple logger
+
+The simple logger implementation contained in `log4j-api` can be configured using these properties:
+
+.Simple logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.simplelogLevel]]`log4j2.simplelogLevel`
+
+(`LOG4J_SIMPLELOG_LEVEL`)
+| ERROR
+| Default level for new logger instances.
+
+| [[log4j2.simplelog.loggerName.level]]`log4j2.simplelog.<loggerName>.level`
+
+(`LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL`)
+| value of <<log4j2.simplelogLevel>>
+| Log level for a logger instance named `<loggerName>`.
+
+| [[log4j2.simplelogShowContextMap]]`log4j2.simplelogShowContextMap`
+
+(`LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP`)
+| false
+| If `true`, the full thread context map is included in each log message.
+
+| [[log4j2.simplelogShowlogname]]`log4j2.simplelogShowlogname`
+
+(`LOG4J_SIMPLELOG_SHOWLOGNAME`)
+| false
+| If `true`, the logger name is included in each log message.
+
+| [[log4j2.simplelogShowShortLogname]]`log4j2.simplelogShowShortLogname`
+
+(`LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME`)
+| true
+| If `true`, only the last component of a logger name is included in each log message.
+
+| [[log4j2.simplelogShowdatetime]]`log4j2.simplelogShowdatetime`
+
+(`LOG4J_SIMPLELOG_SHOWDATETIME`)
+| false
+| If `true`, a timestamp is included in each log message.
+
+| [[log4j2.simplelogDateTimeFormat]]`log4j2.simplelogDateTimeFormat`
+
+(`LOG4J_SIMPLELOG_DATE_TIME_FORMAT`)
+| `yyyy/MM/dd HH:mm:ss:SSS zzz`
+| Date-time format to use. Ignored if <<log4j2.simplelogShowdatetime>> is `false`.
+
+| [[log4j2.simplelogLogFile]]`log4j2.simplelogLogFile`
+
+(`LOG4J_SIMPLELOG_LOG_FILE`)
+| System.err
+a| Specifies the output stream used by all loggers:
+
+* `System.err` logs to the standard error output stream,
+* `System.out` logs to the standard output stream,
+* any other value is interpreted as a file name.
+
+|===
+
+[#simple-logger-thread-context]
+=== Thread context (Simple Logger)
+
+The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
+
+[WARNING]
+====
+These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API.
+
+The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
+
+The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
+====
+
+.Thread context configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableThreadContext]]`log4j2.disableThreadContext`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT`)
+| false
+| If `true`, the `ThreadContext` stack and map are disabled.
+
+| [[log4j2.disableThreadContextStack]]`log4j2.disableThreadContextStack`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_STACK`)
+| false
+| If `true`, the `ThreadContext` stack is disabled.
+
+| [[log4j2.disableThreadContextMap]]`log4j2.disableThreadContextMap`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_MAP`)
+| false
+| If `true`, the `ThreadContext` map is disabled.
+
+| [[log4j2.threadContextMap]]`log4j2.threadContextMap`
+
+(`LOG4J_THREAD_CONTEXT_MAP`)
+| `WebApp`
+
+(GC-free mode: `CopyOnWrite`)
+a| Fully specified class name of a custom `ThreadContextMap` implementation class or one of the predefined constants:
+
+* `NoOp`: to disable the thread context,
+* `WebApp`: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks,
+* `CopyOnWrite`: a copy-on-write implementation,
+* `GarbageFree`: a garbage-free implementation.
+
+| [[isThreadContextMapInheritable]]`log4j2.isThreadContextMapInheritable`
+
+(`LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`)
+| false
+| If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
+
+| [[log4j2.garbagefreeThreadContextMap]]`log4j2.garbagefreeThreadContextMap`
+
+(`LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP`)
+| false
+| If set to `true` selects a garbage-free thread context map implementation.
+Requires <<log4j2.enableThreadlocals>> to be also `true`.
+
+|===
+
+== Log4j Core
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration_new.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
+
+=== Async components
+
+The behavior of all three async components (`AsyncLogger`, `AsyncLoggerConfig` and `AsyncAppender`) can be tuned using these properties:
+
+.Common async component configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.formatMsgAsync]]`log4j2.formatMsgAsync`
+
+(`LOG4J_FORMAT_MSG_ASYNC`)
+| false
+| If `false`, Log4j will make sure the message is formatted in the caller thread, otherwise the formatting will occur on the asynchronous thread.
+
+**Remark**: messages annotated with link:../javadoc/log4j-api/org/apache/logging/log4j/message/AsynchronouslyFormattable[AsynchronouslyFormattable] will be formatted on the async thread regardless of this setting.
+
+| [[log4j2.asyncQueueFullPolicy]]`log4j2.asyncQueueFullPolicy`
+
+(`LOG4J_ASYNC_QUEUE_FULL_POLICY`)
+| `Default`
+a| Determines the link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy[AsyncQueueFullPolicy] to use when the underlying async component cannot keep up with the logging rate and the queue is filling up.
+
+It accepts the following values:
+
+* `Default`: blocks the calling thread until the event can be added to the queue.
+
+* `Discard`: when the queue is full, it drops the events whose level is equal or less than the threshold level (see <<log4j2.discardThreshold>>).
+
+* the fully qualified class name of a custom implementation
+
+| [[log4j2.discardThreshold]]`log4j2.discardThreshold`
+
+(`LOG4J_DISCARD_THRESHOLD`)
+| `INFO`
+| Determines the threshold level used by a `Discard` queue full policy.
+Log events whose level is equal or less specific than the threshold level will be discarded during a queue full event.
+See also <<log4j2.asyncQueueFullPolicy>>.
+
+|===
+
+==== `AsyncLogger`
+
+Additional properties supported by `AsyncLogger` are documented in the xref:manual/async.adoc#SysPropsAllAsync[System Properties to configure all asynchronous loggers] table.
+
+==== `AsyncLoggerConfig`
+
+Additional properties supported by `AsyncLoggerConfig` are documented in the xref:manual/async.adoc#SysPropsMixedSync-Async[System Properties to configure mixed asynchronous and normal loggers] table.
+
+=== Context selector
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ContextSelector[ContextSelector] component specifies the strategy used by Log4j to create new logger contexts.
+The choice of `ContextSelector` determines in particular:
+
+* how loggers are divided among logger contexts.
+See xref:manual/logsep.adoc[Log Separation] for details.
+
+* the `Logger` implementation used by Log4j Core.
+See xref:manual/async.adoc[Async Logging] as an example of this usage.
+
+.Context selector configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.contextSelector]]`log4j2.contextSelector`
+
+(`LOG4J_CONTEXT_SELECTOR`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[ClassLoaderContextSelector]
+a|
+Specifies the fully qualified class name of the `ContextSelector` implementation to use.
+
+The implementations available by default are:
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/BasicContextSelector[org.apache.logging.log4j
+.core.selector.BasicContextSelector]: creates a single logger context and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/BasicAsyncLoggerContextSelector[org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector]: creates a single logger context and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[org.apache.logging.log4j.core.selector.ClassLoaderContextSelector]: creates a separate logger context per classloader and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector[org.apache.logging.log4j.core.async.AsyncLoggerContextSelector]: creates a separate logger context per classloader and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/osgi/BundleContextSelector[org.apache.logging.log4j.core.osgi.BundleContextSelector]: creates a separate logger context per OSGi bundle and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/JndiContextSelector[org.apache.logging.log4j.core.selector.JndiContextSelector]: creates loggers contexts based on a JNDI lookup and synchronous loggers.
Review Comment:
```suggestion
link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/BasicContextSelector[BasicContextSelector]::
Creates a single logger context and synchronous loggers
link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/BasicAsyncLoggerContextSelector[BasicAsyncLoggerContextSelector]::
Creates a single logger context and xref:manual/async.adoc[asynchronous loggers]
link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[ClassLoaderContextSelector]::
Creates a separate logger context per classloader and synchronous loggers
link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector[AsyncLoggerContextSelector]::
Creates a separate logger context per classloader and xref:manual/async.adoc[asynchronous loggers]
link:../javadoc/log4j-core/org/apache/logging/log4j/core/osgi/BundleContextSelector[BundleContextSelector]::
Creates a separate logger context per OSGi bundle and synchronous loggers
link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/JndiContextSelector[JndiContextSelector]::
Creates loggers contexts based on a JNDI lookup and synchronous loggers
```
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
Review Comment:
I think, if not all, several `Default Value` column entries are missing backticks. Can you take care of those, please?
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
+| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates.
+
+| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()]
+| Sets the timezone id used by status logger. See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html[ZoneId] for the accepted formats.
+
+|===
+
+=== Simple logger
+
+The simple logger implementation contained in `log4j-api` can be configured using these properties:
+
+.Simple logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.simplelogLevel]]`log4j2.simplelogLevel`
+
+(`LOG4J_SIMPLELOG_LEVEL`)
+| ERROR
+| Default level for new logger instances.
+
+| [[log4j2.simplelog.loggerName.level]]`log4j2.simplelog.<loggerName>.level`
+
+(`LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL`)
+| value of <<log4j2.simplelogLevel>>
+| Log level for a logger instance named `<loggerName>`.
+
+| [[log4j2.simplelogShowContextMap]]`log4j2.simplelogShowContextMap`
+
+(`LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP`)
+| false
+| If `true`, the full thread context map is included in each log message.
+
+| [[log4j2.simplelogShowlogname]]`log4j2.simplelogShowlogname`
+
+(`LOG4J_SIMPLELOG_SHOWLOGNAME`)
+| false
+| If `true`, the logger name is included in each log message.
+
+| [[log4j2.simplelogShowShortLogname]]`log4j2.simplelogShowShortLogname`
+
+(`LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME`)
+| true
+| If `true`, only the last component of a logger name is included in each log message.
+
+| [[log4j2.simplelogShowdatetime]]`log4j2.simplelogShowdatetime`
+
+(`LOG4J_SIMPLELOG_SHOWDATETIME`)
+| false
+| If `true`, a timestamp is included in each log message.
+
+| [[log4j2.simplelogDateTimeFormat]]`log4j2.simplelogDateTimeFormat`
+
+(`LOG4J_SIMPLELOG_DATE_TIME_FORMAT`)
+| `yyyy/MM/dd HH:mm:ss:SSS zzz`
+| Date-time format to use. Ignored if <<log4j2.simplelogShowdatetime>> is `false`.
+
+| [[log4j2.simplelogLogFile]]`log4j2.simplelogLogFile`
+
+(`LOG4J_SIMPLELOG_LOG_FILE`)
+| System.err
+a| Specifies the output stream used by all loggers:
+
+* `System.err` logs to the standard error output stream,
+* `System.out` logs to the standard output stream,
+* any other value is interpreted as a file name.
+
+|===
+
+[#simple-logger-thread-context]
+=== Thread context (Simple Logger)
+
+The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
+
+[WARNING]
+====
+These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API.
+
+The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
+
+The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
+====
+
+.Thread context configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableThreadContext]]`log4j2.disableThreadContext`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT`)
+| false
+| If `true`, the `ThreadContext` stack and map are disabled.
+
+| [[log4j2.disableThreadContextStack]]`log4j2.disableThreadContextStack`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_STACK`)
+| false
+| If `true`, the `ThreadContext` stack is disabled.
+
+| [[log4j2.disableThreadContextMap]]`log4j2.disableThreadContextMap`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_MAP`)
+| false
+| If `true`, the `ThreadContext` map is disabled.
+
+| [[log4j2.threadContextMap]]`log4j2.threadContextMap`
+
+(`LOG4J_THREAD_CONTEXT_MAP`)
+| `WebApp`
+
+(GC-free mode: `CopyOnWrite`)
+a| Fully specified class name of a custom `ThreadContextMap` implementation class or one of the predefined constants:
+
+* `NoOp`: to disable the thread context,
+* `WebApp`: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks,
+* `CopyOnWrite`: a copy-on-write implementation,
+* `GarbageFree`: a garbage-free implementation.
+
+| [[isThreadContextMapInheritable]]`log4j2.isThreadContextMapInheritable`
+
+(`LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`)
+| false
+| If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
+
+| [[log4j2.garbagefreeThreadContextMap]]`log4j2.garbagefreeThreadContextMap`
+
+(`LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP`)
+| false
+| If set to `true` selects a garbage-free thread context map implementation.
+Requires <<log4j2.enableThreadlocals>> to be also `true`.
+
+|===
+
+== Log4j Core
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration_new.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
+
+=== Async components
Review Comment:
Why do we have some async properties here and some in `async.adoc`? (My preference would be to move all to `async.adoc`.)
##########
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.
+
+**Remark**: Since JRE 8u102 the `Thread.getName()` method does not allocate a new object.
Review Comment:
Please use [an AsciiDoc admonition](https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/).
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
+| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates.
+
+| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()]
+| Sets the timezone id used by status logger. See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html[ZoneId] for the accepted formats.
+
+|===
+
+=== Simple logger
+
+The simple logger implementation contained in `log4j-api` can be configured using these properties:
+
+.Simple logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.simplelogLevel]]`log4j2.simplelogLevel`
+
+(`LOG4J_SIMPLELOG_LEVEL`)
+| ERROR
+| Default level for new logger instances.
+
+| [[log4j2.simplelog.loggerName.level]]`log4j2.simplelog.<loggerName>.level`
+
+(`LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL`)
+| value of <<log4j2.simplelogLevel>>
+| Log level for a logger instance named `<loggerName>`.
+
+| [[log4j2.simplelogShowContextMap]]`log4j2.simplelogShowContextMap`
+
+(`LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP`)
+| false
+| If `true`, the full thread context map is included in each log message.
+
+| [[log4j2.simplelogShowlogname]]`log4j2.simplelogShowlogname`
+
+(`LOG4J_SIMPLELOG_SHOWLOGNAME`)
+| false
+| If `true`, the logger name is included in each log message.
+
+| [[log4j2.simplelogShowShortLogname]]`log4j2.simplelogShowShortLogname`
+
+(`LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME`)
+| true
+| If `true`, only the last component of a logger name is included in each log message.
+
+| [[log4j2.simplelogShowdatetime]]`log4j2.simplelogShowdatetime`
+
+(`LOG4J_SIMPLELOG_SHOWDATETIME`)
+| false
+| If `true`, a timestamp is included in each log message.
+
+| [[log4j2.simplelogDateTimeFormat]]`log4j2.simplelogDateTimeFormat`
+
+(`LOG4J_SIMPLELOG_DATE_TIME_FORMAT`)
+| `yyyy/MM/dd HH:mm:ss:SSS zzz`
+| Date-time format to use. Ignored if <<log4j2.simplelogShowdatetime>> is `false`.
+
+| [[log4j2.simplelogLogFile]]`log4j2.simplelogLogFile`
+
+(`LOG4J_SIMPLELOG_LOG_FILE`)
+| System.err
+a| Specifies the output stream used by all loggers:
+
+* `System.err` logs to the standard error output stream,
+* `System.out` logs to the standard output stream,
+* any other value is interpreted as a file name.
+
+|===
+
+[#simple-logger-thread-context]
+=== Thread context (Simple Logger)
+
+The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
+
+[WARNING]
+====
+These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API.
+
+The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
+
+The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
+====
+
+.Thread context configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableThreadContext]]`log4j2.disableThreadContext`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT`)
+| false
+| If `true`, the `ThreadContext` stack and map are disabled.
+
+| [[log4j2.disableThreadContextStack]]`log4j2.disableThreadContextStack`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_STACK`)
+| false
+| If `true`, the `ThreadContext` stack is disabled.
+
+| [[log4j2.disableThreadContextMap]]`log4j2.disableThreadContextMap`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_MAP`)
+| false
+| If `true`, the `ThreadContext` map is disabled.
+
+| [[log4j2.threadContextMap]]`log4j2.threadContextMap`
+
+(`LOG4J_THREAD_CONTEXT_MAP`)
+| `WebApp`
+
+(GC-free mode: `CopyOnWrite`)
+a| Fully specified class name of a custom `ThreadContextMap` implementation class or one of the predefined constants:
+
+* `NoOp`: to disable the thread context,
+* `WebApp`: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks,
+* `CopyOnWrite`: a copy-on-write implementation,
+* `GarbageFree`: a garbage-free implementation.
+
+| [[isThreadContextMapInheritable]]`log4j2.isThreadContextMapInheritable`
+
+(`LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`)
+| false
+| If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
+
+| [[log4j2.garbagefreeThreadContextMap]]`log4j2.garbagefreeThreadContextMap`
+
+(`LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP`)
+| false
+| If set to `true` selects a garbage-free thread context map implementation.
+Requires <<log4j2.enableThreadlocals>> to be also `true`.
+
+|===
+
+== Log4j Core
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration_new.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
+
+=== Async components
+
+The behavior of all three async components (`AsyncLogger`, `AsyncLoggerConfig` and `AsyncAppender`) can be tuned using these properties:
+
+.Common async component configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.formatMsgAsync]]`log4j2.formatMsgAsync`
+
+(`LOG4J_FORMAT_MSG_ASYNC`)
+| false
+| If `false`, Log4j will make sure the message is formatted in the caller thread, otherwise the formatting will occur on the asynchronous thread.
+
+**Remark**: messages annotated with link:../javadoc/log4j-api/org/apache/logging/log4j/message/AsynchronouslyFormattable[AsynchronouslyFormattable] will be formatted on the async thread regardless of this setting.
+
+| [[log4j2.asyncQueueFullPolicy]]`log4j2.asyncQueueFullPolicy`
+
+(`LOG4J_ASYNC_QUEUE_FULL_POLICY`)
+| `Default`
+a| Determines the link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy[AsyncQueueFullPolicy] to use when the underlying async component cannot keep up with the logging rate and the queue is filling up.
+
+It accepts the following values:
+
+* `Default`: blocks the calling thread until the event can be added to the queue.
+
+* `Discard`: when the queue is full, it drops the events whose level is equal or less than the threshold level (see <<log4j2.discardThreshold>>).
+
+* the fully qualified class name of a custom implementation
+
+| [[log4j2.discardThreshold]]`log4j2.discardThreshold`
+
+(`LOG4J_DISCARD_THRESHOLD`)
+| `INFO`
+| Determines the threshold level used by a `Discard` queue full policy.
+Log events whose level is equal or less specific than the threshold level will be discarded during a queue full event.
+See also <<log4j2.asyncQueueFullPolicy>>.
+
+|===
+
+==== `AsyncLogger`
+
+Additional properties supported by `AsyncLogger` are documented in the xref:manual/async.adoc#SysPropsAllAsync[System Properties to configure all asynchronous loggers] table.
+
+==== `AsyncLoggerConfig`
+
+Additional properties supported by `AsyncLoggerConfig` are documented in the xref:manual/async.adoc#SysPropsMixedSync-Async[System Properties to configure mixed asynchronous and normal loggers] table.
+
+=== Context selector
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ContextSelector[ContextSelector] component specifies the strategy used by Log4j to create new logger contexts.
+The choice of `ContextSelector` determines in particular:
+
+* how loggers are divided among logger contexts.
+See xref:manual/logsep.adoc[Log Separation] for details.
+
+* the `Logger` implementation used by Log4j Core.
+See xref:manual/async.adoc[Async Logging] as an example of this usage.
+
+.Context selector configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.contextSelector]]`log4j2.contextSelector`
+
+(`LOG4J_CONTEXT_SELECTOR`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[ClassLoaderContextSelector]
+a|
+Specifies the fully qualified class name of the `ContextSelector` implementation to use.
+
+The implementations available by default are:
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/BasicContextSelector[org.apache.logging.log4j
+.core.selector.BasicContextSelector]: creates a single logger context and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/BasicAsyncLoggerContextSelector[org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector]: creates a single logger context and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[org.apache.logging.log4j.core.selector.ClassLoaderContextSelector]: creates a separate logger context per classloader and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector[org.apache.logging.log4j.core.async.AsyncLoggerContextSelector]: creates a separate logger context per classloader and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/osgi/BundleContextSelector[org.apache.logging.log4j.core.osgi.BundleContextSelector]: creates a separate logger context per OSGi bundle and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/JndiContextSelector[org.apache.logging.log4j.core.selector.JndiContextSelector]: creates loggers contexts based on a JNDI lookup and synchronous loggers.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application]] for details.
+
+|===
+
+=== Configuration factory
+
+Since configuration factories are used to parse the configuration file, they can **only** be configured through global configuration properties.
+
+[WARNING]
+====
+Log4j Core supports both local and remote configuration files.
+If a remote configuration file is used, its transport must be secured.
+See <<transport-security>> for details.
+====
+
+.Configuration factory properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationFactory]]`log4j2.configurationFactory`
+
+(`LOG4J_CONFIGURATION_FACTORY`)
+|
+|
+Specifies the fully qualified class name of the **preferred** link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory[ConfigurationFactory] to use.
+
+Log4j will attempt to use the provided configuration factory before any other factory implementation.
+
+| [[log4j2.configurationFile]]`log4j2.configurationFile`
+
+(`LOG4J_CONFIGURATION_FILE`)
+| xref:manual/configuration.adoc#AutomaticConfiguration[automatically detected]
+a|
+Specifies a comma-separated list of URIs or file paths to Log4j 2 configuration files.
+
+If a relative URL is provided, it is interpreted as:
+
+* path to a file, if the file exists,
+* a classpath resource otherwise.
+
+See also xref:manual/configuration.adoc#AutomaticConfiguration[Automatic Configuration].
+
+| [[log4j2.level]]`log4j2.level`
+
+(`LOG4J_LEVEL`)
+| `ERROR`
+a|
+Specifies the level of the root logger if:
+
+* the default configuration is used,
+
+* or the configuration file does not specify a level for the root logger.
+
+| [[log4j2.mergeStrategy]]`log4j2.mergeStrategy`
+
+(`LOG4J_MERGE_STRATEGY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/DefaultMergeStrategy[DefaultMergeStrategy]
+|
+Specifies the fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/MergeStrategy[MergeStrategy] implementation used to merge multiple configuration files into one.
+
+|===
+
+=== Garbage Collection
+
+.GC properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+
+| [[log4j2.enableDirectEncoders]]`log4j2.enableDirectEncoders`
+
+(`LOG4J_ENABLE_DIRECT_ENCODERS`)
+| `true`
+|
+If `true`, garbage-aware layouts will directly encode log events into https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html[ByteBuffers] provided by appenders.
Review Comment:
```suggestion
If `true`, garbage-aware layouts will directly encode log events into https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html[ByteBuffer]s provided by appenders.
```
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
Review Comment:
I propose a different method to assemble this file:
1. Create `_log4j-api-properties.adoc`, `_log4j-core-properties.adoc`, `_log4j-core-pattern-layout-properties.adoc`, etc.
2. `include::` these files in `_properties.adoc` and `log4j-api.adoc`, etc.
This not only is a good diet for the file containing all properties, but enables including a particular properties list in multiple places.
**Tip:** You might want to use [partials](https://docs.antora.org/antora/latest/page/partials/).
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
+| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates.
+
+| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()]
+| Sets the timezone id used by status logger. See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html[ZoneId] for the accepted formats.
+
+|===
+
+=== Simple logger
+
+The simple logger implementation contained in `log4j-api` can be configured using these properties:
+
+.Simple logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.simplelogLevel]]`log4j2.simplelogLevel`
+
+(`LOG4J_SIMPLELOG_LEVEL`)
+| ERROR
+| Default level for new logger instances.
+
+| [[log4j2.simplelog.loggerName.level]]`log4j2.simplelog.<loggerName>.level`
+
+(`LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL`)
+| value of <<log4j2.simplelogLevel>>
+| Log level for a logger instance named `<loggerName>`.
+
+| [[log4j2.simplelogShowContextMap]]`log4j2.simplelogShowContextMap`
+
+(`LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP`)
+| false
+| If `true`, the full thread context map is included in each log message.
+
+| [[log4j2.simplelogShowlogname]]`log4j2.simplelogShowlogname`
+
+(`LOG4J_SIMPLELOG_SHOWLOGNAME`)
+| false
+| If `true`, the logger name is included in each log message.
+
+| [[log4j2.simplelogShowShortLogname]]`log4j2.simplelogShowShortLogname`
+
+(`LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME`)
+| true
+| If `true`, only the last component of a logger name is included in each log message.
+
+| [[log4j2.simplelogShowdatetime]]`log4j2.simplelogShowdatetime`
+
+(`LOG4J_SIMPLELOG_SHOWDATETIME`)
+| false
+| If `true`, a timestamp is included in each log message.
+
+| [[log4j2.simplelogDateTimeFormat]]`log4j2.simplelogDateTimeFormat`
+
+(`LOG4J_SIMPLELOG_DATE_TIME_FORMAT`)
+| `yyyy/MM/dd HH:mm:ss:SSS zzz`
+| Date-time format to use. Ignored if <<log4j2.simplelogShowdatetime>> is `false`.
+
+| [[log4j2.simplelogLogFile]]`log4j2.simplelogLogFile`
+
+(`LOG4J_SIMPLELOG_LOG_FILE`)
+| System.err
+a| Specifies the output stream used by all loggers:
+
+* `System.err` logs to the standard error output stream,
+* `System.out` logs to the standard output stream,
+* any other value is interpreted as a file name.
+
+|===
+
+[#simple-logger-thread-context]
+=== Thread context (Simple Logger)
+
+The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
+
+[WARNING]
+====
+These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API.
+
+The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
+
+The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
+====
+
+.Thread context configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableThreadContext]]`log4j2.disableThreadContext`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT`)
+| false
+| If `true`, the `ThreadContext` stack and map are disabled.
+
+| [[log4j2.disableThreadContextStack]]`log4j2.disableThreadContextStack`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_STACK`)
+| false
+| If `true`, the `ThreadContext` stack is disabled.
+
+| [[log4j2.disableThreadContextMap]]`log4j2.disableThreadContextMap`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_MAP`)
+| false
+| If `true`, the `ThreadContext` map is disabled.
+
+| [[log4j2.threadContextMap]]`log4j2.threadContextMap`
+
+(`LOG4J_THREAD_CONTEXT_MAP`)
+| `WebApp`
+
+(GC-free mode: `CopyOnWrite`)
+a| Fully specified class name of a custom `ThreadContextMap` implementation class or one of the predefined constants:
+
+* `NoOp`: to disable the thread context,
+* `WebApp`: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks,
+* `CopyOnWrite`: a copy-on-write implementation,
+* `GarbageFree`: a garbage-free implementation.
+
+| [[isThreadContextMapInheritable]]`log4j2.isThreadContextMapInheritable`
+
+(`LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`)
+| false
+| If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
+
+| [[log4j2.garbagefreeThreadContextMap]]`log4j2.garbagefreeThreadContextMap`
+
+(`LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP`)
+| false
+| If set to `true` selects a garbage-free thread context map implementation.
+Requires <<log4j2.enableThreadlocals>> to be also `true`.
+
+|===
+
+== Log4j Core
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration_new.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
Review Comment:
```suggestion
While the only required configuration of the `log4j-core` library is provided by the xref:manual/configurationw.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
```
##########
src/site/antora/modules/ROOT/pages/manual/configuration.adoc:
##########
Review Comment:
@ppkarwasz, I presume you are gonna submit another PR to improve `configuration.adoc` structurally, right?
Otherwise, this file is unacceptable in its current state. It is extremely bloated, impossible to navigate, and full of clutter (e.g., `Configuration` page starts with `Arbiters`, which hardly anybody uses).
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
+| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates.
+
+| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()]
+| Sets the timezone id used by status logger. See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html[ZoneId] for the accepted formats.
+
+|===
+
+=== Simple logger
+
+The simple logger implementation contained in `log4j-api` can be configured using these properties:
+
+.Simple logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.simplelogLevel]]`log4j2.simplelogLevel`
+
+(`LOG4J_SIMPLELOG_LEVEL`)
+| ERROR
+| Default level for new logger instances.
+
+| [[log4j2.simplelog.loggerName.level]]`log4j2.simplelog.<loggerName>.level`
+
+(`LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL`)
+| value of <<log4j2.simplelogLevel>>
+| Log level for a logger instance named `<loggerName>`.
+
+| [[log4j2.simplelogShowContextMap]]`log4j2.simplelogShowContextMap`
+
+(`LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP`)
+| false
+| If `true`, the full thread context map is included in each log message.
+
+| [[log4j2.simplelogShowlogname]]`log4j2.simplelogShowlogname`
+
+(`LOG4J_SIMPLELOG_SHOWLOGNAME`)
+| false
+| If `true`, the logger name is included in each log message.
+
+| [[log4j2.simplelogShowShortLogname]]`log4j2.simplelogShowShortLogname`
+
+(`LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME`)
+| true
+| If `true`, only the last component of a logger name is included in each log message.
+
+| [[log4j2.simplelogShowdatetime]]`log4j2.simplelogShowdatetime`
+
+(`LOG4J_SIMPLELOG_SHOWDATETIME`)
+| false
+| If `true`, a timestamp is included in each log message.
+
+| [[log4j2.simplelogDateTimeFormat]]`log4j2.simplelogDateTimeFormat`
+
+(`LOG4J_SIMPLELOG_DATE_TIME_FORMAT`)
+| `yyyy/MM/dd HH:mm:ss:SSS zzz`
+| Date-time format to use. Ignored if <<log4j2.simplelogShowdatetime>> is `false`.
+
+| [[log4j2.simplelogLogFile]]`log4j2.simplelogLogFile`
+
+(`LOG4J_SIMPLELOG_LOG_FILE`)
+| System.err
+a| Specifies the output stream used by all loggers:
+
+* `System.err` logs to the standard error output stream,
+* `System.out` logs to the standard output stream,
+* any other value is interpreted as a file name.
+
+|===
+
+[#simple-logger-thread-context]
+=== Thread context (Simple Logger)
+
+The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
+
+[WARNING]
+====
+These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API.
+
+The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
+
+The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
+====
+
+.Thread context configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableThreadContext]]`log4j2.disableThreadContext`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT`)
+| false
+| If `true`, the `ThreadContext` stack and map are disabled.
+
+| [[log4j2.disableThreadContextStack]]`log4j2.disableThreadContextStack`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_STACK`)
+| false
+| If `true`, the `ThreadContext` stack is disabled.
+
+| [[log4j2.disableThreadContextMap]]`log4j2.disableThreadContextMap`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_MAP`)
+| false
+| If `true`, the `ThreadContext` map is disabled.
+
+| [[log4j2.threadContextMap]]`log4j2.threadContextMap`
+
+(`LOG4J_THREAD_CONTEXT_MAP`)
+| `WebApp`
+
+(GC-free mode: `CopyOnWrite`)
+a| Fully specified class name of a custom `ThreadContextMap` implementation class or one of the predefined constants:
+
+* `NoOp`: to disable the thread context,
+* `WebApp`: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks,
+* `CopyOnWrite`: a copy-on-write implementation,
+* `GarbageFree`: a garbage-free implementation.
+
+| [[isThreadContextMapInheritable]]`log4j2.isThreadContextMapInheritable`
+
+(`LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`)
+| false
+| If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
+
+| [[log4j2.garbagefreeThreadContextMap]]`log4j2.garbagefreeThreadContextMap`
+
+(`LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP`)
+| false
+| If set to `true` selects a garbage-free thread context map implementation.
+Requires <<log4j2.enableThreadlocals>> to be also `true`.
+
+|===
+
+== Log4j Core
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration_new.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
+
+=== Async components
+
+The behavior of all three async components (`AsyncLogger`, `AsyncLoggerConfig` and `AsyncAppender`) can be tuned using these properties:
+
+.Common async component configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.formatMsgAsync]]`log4j2.formatMsgAsync`
+
+(`LOG4J_FORMAT_MSG_ASYNC`)
+| false
+| If `false`, Log4j will make sure the message is formatted in the caller thread, otherwise the formatting will occur on the asynchronous thread.
+
+**Remark**: messages annotated with link:../javadoc/log4j-api/org/apache/logging/log4j/message/AsynchronouslyFormattable[AsynchronouslyFormattable] will be formatted on the async thread regardless of this setting.
+
+| [[log4j2.asyncQueueFullPolicy]]`log4j2.asyncQueueFullPolicy`
+
+(`LOG4J_ASYNC_QUEUE_FULL_POLICY`)
+| `Default`
+a| Determines the link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy[AsyncQueueFullPolicy] to use when the underlying async component cannot keep up with the logging rate and the queue is filling up.
+
+It accepts the following values:
+
+* `Default`: blocks the calling thread until the event can be added to the queue.
+
+* `Discard`: when the queue is full, it drops the events whose level is equal or less than the threshold level (see <<log4j2.discardThreshold>>).
+
+* the fully qualified class name of a custom implementation
+
+| [[log4j2.discardThreshold]]`log4j2.discardThreshold`
+
+(`LOG4J_DISCARD_THRESHOLD`)
+| `INFO`
+| Determines the threshold level used by a `Discard` queue full policy.
+Log events whose level is equal or less specific than the threshold level will be discarded during a queue full event.
+See also <<log4j2.asyncQueueFullPolicy>>.
+
+|===
+
+==== `AsyncLogger`
+
+Additional properties supported by `AsyncLogger` are documented in the xref:manual/async.adoc#SysPropsAllAsync[System Properties to configure all asynchronous loggers] table.
+
+==== `AsyncLoggerConfig`
+
+Additional properties supported by `AsyncLoggerConfig` are documented in the xref:manual/async.adoc#SysPropsMixedSync-Async[System Properties to configure mixed asynchronous and normal loggers] table.
+
+=== Context selector
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ContextSelector[ContextSelector] component specifies the strategy used by Log4j to create new logger contexts.
+The choice of `ContextSelector` determines in particular:
+
+* how loggers are divided among logger contexts.
+See xref:manual/logsep.adoc[Log Separation] for details.
+
+* the `Logger` implementation used by Log4j Core.
+See xref:manual/async.adoc[Async Logging] as an example of this usage.
+
+.Context selector configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.contextSelector]]`log4j2.contextSelector`
+
+(`LOG4J_CONTEXT_SELECTOR`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[ClassLoaderContextSelector]
+a|
+Specifies the fully qualified class name of the `ContextSelector` implementation to use.
+
+The implementations available by default are:
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/BasicContextSelector[org.apache.logging.log4j
+.core.selector.BasicContextSelector]: creates a single logger context and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/BasicAsyncLoggerContextSelector[org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector]: creates a single logger context and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[org.apache.logging.log4j.core.selector.ClassLoaderContextSelector]: creates a separate logger context per classloader and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector[org.apache.logging.log4j.core.async.AsyncLoggerContextSelector]: creates a separate logger context per classloader and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/osgi/BundleContextSelector[org.apache.logging.log4j.core.osgi.BundleContextSelector]: creates a separate logger context per OSGi bundle and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/JndiContextSelector[org.apache.logging.log4j.core.selector.JndiContextSelector]: creates loggers contexts based on a JNDI lookup and synchronous loggers.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application]] for details.
+
+|===
+
+=== Configuration factory
+
+Since configuration factories are used to parse the configuration file, they can **only** be configured through global configuration properties.
+
+[WARNING]
+====
+Log4j Core supports both local and remote configuration files.
+If a remote configuration file is used, its transport must be secured.
+See <<transport-security>> for details.
+====
+
+.Configuration factory properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationFactory]]`log4j2.configurationFactory`
+
+(`LOG4J_CONFIGURATION_FACTORY`)
+|
+|
+Specifies the fully qualified class name of the **preferred** link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory[ConfigurationFactory] to use.
+
+Log4j will attempt to use the provided configuration factory before any other factory implementation.
+
+| [[log4j2.configurationFile]]`log4j2.configurationFile`
+
+(`LOG4J_CONFIGURATION_FILE`)
+| xref:manual/configuration.adoc#AutomaticConfiguration[automatically detected]
+a|
+Specifies a comma-separated list of URIs or file paths to Log4j 2 configuration files.
+
+If a relative URL is provided, it is interpreted as:
+
+* path to a file, if the file exists,
+* a classpath resource otherwise.
+
+See also xref:manual/configuration.adoc#AutomaticConfiguration[Automatic Configuration].
+
+| [[log4j2.level]]`log4j2.level`
+
+(`LOG4J_LEVEL`)
+| `ERROR`
+a|
+Specifies the level of the root logger if:
+
+* the default configuration is used,
+
+* or the configuration file does not specify a level for the root logger.
+
+| [[log4j2.mergeStrategy]]`log4j2.mergeStrategy`
+
+(`LOG4J_MERGE_STRATEGY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/DefaultMergeStrategy[DefaultMergeStrategy]
+|
+Specifies the fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/MergeStrategy[MergeStrategy] implementation used to merge multiple configuration files into one.
+
+|===
+
+=== Garbage Collection
+
+.GC properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+
+| [[log4j2.enableDirectEncoders]]`log4j2.enableDirectEncoders`
+
+(`LOG4J_ENABLE_DIRECT_ENCODERS`)
+| `true`
+|
+If `true`, garbage-aware layouts will directly encode log events into https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html[ByteBuffers] provided by appenders.
+
+This prevents the creation temporary multiple `String` and `char[]` temporary objects.
Review Comment:
```suggestion
This prevents allocating temporary `String` and `char[]` instances.
```
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
+| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates.
+
+| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()]
+| Sets the timezone id used by status logger. See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html[ZoneId] for the accepted formats.
+
+|===
+
+=== Simple logger
+
+The simple logger implementation contained in `log4j-api` can be configured using these properties:
+
+.Simple logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.simplelogLevel]]`log4j2.simplelogLevel`
+
+(`LOG4J_SIMPLELOG_LEVEL`)
+| ERROR
+| Default level for new logger instances.
+
+| [[log4j2.simplelog.loggerName.level]]`log4j2.simplelog.<loggerName>.level`
+
+(`LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL`)
+| value of <<log4j2.simplelogLevel>>
+| Log level for a logger instance named `<loggerName>`.
+
+| [[log4j2.simplelogShowContextMap]]`log4j2.simplelogShowContextMap`
+
+(`LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP`)
+| false
+| If `true`, the full thread context map is included in each log message.
+
+| [[log4j2.simplelogShowlogname]]`log4j2.simplelogShowlogname`
+
+(`LOG4J_SIMPLELOG_SHOWLOGNAME`)
+| false
+| If `true`, the logger name is included in each log message.
+
+| [[log4j2.simplelogShowShortLogname]]`log4j2.simplelogShowShortLogname`
+
+(`LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME`)
+| true
+| If `true`, only the last component of a logger name is included in each log message.
+
+| [[log4j2.simplelogShowdatetime]]`log4j2.simplelogShowdatetime`
+
+(`LOG4J_SIMPLELOG_SHOWDATETIME`)
+| false
+| If `true`, a timestamp is included in each log message.
+
+| [[log4j2.simplelogDateTimeFormat]]`log4j2.simplelogDateTimeFormat`
+
+(`LOG4J_SIMPLELOG_DATE_TIME_FORMAT`)
+| `yyyy/MM/dd HH:mm:ss:SSS zzz`
+| Date-time format to use. Ignored if <<log4j2.simplelogShowdatetime>> is `false`.
+
+| [[log4j2.simplelogLogFile]]`log4j2.simplelogLogFile`
+
+(`LOG4J_SIMPLELOG_LOG_FILE`)
+| System.err
+a| Specifies the output stream used by all loggers:
+
+* `System.err` logs to the standard error output stream,
+* `System.out` logs to the standard output stream,
+* any other value is interpreted as a file name.
+
+|===
+
+[#simple-logger-thread-context]
+=== Thread context (Simple Logger)
+
+The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
+
+[WARNING]
+====
+These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API.
+
+The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
+
+The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
+====
+
+.Thread context configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableThreadContext]]`log4j2.disableThreadContext`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT`)
+| false
+| If `true`, the `ThreadContext` stack and map are disabled.
+
+| [[log4j2.disableThreadContextStack]]`log4j2.disableThreadContextStack`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_STACK`)
+| false
+| If `true`, the `ThreadContext` stack is disabled.
+
+| [[log4j2.disableThreadContextMap]]`log4j2.disableThreadContextMap`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_MAP`)
+| false
+| If `true`, the `ThreadContext` map is disabled.
+
+| [[log4j2.threadContextMap]]`log4j2.threadContextMap`
+
+(`LOG4J_THREAD_CONTEXT_MAP`)
+| `WebApp`
+
+(GC-free mode: `CopyOnWrite`)
+a| Fully specified class name of a custom `ThreadContextMap` implementation class or one of the predefined constants:
+
+* `NoOp`: to disable the thread context,
+* `WebApp`: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks,
+* `CopyOnWrite`: a copy-on-write implementation,
+* `GarbageFree`: a garbage-free implementation.
+
+| [[isThreadContextMapInheritable]]`log4j2.isThreadContextMapInheritable`
+
+(`LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`)
+| false
+| If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
+
+| [[log4j2.garbagefreeThreadContextMap]]`log4j2.garbagefreeThreadContextMap`
+
+(`LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP`)
+| false
+| If set to `true` selects a garbage-free thread context map implementation.
+Requires <<log4j2.enableThreadlocals>> to be also `true`.
+
+|===
+
+== Log4j Core
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration_new.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
+
+=== Async components
+
+The behavior of all three async components (`AsyncLogger`, `AsyncLoggerConfig` and `AsyncAppender`) can be tuned using these properties:
+
+.Common async component configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.formatMsgAsync]]`log4j2.formatMsgAsync`
+
+(`LOG4J_FORMAT_MSG_ASYNC`)
+| false
+| If `false`, Log4j will make sure the message is formatted in the caller thread, otherwise the formatting will occur on the asynchronous thread.
+
+**Remark**: messages annotated with link:../javadoc/log4j-api/org/apache/logging/log4j/message/AsynchronouslyFormattable[AsynchronouslyFormattable] will be formatted on the async thread regardless of this setting.
+
+| [[log4j2.asyncQueueFullPolicy]]`log4j2.asyncQueueFullPolicy`
+
+(`LOG4J_ASYNC_QUEUE_FULL_POLICY`)
+| `Default`
+a| Determines the link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy[AsyncQueueFullPolicy] to use when the underlying async component cannot keep up with the logging rate and the queue is filling up.
+
+It accepts the following values:
+
+* `Default`: blocks the calling thread until the event can be added to the queue.
+
+* `Discard`: when the queue is full, it drops the events whose level is equal or less than the threshold level (see <<log4j2.discardThreshold>>).
+
+* the fully qualified class name of a custom implementation
+
+| [[log4j2.discardThreshold]]`log4j2.discardThreshold`
+
+(`LOG4J_DISCARD_THRESHOLD`)
+| `INFO`
+| Determines the threshold level used by a `Discard` queue full policy.
+Log events whose level is equal or less specific than the threshold level will be discarded during a queue full event.
+See also <<log4j2.asyncQueueFullPolicy>>.
+
+|===
+
+==== `AsyncLogger`
+
+Additional properties supported by `AsyncLogger` are documented in the xref:manual/async.adoc#SysPropsAllAsync[System Properties to configure all asynchronous loggers] table.
+
+==== `AsyncLoggerConfig`
+
+Additional properties supported by `AsyncLoggerConfig` are documented in the xref:manual/async.adoc#SysPropsMixedSync-Async[System Properties to configure mixed asynchronous and normal loggers] table.
+
+=== Context selector
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ContextSelector[ContextSelector] component specifies the strategy used by Log4j to create new logger contexts.
+The choice of `ContextSelector` determines in particular:
+
+* how loggers are divided among logger contexts.
+See xref:manual/logsep.adoc[Log Separation] for details.
+
+* the `Logger` implementation used by Log4j Core.
+See xref:manual/async.adoc[Async Logging] as an example of this usage.
+
+.Context selector configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.contextSelector]]`log4j2.contextSelector`
+
+(`LOG4J_CONTEXT_SELECTOR`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[ClassLoaderContextSelector]
+a|
+Specifies the fully qualified class name of the `ContextSelector` implementation to use.
+
+The implementations available by default are:
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/BasicContextSelector[org.apache.logging.log4j
+.core.selector.BasicContextSelector]: creates a single logger context and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/BasicAsyncLoggerContextSelector[org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector]: creates a single logger context and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[org.apache.logging.log4j.core.selector.ClassLoaderContextSelector]: creates a separate logger context per classloader and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector[org.apache.logging.log4j.core.async.AsyncLoggerContextSelector]: creates a separate logger context per classloader and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/osgi/BundleContextSelector[org.apache.logging.log4j.core.osgi.BundleContextSelector]: creates a separate logger context per OSGi bundle and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/JndiContextSelector[org.apache.logging.log4j.core.selector.JndiContextSelector]: creates loggers contexts based on a JNDI lookup and synchronous loggers.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application]] for details.
+
+|===
+
+=== Configuration factory
+
+Since configuration factories are used to parse the configuration file, they can **only** be configured through global configuration properties.
+
+[WARNING]
+====
+Log4j Core supports both local and remote configuration files.
+If a remote configuration file is used, its transport must be secured.
+See <<transport-security>> for details.
+====
+
+.Configuration factory properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationFactory]]`log4j2.configurationFactory`
+
+(`LOG4J_CONFIGURATION_FACTORY`)
+|
+|
+Specifies the fully qualified class name of the **preferred** link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory[ConfigurationFactory] to use.
+
+Log4j will attempt to use the provided configuration factory before any other factory implementation.
+
+| [[log4j2.configurationFile]]`log4j2.configurationFile`
+
+(`LOG4J_CONFIGURATION_FILE`)
+| xref:manual/configuration.adoc#AutomaticConfiguration[automatically detected]
+a|
+Specifies a comma-separated list of URIs or file paths to Log4j 2 configuration files.
+
+If a relative URL is provided, it is interpreted as:
+
+* path to a file, if the file exists,
+* a classpath resource otherwise.
+
+See also xref:manual/configuration.adoc#AutomaticConfiguration[Automatic Configuration].
+
+| [[log4j2.level]]`log4j2.level`
+
+(`LOG4J_LEVEL`)
+| `ERROR`
+a|
+Specifies the level of the root logger if:
+
+* the default configuration is used,
+
+* or the configuration file does not specify a level for the root logger.
+
+| [[log4j2.mergeStrategy]]`log4j2.mergeStrategy`
+
+(`LOG4J_MERGE_STRATEGY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/DefaultMergeStrategy[DefaultMergeStrategy]
+|
+Specifies the fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/MergeStrategy[MergeStrategy] implementation used to merge multiple configuration files into one.
+
+|===
+
+=== Garbage Collection
+
+.GC properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+
+| [[log4j2.enableDirectEncoders]]`log4j2.enableDirectEncoders`
+
+(`LOG4J_ENABLE_DIRECT_ENCODERS`)
+| `true`
+|
+If `true`, garbage-aware layouts will directly encode log events into https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html[ByteBuffers] provided by appenders.
+
+This prevents the creation temporary multiple `String` and `char[]` temporary objects.
+
+| [[log4j2.initialReusableMsgSize]]`log4j2.initialReusableMsgSize`
+
+(`LOG4J_INITIAL_REUSABLE_MSG_SIZE`)
+| 128
+| In GC-free mode, this property determines the initial size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+| [[log4j2.maxReusableMsgSize]]`log4j2.maxReusableMsgSize`
+
+(`LOG4J_MAX_REUSABLE_MSG_SIZE`)
+| 518
+| In GC-free mode, this property determines the maximum size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+The default value allows is equal to `2 × (2 × log4j.initialReusableMsgSize + 2) + 2` and allows the
+``StringBuilder`` to be resized twice by the current JVM resize algorithm.
+
+| [[log4j2.layoutStringBuilderMaxSize]]`log4j2.layout{zwsp}StringBuilderMaxSize`
+
+(`LOG4J_LAYOUT_{zwsp}STRING_BUILDER_MAX_SIZE`)
+| 2048
+| This property determines the maximum size of the reusable ``StringBuilder``sused to format link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent[LogEvents].
+
+| [[log4j2.unboxRingbufferSize]]`log4j2.unboxRingbufferSize`
+
+(`LOG4J_UNBOX_RINGBUFFER_SIZE`)
+| 32
+|
+The link:../javadoc/log4j-api/org/apache/logging/log4j/util/Unbox[Unbox] utility class can be used by users to format primitive values without incurring in the boxing allocation cost.
+
+This property specifies the maximum number of primitive arguments to a log message that will be cached and usually does not need to be changed.
+
+|===
+
+=== JANSI
+
+If the https://fusesource.github.io/jansi/[JANSI] library is on the runtime classpath of the application, the following property can be used to control its usage:
+
+.JANSI properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.skipJansi]]`log4j2.skipJansi`
+
+(`LOG4J_SKIP_JANSI`)
+| `true`
+a| If the following conditions are satisfied:
+
+* Log4j runs on Windows,
+* this property is set to `false`,
+
+Log4j will use the JANSI library to color the output of the console appender.
+
+|===
+
+=== JNDI
+
+Due to the inherent security problems of https://docs.oracle.com/javase/tutorial/jndi/overview/[JNDI], its usage in Log4j is restricted to the `java:` protocol.
+
+Moreover, each JNDI usage must be **explicitly** enabled by the user through the following configuration properties.
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.enableJndiContextSelector]]`log4j2.enableJndiContextSelector`
+
+(`LOG4J_ENABLE_JNDI_CONTEXT_SELECTOR`)
+| `false`
+|
+When `true` the `JndiContextSelector` is enabled for the `java:` protocol.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application] for more details.
+
+| [[log4j2.enableJndiJdbc]]`log4j2.enableJndiJdbc`
+
+(`LOG4J_ENABLE_JNDI_JDBC`)
+| `false`
+| When `true`, a Log4j JDBC Appender can use JNDI to retrieve a https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[DataSource] using the `java:` protocol.
+
+| [[log4j2.enableJndiJms]]`log4j2.enableJndiJms`
+
+(`LOG4J_ENABLE_JNDI_JMS`)
+| `false`
+| When `true`, a Log4j JMS Appender can use JNDI to retrieve the necessary components using the `java:` protocol.
+
+| [[log4j2.enableJndiLookup]]`log4j2.enableJndiLookup`
+
+(`LOG4J_ENABLE_JNDI_LOOKUP`)
+| `false`
+| When `true`, the Log4j JNDI Lookup can use the `java:` protocol.
+
+|===
+
+=== JMX
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableJmx]]`log4j2.disableJmx`
+
+(`LOG4J_DISABLE_JMX`)
+| `true`
+|
+If `false`, Log4j configuration objects like ``LoggerContext``s, ``Appender``s, ``Logger``s, etc.
+will be instrumented with ``MBean``s and can be remotely monitored and managed.
+
+| [[log4j2.jmxNotifyAsync]]`log4j2.jmxNotifyAsync`
+
+(`LOG4J_JMX_NOTIFY_ASYNC`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true`, Log4j's JMX notifications are sent from a separate background thread, otherwise they are sent from the caller thread.
+
+|===
+
+[#log4j-core-thread-context]
+=== Thread context (Log4j Core)
+
+Log4j Core supports the same properties as Simple Logger for the configuration of the thread context.
+See <<simple-logger-thread-context>> for more details.
+
+[#transport-security]
+=== Transport security
+
+Since configuration files can be used to load arbitrary classes into a Log4j Core `Configuration`, users need to ensure that all the configuration elements come from trusted sources (cf. link:/security#threat-common-config-sources[Thread model] for more information).
+
+In order to protect the user Log4j disables the `http` URI scheme by default and provides several configuration options to ensure secure transport of configuration files:
+
+:jsse-default-keystores: https://docs.oracle.com/en/java/javase/21/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-7D9F43B8-AABF-4C5B-93E6-3AFB18B66150
+
+.Transport security properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationAllowedProtocols]]`log4j2.configuration{zwsp}AllowedProtocols`
+
+(`LOG4J_CONFIGURATION_{zwsp}ALLOWED_PROTOCOLS`)
+| file, https, jar
+|
+A comma separated list of URL protocols that may be used to load any kind of configuration source.
+
+To completely prevent accessing the configuration via the Java https://docs.oracle.com/javase/8/docs/api/java/net/URL.html[URL class] specify a value of `_none`.
+
+// TODO: What about 'jar:http:'?
+
+| [[log4j2.configurationAuthorizationProvider]]`log4j2.configuration{zwsp}AuthorizationProvider`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_PROVIDER`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/BasicAuthorizationProvider[BasicAuthorizationProvider]
+| The fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/AuthorizationProvider[AuthorizationProvider] implementation to use with `http` and `https` URL protocols.
+
+3+h| HTTP Basic authentication
+
+| [[log4j2.configurationAuthorizationEncoding]]`log4j2.configuration{zwsp}AuthorizationEncoding`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_ENCODING`)
+| UTF-8
+| The encoding used in Basic Authentication (cf. https://datatracker.ietf.org/doc/html/rfc7617[RFC 7617]).
+
+| [[log4j2.configurationPassword]]`log4j2.configurationPassword`
+
+(`LOG4J_CONFIGURATION_PASSWORD`)
+|
+| The password to use in HTTP Basic authentication.
+
+If used in conjunction with <<log4j2.configurationPasswordDecryptor>> the contents of this variable are
+interpreted by the decryptor.
+
+| [[log4j2.configurationPasswordDecryptor]]`log4j2.configuration{zwsp}PasswordDecryptor`
+
+(`LOG4J_CONFIGURATION_{zwsp}PASSWORD_DECRYPTOR`)
+|
+| Fully qualified class name of an implementation of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/PasswordDecryptor[PasswordDecryptor] to use for the value of the <<log4j2.configurationPassword>> property.
+
+By default, the literal value of the password is used.
+
+| [[log4j2.configurationUsername]]`log4j2.configurationUsername`
+
+(`LOG4J_CONFIGURATION_USERNAME`)
+|
+| The username used in HTTP Basic authentication.
+
+3+h| TLS server authentication properties
+
+| [[log4j2.trustStoreLocation]]`log4j2.trustStoreLocation`
+
+(`LOG4J_TRUST_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java trust store]
+| The location of the trust store.
+
+| [[log4j2.trustStorePassword]]`log4j2.trustStorePassword`
+
+(`LOG4J_TRUST_STORE_PASSWORD`)
+|
+| The password for the trust store.
+
+| [[log4j2.trustStorePasswordFile]]`log4j2.trustStore{zwsp}PasswordFile`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the trust store.
+
+| [[log4j2.trustStorePasswordEnvironmentVariable]]`log4j2.trustStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains password for the trust store.
+
+| [[log4j2.trustStoreType]]`log4j2.trustStoreType`
+
+(`LOG4J_TRUST_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.trustStoreKeyManagerFactoryAlgorithm]]`log4j2.trustStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_TRUST_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+| [[log4j2.sslVerifyHostName]]`log4j2.sslVerifyHostName`
+
+(`LOG4J_SSL_VERIFY_HOST_NAME`)
+| false
+| If `true` enables verification of the name of the TLS server.
+
+3+h| TLS client authentication properties
+
+| [[log4j2.keyStoreLocation]]`log4j2.keyStoreLocation`
+
+(`LOG4J_KEY_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java key store]
+| The location of the private key store.
+
+| [[log4j2.keyStorePassword]]`log4j2.keyStorePassword`
+
+(`LOG4J_KEY_STORE_PASSWORD`)
+|
+| The password for the private key store.
+
+| [[log4j2.keyStorePasswordFile]]`log4j2.keyStore{zwsp}PasswordFile`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the private key store.
+
+| [[log4j2.keyStorePasswordEnvironmentVariable]]`log4j2.keyStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains the password for the private key store.
+
+| [[log4j2.keyStoreType]]`log4j2.keyStoreType`
+
+(`LOG4J_KEY_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.keyStoreKeyManagerFactoryAlgorithm]]`log4j2.keyStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_KEY_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+|===
+
+=== Miscellaneous properties
+
+.Miscellaneous configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.clock]]`log4j2.clock`
+
+(`LOG4J_CLOCK`)
+| `SystemClock`
+a|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/Clock[Clock] implementation used to timestamp log events.
+
+The possible values are:
+
+* `SystemClock`: uses the best available system clock as time source.
+See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/Clock.html#systemDefaultZone--[Clock#systemDefaultZone] for details.
+
+* `SystemMillisClock`: same as `SystemClock`, but truncates the result to a millisecond.
+
+* `CachedClock`: uses a separate thread to update the timestamp value.
+See link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/CachedClock[JavaDoc] for details.
+
+* `CoarseCachedClock`: alternative implementation of `CachedClock` with a slightly lower precision.
+See link:..//javadoc/log4j-core/org/apache/logging/log4j/core/util/CoarseCachedClock[JavaDoc] for details.
+
+* the fully qualified name of a custom implementation.
+
+| [[log4j2.contextDataInjector]]`log4j2.contextDataInjector`
+
+(`LOG4J_CONTEXT_DATA_INJECTOR`)
+| depends on the `ThreadContextMap` implementation
+| Fully specified class name of a link:../javadoc/log4j-core/org/apache/logging/log4j/core/ContextDataInjector[ContextDataInjector] implementation.
+
+The default implementation uses all implementations of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ContextDataProvider[ContextDataProvider] registered with `ServiceLoader`.
+
+| [[log4j2.logEventFactory]]`log4j2.logEventFactory`
+
+(`LOG4J_LOG_EVENT_FACTORY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/DefaultLogEventFactory[DefaultLogEventFactory]
+
+(GC-free mode: link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/ReusableLogEventFactory[ReusableLogEventFactory])
+|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/LogEventFactory[LogEventFactory]
+implementation to use to create log events.
+
+| [[log4j2.shutdownHookEnabled]]`log4j2.shutdownHookEnabled`
+
+(`LOG4J_SHUTDOWN_HOOK_ENABLED`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true` a shutdown hook will be installed to stop all logger contexts when the system stops.
+
+| [[log4j2.shutdownCallbackRegistry]]`log4j2.shutdownCallbackRegistry`
+
+(`LOG4J_SHUTDOWN_CALLBACK_REGISTRY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/DefaultShutdownCallbackRegistry[DefaultShutdownCallbackRegistry]
+|
+The fully qualified class name of a link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry[ShutdownCallbackRegistry] implementation.
+Integrators can use this to customize the shutdown order of the JVM.
+
+The default implementation executes all shutdown actions in a separate `Thread` registered through https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#addShutdownHook-java.lang.Thread-[Runtime#addShutdownHook()].
+
+
+| [[log4j2.uuidSequence]]`log4j2.uuidSequence`
+
+(`LOG4J_UUID_SEQUENCE`)
+| 0
+|
+Provides a `long` see to the UUID generator used by the `%uuid` pattern converter.
+
+Can be used to assure uniqueness of UUIDs generated by multiple JVMs on the same machine.
+
+| [[log4j2.messageFactory]]`log4j2.messageFactory`
+
+(`LOG4J_MESSAGE_FACTORY`)
+| link:../javadoc/log4j-api/org/apache/logging/log4j/message/ParameterizedMessageFactory[ParameterizeMessageFactory]
+
+(GC-free mode: link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessageFactory[ReusableMessageFactory])
+| Default message factory used by loggers if no factory was specified.
+
+| [[log4j2.flowMessageFactory]]`log4j2.flowMessageFactory`
+
+(`LOG4J_FLOW_MESSAGE_FACTORY`)
+| link:../javadoc/log4j-api/org/apache/logging/log4j/message/DefaultFlowMessageFactory[DefaultFlowMessageFactory]
+| Default flow message factory used by Loggers.
+
+| [[log4j2.loggerContextStacktraceOnStart]]`log4j2.loggerContext{zwsp}StacktraceOnStart`
+
+(`LOG4J_LOGGER_CONTEXT_{zwsp}STACKTRACE_ON_START`)
+| `false`
+| Prints a stacktrace to the xref:manual/configuration.adoc#StatusMessages[status logger] at `DEBUG` level when the LoggerContext is started.
+
+For debug purposes only.
+
+| [[log4j2.scriptEnableLanguages]]`log4j2.scriptEnableLanguages`
+
+(`LOG4J_SCRIPT_ENABLE_LANGUAGES`)
+|
+| The list of script languages that are allowed to execute.
+
+The names specified must correspond to those returned by https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/script/ScriptEngineFactory.html#getNames--[ScriptEngineFactory#getNames()].
+
+|===
+
+== JUL-to-Log4j API bridge
+
+The JUL-to-Log4j API bridge provides the following configuration properties:
+
+.JUL configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.julLevelConverter]]`log4j2.julLevelConverter`
+
+(`LOG4J_JUL_LEVEL_CONVERTER`)
+|
+|
+Fully qualified name of an alternative `org.apache.logging.log4j.jul.LevelConverter` implementation.
+
+See xref:log4j-jul.adoc#default-level-conversions[Default Level Conversions] for the default implementation.
+
+| [[log4j2.julLoggerAdapter]]`log4j2.julLoggerAdapter`
+
+(`LOG4J_JUL_LOGGER_ADAPTER`)
+| depends on classpath
+a|
+This property allows users to choose between two implementation of the logging bridge:
+
+* `org.apache.logging.log4j.jul.CoreLoggerAdapter` (default if `log4j-core` present) allows users to modify the Log4j Core configuration through the JUL https://docs.oracle.com/javase/8/docs/api/java/util/logging/Logger.html[Logger] interface,
+
+* `org.apache.logging.log4j.jul.ApiLoggerAdapter` (default if `log4j-core` absent) disables the level mutators in the JUL `Logger` interface.
+
+|===
+
+== Log4j Spring Boot
+
+The Log4j Spring Boot module supports the following configuration properties:
+
+.Spring Boot configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableCloudConfigLoggingSystem]]`log4j2.disable{zwsp}CloudConfigLoggingSystem`
+
+(`LOG4J_DISABLE_{zwsp}CLOUD_CONFIG_LOGGING_SYSTEM`)
+| `false`
+| Disables the usage of the Spring Boot `Log4j2CloudConfigLoggingSystem`.
+
+|===
+
+[#property-sources]
+== Property sources
+
+The Log4j configuration properties sub-system merges the content of multiple property sources that implement the Java interface link:../javadoc/log4j-api/org/apache/logging/log4j/util/PropertySource[PropertySource].
+
+Additional property source classes can be added through:
+
+* the standard Java SE https://docs.oracle.com/en/java/javase/{java-target-version}/docs/api/java.base/java/util/ServiceLoader.html[ServiceLoader] mechanism,
+* programmatically using `PropertiesUtil#addPropertySource` and `PropertiesUtil#removePropertySource`.
Review Comment:
```suggestion
* programmatically using `addPropertySource()` and `removePropertySource()` static methods of `PropertiesUtil`.
```
##########
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:
Please use a description list. Also formatting is broken, you need `a|` instead of `|` at the column start.
##########
src/site/antora/modules/ROOT/pages/manual/layouts.adoc:
##########
Review Comment:
Thanks for the groundwork, but there is already #2527. :sweat_smile:
##########
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:
Can you stop creating your own description lists and use [AsciiDoc description lists](https://docs.asciidoctor.org/asciidoc/latest/lists/description/), please?
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
+| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates.
+
+| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()]
+| Sets the timezone id used by status logger. See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html[ZoneId] for the accepted formats.
+
+|===
+
+=== Simple logger
+
+The simple logger implementation contained in `log4j-api` can be configured using these properties:
+
+.Simple logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.simplelogLevel]]`log4j2.simplelogLevel`
+
+(`LOG4J_SIMPLELOG_LEVEL`)
+| ERROR
+| Default level for new logger instances.
+
+| [[log4j2.simplelog.loggerName.level]]`log4j2.simplelog.<loggerName>.level`
+
+(`LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL`)
+| value of <<log4j2.simplelogLevel>>
+| Log level for a logger instance named `<loggerName>`.
+
+| [[log4j2.simplelogShowContextMap]]`log4j2.simplelogShowContextMap`
+
+(`LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP`)
+| false
+| If `true`, the full thread context map is included in each log message.
+
+| [[log4j2.simplelogShowlogname]]`log4j2.simplelogShowlogname`
+
+(`LOG4J_SIMPLELOG_SHOWLOGNAME`)
+| false
+| If `true`, the logger name is included in each log message.
+
+| [[log4j2.simplelogShowShortLogname]]`log4j2.simplelogShowShortLogname`
+
+(`LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME`)
+| true
+| If `true`, only the last component of a logger name is included in each log message.
+
+| [[log4j2.simplelogShowdatetime]]`log4j2.simplelogShowdatetime`
+
+(`LOG4J_SIMPLELOG_SHOWDATETIME`)
+| false
+| If `true`, a timestamp is included in each log message.
+
+| [[log4j2.simplelogDateTimeFormat]]`log4j2.simplelogDateTimeFormat`
+
+(`LOG4J_SIMPLELOG_DATE_TIME_FORMAT`)
+| `yyyy/MM/dd HH:mm:ss:SSS zzz`
+| Date-time format to use. Ignored if <<log4j2.simplelogShowdatetime>> is `false`.
+
+| [[log4j2.simplelogLogFile]]`log4j2.simplelogLogFile`
+
+(`LOG4J_SIMPLELOG_LOG_FILE`)
+| System.err
+a| Specifies the output stream used by all loggers:
+
+* `System.err` logs to the standard error output stream,
+* `System.out` logs to the standard output stream,
+* any other value is interpreted as a file name.
+
+|===
+
+[#simple-logger-thread-context]
+=== Thread context (Simple Logger)
+
+The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
+
+[WARNING]
+====
+These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API.
+
+The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
+
+The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
+====
+
+.Thread context configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableThreadContext]]`log4j2.disableThreadContext`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT`)
+| false
+| If `true`, the `ThreadContext` stack and map are disabled.
+
+| [[log4j2.disableThreadContextStack]]`log4j2.disableThreadContextStack`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_STACK`)
+| false
+| If `true`, the `ThreadContext` stack is disabled.
+
+| [[log4j2.disableThreadContextMap]]`log4j2.disableThreadContextMap`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_MAP`)
+| false
+| If `true`, the `ThreadContext` map is disabled.
+
+| [[log4j2.threadContextMap]]`log4j2.threadContextMap`
+
+(`LOG4J_THREAD_CONTEXT_MAP`)
+| `WebApp`
+
+(GC-free mode: `CopyOnWrite`)
+a| Fully specified class name of a custom `ThreadContextMap` implementation class or one of the predefined constants:
+
+* `NoOp`: to disable the thread context,
+* `WebApp`: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks,
+* `CopyOnWrite`: a copy-on-write implementation,
+* `GarbageFree`: a garbage-free implementation.
+
+| [[isThreadContextMapInheritable]]`log4j2.isThreadContextMapInheritable`
+
+(`LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`)
+| false
+| If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
+
+| [[log4j2.garbagefreeThreadContextMap]]`log4j2.garbagefreeThreadContextMap`
+
+(`LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP`)
+| false
+| If set to `true` selects a garbage-free thread context map implementation.
+Requires <<log4j2.enableThreadlocals>> to be also `true`.
+
+|===
+
+== Log4j Core
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration_new.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
+
+=== Async components
+
+The behavior of all three async components (`AsyncLogger`, `AsyncLoggerConfig` and `AsyncAppender`) can be tuned using these properties:
+
+.Common async component configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.formatMsgAsync]]`log4j2.formatMsgAsync`
+
+(`LOG4J_FORMAT_MSG_ASYNC`)
+| false
+| If `false`, Log4j will make sure the message is formatted in the caller thread, otherwise the formatting will occur on the asynchronous thread.
+
+**Remark**: messages annotated with link:../javadoc/log4j-api/org/apache/logging/log4j/message/AsynchronouslyFormattable[AsynchronouslyFormattable] will be formatted on the async thread regardless of this setting.
+
+| [[log4j2.asyncQueueFullPolicy]]`log4j2.asyncQueueFullPolicy`
+
+(`LOG4J_ASYNC_QUEUE_FULL_POLICY`)
+| `Default`
+a| Determines the link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy[AsyncQueueFullPolicy] to use when the underlying async component cannot keep up with the logging rate and the queue is filling up.
+
+It accepts the following values:
+
+* `Default`: blocks the calling thread until the event can be added to the queue.
+
+* `Discard`: when the queue is full, it drops the events whose level is equal or less than the threshold level (see <<log4j2.discardThreshold>>).
+
+* the fully qualified class name of a custom implementation
+
+| [[log4j2.discardThreshold]]`log4j2.discardThreshold`
+
+(`LOG4J_DISCARD_THRESHOLD`)
+| `INFO`
+| Determines the threshold level used by a `Discard` queue full policy.
+Log events whose level is equal or less specific than the threshold level will be discarded during a queue full event.
+See also <<log4j2.asyncQueueFullPolicy>>.
+
+|===
+
+==== `AsyncLogger`
+
+Additional properties supported by `AsyncLogger` are documented in the xref:manual/async.adoc#SysPropsAllAsync[System Properties to configure all asynchronous loggers] table.
+
+==== `AsyncLoggerConfig`
+
+Additional properties supported by `AsyncLoggerConfig` are documented in the xref:manual/async.adoc#SysPropsMixedSync-Async[System Properties to configure mixed asynchronous and normal loggers] table.
+
+=== Context selector
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ContextSelector[ContextSelector] component specifies the strategy used by Log4j to create new logger contexts.
+The choice of `ContextSelector` determines in particular:
+
+* how loggers are divided among logger contexts.
+See xref:manual/logsep.adoc[Log Separation] for details.
+
+* the `Logger` implementation used by Log4j Core.
+See xref:manual/async.adoc[Async Logging] as an example of this usage.
+
+.Context selector configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.contextSelector]]`log4j2.contextSelector`
+
+(`LOG4J_CONTEXT_SELECTOR`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[ClassLoaderContextSelector]
+a|
+Specifies the fully qualified class name of the `ContextSelector` implementation to use.
+
+The implementations available by default are:
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/BasicContextSelector[org.apache.logging.log4j
+.core.selector.BasicContextSelector]: creates a single logger context and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/BasicAsyncLoggerContextSelector[org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector]: creates a single logger context and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[org.apache.logging.log4j.core.selector.ClassLoaderContextSelector]: creates a separate logger context per classloader and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector[org.apache.logging.log4j.core.async.AsyncLoggerContextSelector]: creates a separate logger context per classloader and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/osgi/BundleContextSelector[org.apache.logging.log4j.core.osgi.BundleContextSelector]: creates a separate logger context per OSGi bundle and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/JndiContextSelector[org.apache.logging.log4j.core.selector.JndiContextSelector]: creates loggers contexts based on a JNDI lookup and synchronous loggers.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application]] for details.
+
+|===
+
+=== Configuration factory
+
+Since configuration factories are used to parse the configuration file, they can **only** be configured through global configuration properties.
+
+[WARNING]
+====
+Log4j Core supports both local and remote configuration files.
+If a remote configuration file is used, its transport must be secured.
+See <<transport-security>> for details.
+====
+
+.Configuration factory properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationFactory]]`log4j2.configurationFactory`
+
+(`LOG4J_CONFIGURATION_FACTORY`)
+|
+|
+Specifies the fully qualified class name of the **preferred** link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory[ConfigurationFactory] to use.
+
+Log4j will attempt to use the provided configuration factory before any other factory implementation.
+
+| [[log4j2.configurationFile]]`log4j2.configurationFile`
+
+(`LOG4J_CONFIGURATION_FILE`)
+| xref:manual/configuration.adoc#AutomaticConfiguration[automatically detected]
+a|
+Specifies a comma-separated list of URIs or file paths to Log4j 2 configuration files.
+
+If a relative URL is provided, it is interpreted as:
+
+* path to a file, if the file exists,
+* a classpath resource otherwise.
+
+See also xref:manual/configuration.adoc#AutomaticConfiguration[Automatic Configuration].
+
+| [[log4j2.level]]`log4j2.level`
+
+(`LOG4J_LEVEL`)
+| `ERROR`
+a|
+Specifies the level of the root logger if:
+
+* the default configuration is used,
+
+* or the configuration file does not specify a level for the root logger.
+
+| [[log4j2.mergeStrategy]]`log4j2.mergeStrategy`
+
+(`LOG4J_MERGE_STRATEGY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/DefaultMergeStrategy[DefaultMergeStrategy]
+|
+Specifies the fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/MergeStrategy[MergeStrategy] implementation used to merge multiple configuration files into one.
+
+|===
+
+=== Garbage Collection
+
+.GC properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+
+| [[log4j2.enableDirectEncoders]]`log4j2.enableDirectEncoders`
+
+(`LOG4J_ENABLE_DIRECT_ENCODERS`)
+| `true`
+|
+If `true`, garbage-aware layouts will directly encode log events into https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html[ByteBuffers] provided by appenders.
+
+This prevents the creation temporary multiple `String` and `char[]` temporary objects.
+
+| [[log4j2.initialReusableMsgSize]]`log4j2.initialReusableMsgSize`
+
+(`LOG4J_INITIAL_REUSABLE_MSG_SIZE`)
+| 128
+| In GC-free mode, this property determines the initial size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+| [[log4j2.maxReusableMsgSize]]`log4j2.maxReusableMsgSize`
+
+(`LOG4J_MAX_REUSABLE_MSG_SIZE`)
+| 518
+| In GC-free mode, this property determines the maximum size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+The default value allows is equal to `2 × (2 × log4j.initialReusableMsgSize + 2) + 2` and allows the
+``StringBuilder`` to be resized twice by the current JVM resize algorithm.
+
+| [[log4j2.layoutStringBuilderMaxSize]]`log4j2.layout{zwsp}StringBuilderMaxSize`
+
+(`LOG4J_LAYOUT_{zwsp}STRING_BUILDER_MAX_SIZE`)
+| 2048
+| This property determines the maximum size of the reusable ``StringBuilder``sused to format link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent[LogEvents].
+
+| [[log4j2.unboxRingbufferSize]]`log4j2.unboxRingbufferSize`
+
+(`LOG4J_UNBOX_RINGBUFFER_SIZE`)
+| 32
+|
+The link:../javadoc/log4j-api/org/apache/logging/log4j/util/Unbox[Unbox] utility class can be used by users to format primitive values without incurring in the boxing allocation cost.
+
+This property specifies the maximum number of primitive arguments to a log message that will be cached and usually does not need to be changed.
+
+|===
+
+=== JANSI
+
+If the https://fusesource.github.io/jansi/[JANSI] library is on the runtime classpath of the application, the following property can be used to control its usage:
+
+.JANSI properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.skipJansi]]`log4j2.skipJansi`
+
+(`LOG4J_SKIP_JANSI`)
+| `true`
+a| If the following conditions are satisfied:
+
+* Log4j runs on Windows,
+* this property is set to `false`,
+
+Log4j will use the JANSI library to color the output of the console appender.
+
+|===
+
+=== JNDI
+
+Due to the inherent security problems of https://docs.oracle.com/javase/tutorial/jndi/overview/[JNDI], its usage in Log4j is restricted to the `java:` protocol.
+
+Moreover, each JNDI usage must be **explicitly** enabled by the user through the following configuration properties.
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.enableJndiContextSelector]]`log4j2.enableJndiContextSelector`
+
+(`LOG4J_ENABLE_JNDI_CONTEXT_SELECTOR`)
+| `false`
+|
+When `true` the `JndiContextSelector` is enabled for the `java:` protocol.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application] for more details.
+
+| [[log4j2.enableJndiJdbc]]`log4j2.enableJndiJdbc`
+
+(`LOG4J_ENABLE_JNDI_JDBC`)
+| `false`
+| When `true`, a Log4j JDBC Appender can use JNDI to retrieve a https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[DataSource] using the `java:` protocol.
+
+| [[log4j2.enableJndiJms]]`log4j2.enableJndiJms`
+
+(`LOG4J_ENABLE_JNDI_JMS`)
+| `false`
+| When `true`, a Log4j JMS Appender can use JNDI to retrieve the necessary components using the `java:` protocol.
+
+| [[log4j2.enableJndiLookup]]`log4j2.enableJndiLookup`
+
+(`LOG4J_ENABLE_JNDI_LOOKUP`)
+| `false`
+| When `true`, the Log4j JNDI Lookup can use the `java:` protocol.
+
+|===
+
+=== JMX
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableJmx]]`log4j2.disableJmx`
+
+(`LOG4J_DISABLE_JMX`)
+| `true`
+|
+If `false`, Log4j configuration objects like ``LoggerContext``s, ``Appender``s, ``Logger``s, etc.
+will be instrumented with ``MBean``s and can be remotely monitored and managed.
+
+| [[log4j2.jmxNotifyAsync]]`log4j2.jmxNotifyAsync`
+
+(`LOG4J_JMX_NOTIFY_ASYNC`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true`, Log4j's JMX notifications are sent from a separate background thread, otherwise they are sent from the caller thread.
+
+|===
+
+[#log4j-core-thread-context]
+=== Thread context (Log4j Core)
+
+Log4j Core supports the same properties as Simple Logger for the configuration of the thread context.
+See <<simple-logger-thread-context>> for more details.
+
+[#transport-security]
+=== Transport security
+
+Since configuration files can be used to load arbitrary classes into a Log4j Core `Configuration`, users need to ensure that all the configuration elements come from trusted sources (cf. link:/security#threat-common-config-sources[Thread model] for more information).
+
+In order to protect the user Log4j disables the `http` URI scheme by default and provides several configuration options to ensure secure transport of configuration files:
+
+:jsse-default-keystores: https://docs.oracle.com/en/java/javase/21/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-7D9F43B8-AABF-4C5B-93E6-3AFB18B66150
+
+.Transport security properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationAllowedProtocols]]`log4j2.configuration{zwsp}AllowedProtocols`
+
+(`LOG4J_CONFIGURATION_{zwsp}ALLOWED_PROTOCOLS`)
+| file, https, jar
+|
+A comma separated list of URL protocols that may be used to load any kind of configuration source.
+
+To completely prevent accessing the configuration via the Java https://docs.oracle.com/javase/8/docs/api/java/net/URL.html[URL class] specify a value of `_none`.
+
+// TODO: What about 'jar:http:'?
+
+| [[log4j2.configurationAuthorizationProvider]]`log4j2.configuration{zwsp}AuthorizationProvider`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_PROVIDER`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/BasicAuthorizationProvider[BasicAuthorizationProvider]
+| The fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/AuthorizationProvider[AuthorizationProvider] implementation to use with `http` and `https` URL protocols.
+
+3+h| HTTP Basic authentication
+
+| [[log4j2.configurationAuthorizationEncoding]]`log4j2.configuration{zwsp}AuthorizationEncoding`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_ENCODING`)
+| UTF-8
+| The encoding used in Basic Authentication (cf. https://datatracker.ietf.org/doc/html/rfc7617[RFC 7617]).
+
+| [[log4j2.configurationPassword]]`log4j2.configurationPassword`
+
+(`LOG4J_CONFIGURATION_PASSWORD`)
+|
+| The password to use in HTTP Basic authentication.
+
+If used in conjunction with <<log4j2.configurationPasswordDecryptor>> the contents of this variable are
+interpreted by the decryptor.
+
+| [[log4j2.configurationPasswordDecryptor]]`log4j2.configuration{zwsp}PasswordDecryptor`
+
+(`LOG4J_CONFIGURATION_{zwsp}PASSWORD_DECRYPTOR`)
+|
+| Fully qualified class name of an implementation of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/PasswordDecryptor[PasswordDecryptor] to use for the value of the <<log4j2.configurationPassword>> property.
+
+By default, the literal value of the password is used.
+
+| [[log4j2.configurationUsername]]`log4j2.configurationUsername`
+
+(`LOG4J_CONFIGURATION_USERNAME`)
+|
+| The username used in HTTP Basic authentication.
+
+3+h| TLS server authentication properties
+
+| [[log4j2.trustStoreLocation]]`log4j2.trustStoreLocation`
+
+(`LOG4J_TRUST_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java trust store]
+| The location of the trust store.
+
+| [[log4j2.trustStorePassword]]`log4j2.trustStorePassword`
+
+(`LOG4J_TRUST_STORE_PASSWORD`)
+|
+| The password for the trust store.
+
+| [[log4j2.trustStorePasswordFile]]`log4j2.trustStore{zwsp}PasswordFile`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the trust store.
+
+| [[log4j2.trustStorePasswordEnvironmentVariable]]`log4j2.trustStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains password for the trust store.
+
+| [[log4j2.trustStoreType]]`log4j2.trustStoreType`
+
+(`LOG4J_TRUST_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.trustStoreKeyManagerFactoryAlgorithm]]`log4j2.trustStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_TRUST_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+| [[log4j2.sslVerifyHostName]]`log4j2.sslVerifyHostName`
+
+(`LOG4J_SSL_VERIFY_HOST_NAME`)
+| false
+| If `true` enables verification of the name of the TLS server.
+
+3+h| TLS client authentication properties
+
+| [[log4j2.keyStoreLocation]]`log4j2.keyStoreLocation`
+
+(`LOG4J_KEY_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java key store]
+| The location of the private key store.
+
+| [[log4j2.keyStorePassword]]`log4j2.keyStorePassword`
+
+(`LOG4J_KEY_STORE_PASSWORD`)
+|
+| The password for the private key store.
+
+| [[log4j2.keyStorePasswordFile]]`log4j2.keyStore{zwsp}PasswordFile`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the private key store.
+
+| [[log4j2.keyStorePasswordEnvironmentVariable]]`log4j2.keyStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains the password for the private key store.
+
+| [[log4j2.keyStoreType]]`log4j2.keyStoreType`
+
+(`LOG4J_KEY_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.keyStoreKeyManagerFactoryAlgorithm]]`log4j2.keyStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_KEY_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+|===
+
+=== Miscellaneous properties
+
+.Miscellaneous configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.clock]]`log4j2.clock`
+
+(`LOG4J_CLOCK`)
+| `SystemClock`
+a|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/Clock[Clock] implementation used to timestamp log events.
+
+The possible values are:
+
+* `SystemClock`: uses the best available system clock as time source.
+See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/Clock.html#systemDefaultZone--[Clock#systemDefaultZone] for details.
+
+* `SystemMillisClock`: same as `SystemClock`, but truncates the result to a millisecond.
+
+* `CachedClock`: uses a separate thread to update the timestamp value.
+See link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/CachedClock[JavaDoc] for details.
+
+* `CoarseCachedClock`: alternative implementation of `CachedClock` with a slightly lower precision.
+See link:..//javadoc/log4j-core/org/apache/logging/log4j/core/util/CoarseCachedClock[JavaDoc] for details.
+
+* the fully qualified name of a custom implementation.
Review Comment:
```suggestion
The built-in implementations are:
`SystemClock`:: uses the best available system clock as time source.
See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/Clock.html#systemDefaultZone--[Clock#systemDefaultZone] for details.
`SystemMillisClock`:: same as `SystemClock`, but truncates the result to a millisecond.
`CachedClock`:: uses a separate thread to update the timestamp value.
See link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/CachedClock[JavaDoc] for details.
`CoarseCachedClock`:: alternative implementation of `CachedClock` with a slightly lower precision.
See link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/CoarseCachedClock[JavaDoc] for details.
```
##########
src/site/antora/modules/ROOT/pages/manual/async.adoc:
##########
@@ -363,87 +348,95 @@ 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: All system properties were renamed into a more consistent style in
-Log4j 2.10. All old property names are still supported which are
-documented xref:manual/configuration.adoc#SystemProperties[here].
-
[[SysPropsMixedSync-Async]]
.System Properties to configure mixed asynchronous and normal loggers
-[cols="5m,2,10a",options="header"]
+[cols="1,1,5"]
|===
-|System Property |Default Value |Description
+h| Java Property
-|log4j2.asyncLoggerConfigExceptionHandler
-|`default handler`
-|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.
+(Environment Variable)
+h| Default Value
+h| Description
-If not specified, the default exception handler will print a message and
+| [[log4j2.asyncLoggerConfigExceptionHandler]]`log4j2.asyncLoggerConfig{zwsp}ExceptionHandler`
+
+(`LOG4J_ASYNC_LOGGER_CONFIG_{zwsp}EXCEPTION_HANDLER`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerConfigDefaultExceptionHandler[AsyncLoggerConfig{zwsp}DefaultExceptionHandler]
+|
+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.
+
+The default exception handler will print a message and
stack trace to the standard error output stream.
-|log4j2.asyncLoggerConfigRingBufferSize
-|256 * 1024
-|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 behavious
-is determined by the
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy.html[AsyncQueueFullPolicy].
-
-|[[asyncLoggerConfigWaitStrategy]]log4j2.asyncLoggerConfigWaitStrategy
-|`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.asyncLoggerConfigTimeout
-|`10`
-|Timeout in milliseconds of `TimeoutBlockingWaitStrategy`. See
-link:#asyncLoggerConfigWaitStrategy[WaitStrategy System Property] for details.
+| [[log4j2.asyncLoggerConfigRingBufferSize]]`log4j2.asyncLoggerConfig{zwsp}RingBufferSize`
+
+(`LOG4J_ASYNC_LOGGER_CONFIG_{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].
+
+| [[log4j2.asyncLoggerConfigWaitStrategy]]`log4j2.asyncLoggerConfig{zwsp}WaitStrategy`
+
+(`LOG4J_ASYNC_LOGGER_CONFIG_{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.asyncLoggerConfigTimeout>>)
+
+* `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.asyncLoggerConfigRetries>> and <<log4j2.asyncLoggerConfigSleepTimeNs>>).
+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:
Please use AsciiDoc description lists.
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
+| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates.
+
+| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()]
+| Sets the timezone id used by status logger. See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html[ZoneId] for the accepted formats.
+
+|===
+
+=== Simple logger
+
+The simple logger implementation contained in `log4j-api` can be configured using these properties:
+
+.Simple logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.simplelogLevel]]`log4j2.simplelogLevel`
+
+(`LOG4J_SIMPLELOG_LEVEL`)
+| ERROR
+| Default level for new logger instances.
+
+| [[log4j2.simplelog.loggerName.level]]`log4j2.simplelog.<loggerName>.level`
+
+(`LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL`)
+| value of <<log4j2.simplelogLevel>>
+| Log level for a logger instance named `<loggerName>`.
+
+| [[log4j2.simplelogShowContextMap]]`log4j2.simplelogShowContextMap`
+
+(`LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP`)
+| false
+| If `true`, the full thread context map is included in each log message.
+
+| [[log4j2.simplelogShowlogname]]`log4j2.simplelogShowlogname`
+
+(`LOG4J_SIMPLELOG_SHOWLOGNAME`)
+| false
+| If `true`, the logger name is included in each log message.
+
+| [[log4j2.simplelogShowShortLogname]]`log4j2.simplelogShowShortLogname`
+
+(`LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME`)
+| true
+| If `true`, only the last component of a logger name is included in each log message.
+
+| [[log4j2.simplelogShowdatetime]]`log4j2.simplelogShowdatetime`
+
+(`LOG4J_SIMPLELOG_SHOWDATETIME`)
+| false
+| If `true`, a timestamp is included in each log message.
+
+| [[log4j2.simplelogDateTimeFormat]]`log4j2.simplelogDateTimeFormat`
+
+(`LOG4J_SIMPLELOG_DATE_TIME_FORMAT`)
+| `yyyy/MM/dd HH:mm:ss:SSS zzz`
+| Date-time format to use. Ignored if <<log4j2.simplelogShowdatetime>> is `false`.
+
+| [[log4j2.simplelogLogFile]]`log4j2.simplelogLogFile`
+
+(`LOG4J_SIMPLELOG_LOG_FILE`)
+| System.err
+a| Specifies the output stream used by all loggers:
+
+* `System.err` logs to the standard error output stream,
+* `System.out` logs to the standard output stream,
+* any other value is interpreted as a file name.
+
+|===
+
+[#simple-logger-thread-context]
+=== Thread context (Simple Logger)
+
+The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
+
+[WARNING]
+====
+These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API.
+
+The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
+
+The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
+====
+
+.Thread context configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableThreadContext]]`log4j2.disableThreadContext`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT`)
+| false
+| If `true`, the `ThreadContext` stack and map are disabled.
+
+| [[log4j2.disableThreadContextStack]]`log4j2.disableThreadContextStack`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_STACK`)
+| false
+| If `true`, the `ThreadContext` stack is disabled.
+
+| [[log4j2.disableThreadContextMap]]`log4j2.disableThreadContextMap`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_MAP`)
+| false
+| If `true`, the `ThreadContext` map is disabled.
+
+| [[log4j2.threadContextMap]]`log4j2.threadContextMap`
+
+(`LOG4J_THREAD_CONTEXT_MAP`)
+| `WebApp`
+
+(GC-free mode: `CopyOnWrite`)
+a| Fully specified class name of a custom `ThreadContextMap` implementation class or one of the predefined constants:
+
+* `NoOp`: to disable the thread context,
+* `WebApp`: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks,
+* `CopyOnWrite`: a copy-on-write implementation,
+* `GarbageFree`: a garbage-free implementation.
+
+| [[isThreadContextMapInheritable]]`log4j2.isThreadContextMapInheritable`
+
+(`LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`)
+| false
+| If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
+
+| [[log4j2.garbagefreeThreadContextMap]]`log4j2.garbagefreeThreadContextMap`
+
+(`LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP`)
+| false
+| If set to `true` selects a garbage-free thread context map implementation.
+Requires <<log4j2.enableThreadlocals>> to be also `true`.
+
+|===
+
+== Log4j Core
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration_new.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
+
+=== Async components
+
+The behavior of all three async components (`AsyncLogger`, `AsyncLoggerConfig` and `AsyncAppender`) can be tuned using these properties:
+
+.Common async component configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.formatMsgAsync]]`log4j2.formatMsgAsync`
+
+(`LOG4J_FORMAT_MSG_ASYNC`)
+| false
+| If `false`, Log4j will make sure the message is formatted in the caller thread, otherwise the formatting will occur on the asynchronous thread.
+
+**Remark**: messages annotated with link:../javadoc/log4j-api/org/apache/logging/log4j/message/AsynchronouslyFormattable[AsynchronouslyFormattable] will be formatted on the async thread regardless of this setting.
+
+| [[log4j2.asyncQueueFullPolicy]]`log4j2.asyncQueueFullPolicy`
+
+(`LOG4J_ASYNC_QUEUE_FULL_POLICY`)
+| `Default`
+a| Determines the link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy[AsyncQueueFullPolicy] to use when the underlying async component cannot keep up with the logging rate and the queue is filling up.
+
+It accepts the following values:
+
+* `Default`: blocks the calling thread until the event can be added to the queue.
+
+* `Discard`: when the queue is full, it drops the events whose level is equal or less than the threshold level (see <<log4j2.discardThreshold>>).
+
+* the fully qualified class name of a custom implementation
+
+| [[log4j2.discardThreshold]]`log4j2.discardThreshold`
+
+(`LOG4J_DISCARD_THRESHOLD`)
+| `INFO`
+| Determines the threshold level used by a `Discard` queue full policy.
+Log events whose level is equal or less specific than the threshold level will be discarded during a queue full event.
+See also <<log4j2.asyncQueueFullPolicy>>.
+
+|===
+
+==== `AsyncLogger`
+
+Additional properties supported by `AsyncLogger` are documented in the xref:manual/async.adoc#SysPropsAllAsync[System Properties to configure all asynchronous loggers] table.
+
+==== `AsyncLoggerConfig`
+
+Additional properties supported by `AsyncLoggerConfig` are documented in the xref:manual/async.adoc#SysPropsMixedSync-Async[System Properties to configure mixed asynchronous and normal loggers] table.
+
+=== Context selector
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ContextSelector[ContextSelector] component specifies the strategy used by Log4j to create new logger contexts.
+The choice of `ContextSelector` determines in particular:
+
+* how loggers are divided among logger contexts.
+See xref:manual/logsep.adoc[Log Separation] for details.
+
+* the `Logger` implementation used by Log4j Core.
+See xref:manual/async.adoc[Async Logging] as an example of this usage.
+
+.Context selector configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.contextSelector]]`log4j2.contextSelector`
+
+(`LOG4J_CONTEXT_SELECTOR`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[ClassLoaderContextSelector]
+a|
+Specifies the fully qualified class name of the `ContextSelector` implementation to use.
+
+The implementations available by default are:
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/BasicContextSelector[org.apache.logging.log4j
+.core.selector.BasicContextSelector]: creates a single logger context and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/BasicAsyncLoggerContextSelector[org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector]: creates a single logger context and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[org.apache.logging.log4j.core.selector.ClassLoaderContextSelector]: creates a separate logger context per classloader and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector[org.apache.logging.log4j.core.async.AsyncLoggerContextSelector]: creates a separate logger context per classloader and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/osgi/BundleContextSelector[org.apache.logging.log4j.core.osgi.BundleContextSelector]: creates a separate logger context per OSGi bundle and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/JndiContextSelector[org.apache.logging.log4j.core.selector.JndiContextSelector]: creates loggers contexts based on a JNDI lookup and synchronous loggers.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application]] for details.
+
+|===
+
+=== Configuration factory
+
+Since configuration factories are used to parse the configuration file, they can **only** be configured through global configuration properties.
+
+[WARNING]
+====
+Log4j Core supports both local and remote configuration files.
+If a remote configuration file is used, its transport must be secured.
+See <<transport-security>> for details.
+====
+
+.Configuration factory properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationFactory]]`log4j2.configurationFactory`
+
+(`LOG4J_CONFIGURATION_FACTORY`)
+|
+|
+Specifies the fully qualified class name of the **preferred** link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory[ConfigurationFactory] to use.
+
+Log4j will attempt to use the provided configuration factory before any other factory implementation.
+
+| [[log4j2.configurationFile]]`log4j2.configurationFile`
+
+(`LOG4J_CONFIGURATION_FILE`)
+| xref:manual/configuration.adoc#AutomaticConfiguration[automatically detected]
+a|
+Specifies a comma-separated list of URIs or file paths to Log4j 2 configuration files.
+
+If a relative URL is provided, it is interpreted as:
+
+* path to a file, if the file exists,
+* a classpath resource otherwise.
+
+See also xref:manual/configuration.adoc#AutomaticConfiguration[Automatic Configuration].
+
+| [[log4j2.level]]`log4j2.level`
+
+(`LOG4J_LEVEL`)
+| `ERROR`
+a|
+Specifies the level of the root logger if:
+
+* the default configuration is used,
+
+* or the configuration file does not specify a level for the root logger.
+
+| [[log4j2.mergeStrategy]]`log4j2.mergeStrategy`
+
+(`LOG4J_MERGE_STRATEGY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/DefaultMergeStrategy[DefaultMergeStrategy]
+|
+Specifies the fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/MergeStrategy[MergeStrategy] implementation used to merge multiple configuration files into one.
+
+|===
+
+=== Garbage Collection
+
+.GC properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+
+| [[log4j2.enableDirectEncoders]]`log4j2.enableDirectEncoders`
+
+(`LOG4J_ENABLE_DIRECT_ENCODERS`)
+| `true`
+|
+If `true`, garbage-aware layouts will directly encode log events into https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html[ByteBuffers] provided by appenders.
+
+This prevents the creation temporary multiple `String` and `char[]` temporary objects.
+
+| [[log4j2.initialReusableMsgSize]]`log4j2.initialReusableMsgSize`
+
+(`LOG4J_INITIAL_REUSABLE_MSG_SIZE`)
+| 128
+| In GC-free mode, this property determines the initial size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+| [[log4j2.maxReusableMsgSize]]`log4j2.maxReusableMsgSize`
+
+(`LOG4J_MAX_REUSABLE_MSG_SIZE`)
+| 518
+| In GC-free mode, this property determines the maximum size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+The default value allows is equal to `2 × (2 × log4j.initialReusableMsgSize + 2) + 2` and allows the
+``StringBuilder`` to be resized twice by the current JVM resize algorithm.
+
+| [[log4j2.layoutStringBuilderMaxSize]]`log4j2.layout{zwsp}StringBuilderMaxSize`
+
+(`LOG4J_LAYOUT_{zwsp}STRING_BUILDER_MAX_SIZE`)
+| 2048
+| This property determines the maximum size of the reusable ``StringBuilder``sused to format link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent[LogEvents].
+
+| [[log4j2.unboxRingbufferSize]]`log4j2.unboxRingbufferSize`
+
+(`LOG4J_UNBOX_RINGBUFFER_SIZE`)
+| 32
+|
+The link:../javadoc/log4j-api/org/apache/logging/log4j/util/Unbox[Unbox] utility class can be used by users to format primitive values without incurring in the boxing allocation cost.
+
+This property specifies the maximum number of primitive arguments to a log message that will be cached and usually does not need to be changed.
+
+|===
+
+=== JANSI
+
+If the https://fusesource.github.io/jansi/[JANSI] library is on the runtime classpath of the application, the following property can be used to control its usage:
+
+.JANSI properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.skipJansi]]`log4j2.skipJansi`
+
+(`LOG4J_SKIP_JANSI`)
+| `true`
+a| If the following conditions are satisfied:
+
+* Log4j runs on Windows,
+* this property is set to `false`,
+
+Log4j will use the JANSI library to color the output of the console appender.
+
+|===
+
+=== JNDI
+
+Due to the inherent security problems of https://docs.oracle.com/javase/tutorial/jndi/overview/[JNDI], its usage in Log4j is restricted to the `java:` protocol.
+
+Moreover, each JNDI usage must be **explicitly** enabled by the user through the following configuration properties.
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.enableJndiContextSelector]]`log4j2.enableJndiContextSelector`
+
+(`LOG4J_ENABLE_JNDI_CONTEXT_SELECTOR`)
+| `false`
+|
+When `true` the `JndiContextSelector` is enabled for the `java:` protocol.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application] for more details.
+
+| [[log4j2.enableJndiJdbc]]`log4j2.enableJndiJdbc`
+
+(`LOG4J_ENABLE_JNDI_JDBC`)
+| `false`
+| When `true`, a Log4j JDBC Appender can use JNDI to retrieve a https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[DataSource] using the `java:` protocol.
+
+| [[log4j2.enableJndiJms]]`log4j2.enableJndiJms`
+
+(`LOG4J_ENABLE_JNDI_JMS`)
+| `false`
+| When `true`, a Log4j JMS Appender can use JNDI to retrieve the necessary components using the `java:` protocol.
+
+| [[log4j2.enableJndiLookup]]`log4j2.enableJndiLookup`
+
+(`LOG4J_ENABLE_JNDI_LOOKUP`)
+| `false`
+| When `true`, the Log4j JNDI Lookup can use the `java:` protocol.
+
+|===
+
+=== JMX
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableJmx]]`log4j2.disableJmx`
+
+(`LOG4J_DISABLE_JMX`)
+| `true`
+|
+If `false`, Log4j configuration objects like ``LoggerContext``s, ``Appender``s, ``Logger``s, etc.
+will be instrumented with ``MBean``s and can be remotely monitored and managed.
+
+| [[log4j2.jmxNotifyAsync]]`log4j2.jmxNotifyAsync`
+
+(`LOG4J_JMX_NOTIFY_ASYNC`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true`, Log4j's JMX notifications are sent from a separate background thread, otherwise they are sent from the caller thread.
+
+|===
+
+[#log4j-core-thread-context]
+=== Thread context (Log4j Core)
+
+Log4j Core supports the same properties as Simple Logger for the configuration of the thread context.
+See <<simple-logger-thread-context>> for more details.
+
+[#transport-security]
+=== Transport security
+
+Since configuration files can be used to load arbitrary classes into a Log4j Core `Configuration`, users need to ensure that all the configuration elements come from trusted sources (cf. link:/security#threat-common-config-sources[Thread model] for more information).
+
+In order to protect the user Log4j disables the `http` URI scheme by default and provides several configuration options to ensure secure transport of configuration files:
+
+:jsse-default-keystores: https://docs.oracle.com/en/java/javase/21/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-7D9F43B8-AABF-4C5B-93E6-3AFB18B66150
+
+.Transport security properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationAllowedProtocols]]`log4j2.configuration{zwsp}AllowedProtocols`
+
+(`LOG4J_CONFIGURATION_{zwsp}ALLOWED_PROTOCOLS`)
+| file, https, jar
+|
+A comma separated list of URL protocols that may be used to load any kind of configuration source.
+
+To completely prevent accessing the configuration via the Java https://docs.oracle.com/javase/8/docs/api/java/net/URL.html[URL class] specify a value of `_none`.
+
+// TODO: What about 'jar:http:'?
+
+| [[log4j2.configurationAuthorizationProvider]]`log4j2.configuration{zwsp}AuthorizationProvider`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_PROVIDER`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/BasicAuthorizationProvider[BasicAuthorizationProvider]
+| The fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/AuthorizationProvider[AuthorizationProvider] implementation to use with `http` and `https` URL protocols.
+
+3+h| HTTP Basic authentication
+
+| [[log4j2.configurationAuthorizationEncoding]]`log4j2.configuration{zwsp}AuthorizationEncoding`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_ENCODING`)
+| UTF-8
+| The encoding used in Basic Authentication (cf. https://datatracker.ietf.org/doc/html/rfc7617[RFC 7617]).
+
+| [[log4j2.configurationPassword]]`log4j2.configurationPassword`
+
+(`LOG4J_CONFIGURATION_PASSWORD`)
+|
+| The password to use in HTTP Basic authentication.
+
+If used in conjunction with <<log4j2.configurationPasswordDecryptor>> the contents of this variable are
+interpreted by the decryptor.
+
+| [[log4j2.configurationPasswordDecryptor]]`log4j2.configuration{zwsp}PasswordDecryptor`
+
+(`LOG4J_CONFIGURATION_{zwsp}PASSWORD_DECRYPTOR`)
+|
+| Fully qualified class name of an implementation of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/PasswordDecryptor[PasswordDecryptor] to use for the value of the <<log4j2.configurationPassword>> property.
+
+By default, the literal value of the password is used.
+
+| [[log4j2.configurationUsername]]`log4j2.configurationUsername`
+
+(`LOG4J_CONFIGURATION_USERNAME`)
+|
+| The username used in HTTP Basic authentication.
+
+3+h| TLS server authentication properties
+
+| [[log4j2.trustStoreLocation]]`log4j2.trustStoreLocation`
+
+(`LOG4J_TRUST_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java trust store]
+| The location of the trust store.
+
+| [[log4j2.trustStorePassword]]`log4j2.trustStorePassword`
+
+(`LOG4J_TRUST_STORE_PASSWORD`)
+|
+| The password for the trust store.
+
+| [[log4j2.trustStorePasswordFile]]`log4j2.trustStore{zwsp}PasswordFile`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the trust store.
+
+| [[log4j2.trustStorePasswordEnvironmentVariable]]`log4j2.trustStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains password for the trust store.
+
+| [[log4j2.trustStoreType]]`log4j2.trustStoreType`
+
+(`LOG4J_TRUST_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.trustStoreKeyManagerFactoryAlgorithm]]`log4j2.trustStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_TRUST_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+| [[log4j2.sslVerifyHostName]]`log4j2.sslVerifyHostName`
+
+(`LOG4J_SSL_VERIFY_HOST_NAME`)
+| false
+| If `true` enables verification of the name of the TLS server.
+
+3+h| TLS client authentication properties
+
+| [[log4j2.keyStoreLocation]]`log4j2.keyStoreLocation`
+
+(`LOG4J_KEY_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java key store]
+| The location of the private key store.
+
+| [[log4j2.keyStorePassword]]`log4j2.keyStorePassword`
+
+(`LOG4J_KEY_STORE_PASSWORD`)
+|
+| The password for the private key store.
+
+| [[log4j2.keyStorePasswordFile]]`log4j2.keyStore{zwsp}PasswordFile`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the private key store.
+
+| [[log4j2.keyStorePasswordEnvironmentVariable]]`log4j2.keyStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains the password for the private key store.
+
+| [[log4j2.keyStoreType]]`log4j2.keyStoreType`
+
+(`LOG4J_KEY_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.keyStoreKeyManagerFactoryAlgorithm]]`log4j2.keyStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_KEY_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+|===
+
+=== Miscellaneous properties
+
+.Miscellaneous configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.clock]]`log4j2.clock`
+
+(`LOG4J_CLOCK`)
+| `SystemClock`
+a|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/Clock[Clock] implementation used to timestamp log events.
+
+The possible values are:
+
+* `SystemClock`: uses the best available system clock as time source.
+See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/Clock.html#systemDefaultZone--[Clock#systemDefaultZone] for details.
+
+* `SystemMillisClock`: same as `SystemClock`, but truncates the result to a millisecond.
+
+* `CachedClock`: uses a separate thread to update the timestamp value.
+See link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/CachedClock[JavaDoc] for details.
+
+* `CoarseCachedClock`: alternative implementation of `CachedClock` with a slightly lower precision.
+See link:..//javadoc/log4j-core/org/apache/logging/log4j/core/util/CoarseCachedClock[JavaDoc] for details.
+
+* the fully qualified name of a custom implementation.
+
+| [[log4j2.contextDataInjector]]`log4j2.contextDataInjector`
+
+(`LOG4J_CONTEXT_DATA_INJECTOR`)
+| depends on the `ThreadContextMap` implementation
+| Fully specified class name of a link:../javadoc/log4j-core/org/apache/logging/log4j/core/ContextDataInjector[ContextDataInjector] implementation.
+
+The default implementation uses all implementations of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ContextDataProvider[ContextDataProvider] registered with `ServiceLoader`.
+
+| [[log4j2.logEventFactory]]`log4j2.logEventFactory`
+
+(`LOG4J_LOG_EVENT_FACTORY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/DefaultLogEventFactory[DefaultLogEventFactory]
+
+(GC-free mode: link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/ReusableLogEventFactory[ReusableLogEventFactory])
+|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/LogEventFactory[LogEventFactory]
+implementation to use to create log events.
+
+| [[log4j2.shutdownHookEnabled]]`log4j2.shutdownHookEnabled`
+
+(`LOG4J_SHUTDOWN_HOOK_ENABLED`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true` a shutdown hook will be installed to stop all logger contexts when the system stops.
+
+| [[log4j2.shutdownCallbackRegistry]]`log4j2.shutdownCallbackRegistry`
+
+(`LOG4J_SHUTDOWN_CALLBACK_REGISTRY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/DefaultShutdownCallbackRegistry[DefaultShutdownCallbackRegistry]
+|
+The fully qualified class name of a link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry[ShutdownCallbackRegistry] implementation.
+Integrators can use this to customize the shutdown order of the JVM.
+
+The default implementation executes all shutdown actions in a separate `Thread` registered through https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#addShutdownHook-java.lang.Thread-[Runtime#addShutdownHook()].
+
+
+| [[log4j2.uuidSequence]]`log4j2.uuidSequence`
+
+(`LOG4J_UUID_SEQUENCE`)
+| 0
+|
+Provides a `long` see to the UUID generator used by the `%uuid` pattern converter.
+
+Can be used to assure uniqueness of UUIDs generated by multiple JVMs on the same machine.
+
+| [[log4j2.messageFactory]]`log4j2.messageFactory`
+
+(`LOG4J_MESSAGE_FACTORY`)
+| link:../javadoc/log4j-api/org/apache/logging/log4j/message/ParameterizedMessageFactory[ParameterizeMessageFactory]
+
+(GC-free mode: link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessageFactory[ReusableMessageFactory])
+| Default message factory used by loggers if no factory was specified.
+
+| [[log4j2.flowMessageFactory]]`log4j2.flowMessageFactory`
+
+(`LOG4J_FLOW_MESSAGE_FACTORY`)
+| link:../javadoc/log4j-api/org/apache/logging/log4j/message/DefaultFlowMessageFactory[DefaultFlowMessageFactory]
+| Default flow message factory used by Loggers.
+
+| [[log4j2.loggerContextStacktraceOnStart]]`log4j2.loggerContext{zwsp}StacktraceOnStart`
+
+(`LOG4J_LOGGER_CONTEXT_{zwsp}STACKTRACE_ON_START`)
+| `false`
+| Prints a stacktrace to the xref:manual/configuration.adoc#StatusMessages[status logger] at `DEBUG` level when the LoggerContext is started.
+
+For debug purposes only.
+
+| [[log4j2.scriptEnableLanguages]]`log4j2.scriptEnableLanguages`
+
+(`LOG4J_SCRIPT_ENABLE_LANGUAGES`)
+|
+| The list of script languages that are allowed to execute.
+
+The names specified must correspond to those returned by https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/script/ScriptEngineFactory.html#getNames--[ScriptEngineFactory#getNames()].
+
+|===
+
+== JUL-to-Log4j API bridge
+
+The JUL-to-Log4j API bridge provides the following configuration properties:
+
+.JUL configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.julLevelConverter]]`log4j2.julLevelConverter`
+
+(`LOG4J_JUL_LEVEL_CONVERTER`)
+|
+|
+Fully qualified name of an alternative `org.apache.logging.log4j.jul.LevelConverter` implementation.
+
+See xref:log4j-jul.adoc#default-level-conversions[Default Level Conversions] for the default implementation.
+
+| [[log4j2.julLoggerAdapter]]`log4j2.julLoggerAdapter`
+
+(`LOG4J_JUL_LOGGER_ADAPTER`)
+| depends on classpath
+a|
+This property allows users to choose between two implementation of the logging bridge:
+
+* `org.apache.logging.log4j.jul.CoreLoggerAdapter` (default if `log4j-core` present) allows users to modify the Log4j Core configuration through the JUL https://docs.oracle.com/javase/8/docs/api/java/util/logging/Logger.html[Logger] interface,
+
+* `org.apache.logging.log4j.jul.ApiLoggerAdapter` (default if `log4j-core` absent) disables the level mutators in the JUL `Logger` interface.
Review Comment:
```suggestion
`org.apache.logging.log4j.jul.CoreLoggerAdapter`::
The default if `log4j-core` is found in the class path.
It allows users to modify the Log4j Core configuration through the JUL https://docs.oracle.com/javase/8/docs/api/java/util/logging/Logger.html[Logger] interface.
`org.apache.logging.log4j.jul.ApiLoggerAdapter`::
The default if `log4j-core` cannot be found in the class path.
It disables the level mutators in the JUL `Logger` interface.
```
##########
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()].
Review Comment:
Link is broken.
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587646691
##########
src/site/antora/modules/ROOT/pages/log4j-jmx-gui.adoc:
##########
@@ -23,5 +23,5 @@ The client GUI can be run as a stand-alone application or as a JConsole plug-in.
====
The Java VM to be monitored has to enable Log4j JMX support, set the following system property when starting the Java VM:
-`log4j2.disableJmx=false`
+`xref:manual/configuration.adoc#log4j2.disableJmx[log4j2.disableJmx]=false`
Review Comment:
Fixed in 928d23bfdb70b3f346856fc7c12ffcf6bfb0d196
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587667130
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
+| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates.
+
+| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()]
+| Sets the timezone id used by status logger. See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html[ZoneId] for the accepted formats.
+
+|===
+
+=== Simple logger
+
+The simple logger implementation contained in `log4j-api` can be configured using these properties:
+
+.Simple logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.simplelogLevel]]`log4j2.simplelogLevel`
+
+(`LOG4J_SIMPLELOG_LEVEL`)
+| ERROR
+| Default level for new logger instances.
+
+| [[log4j2.simplelog.loggerName.level]]`log4j2.simplelog.<loggerName>.level`
+
+(`LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL`)
+| value of <<log4j2.simplelogLevel>>
+| Log level for a logger instance named `<loggerName>`.
+
+| [[log4j2.simplelogShowContextMap]]`log4j2.simplelogShowContextMap`
+
+(`LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP`)
+| false
+| If `true`, the full thread context map is included in each log message.
+
+| [[log4j2.simplelogShowlogname]]`log4j2.simplelogShowlogname`
+
+(`LOG4J_SIMPLELOG_SHOWLOGNAME`)
+| false
+| If `true`, the logger name is included in each log message.
+
+| [[log4j2.simplelogShowShortLogname]]`log4j2.simplelogShowShortLogname`
+
+(`LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME`)
+| true
+| If `true`, only the last component of a logger name is included in each log message.
+
+| [[log4j2.simplelogShowdatetime]]`log4j2.simplelogShowdatetime`
+
+(`LOG4J_SIMPLELOG_SHOWDATETIME`)
+| false
+| If `true`, a timestamp is included in each log message.
+
+| [[log4j2.simplelogDateTimeFormat]]`log4j2.simplelogDateTimeFormat`
+
+(`LOG4J_SIMPLELOG_DATE_TIME_FORMAT`)
+| `yyyy/MM/dd HH:mm:ss:SSS zzz`
+| Date-time format to use. Ignored if <<log4j2.simplelogShowdatetime>> is `false`.
+
+| [[log4j2.simplelogLogFile]]`log4j2.simplelogLogFile`
+
+(`LOG4J_SIMPLELOG_LOG_FILE`)
+| System.err
+a| Specifies the output stream used by all loggers:
+
+* `System.err` logs to the standard error output stream,
+* `System.out` logs to the standard output stream,
+* any other value is interpreted as a file name.
+
+|===
+
+[#simple-logger-thread-context]
+=== Thread context (Simple Logger)
+
+The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
+
+[WARNING]
+====
+These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API.
+
+The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
+
+The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
+====
+
+.Thread context configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableThreadContext]]`log4j2.disableThreadContext`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT`)
+| false
+| If `true`, the `ThreadContext` stack and map are disabled.
+
+| [[log4j2.disableThreadContextStack]]`log4j2.disableThreadContextStack`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_STACK`)
+| false
+| If `true`, the `ThreadContext` stack is disabled.
+
+| [[log4j2.disableThreadContextMap]]`log4j2.disableThreadContextMap`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_MAP`)
+| false
+| If `true`, the `ThreadContext` map is disabled.
+
+| [[log4j2.threadContextMap]]`log4j2.threadContextMap`
+
+(`LOG4J_THREAD_CONTEXT_MAP`)
+| `WebApp`
+
+(GC-free mode: `CopyOnWrite`)
+a| Fully specified class name of a custom `ThreadContextMap` implementation class or one of the predefined constants:
+
+* `NoOp`: to disable the thread context,
+* `WebApp`: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks,
+* `CopyOnWrite`: a copy-on-write implementation,
+* `GarbageFree`: a garbage-free implementation.
+
+| [[isThreadContextMapInheritable]]`log4j2.isThreadContextMapInheritable`
+
+(`LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`)
+| false
+| If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
+
+| [[log4j2.garbagefreeThreadContextMap]]`log4j2.garbagefreeThreadContextMap`
+
+(`LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP`)
+| false
+| If set to `true` selects a garbage-free thread context map implementation.
+Requires <<log4j2.enableThreadlocals>> to be also `true`.
+
+|===
+
+== Log4j Core
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration_new.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
+
+=== Async components
+
+The behavior of all three async components (`AsyncLogger`, `AsyncLoggerConfig` and `AsyncAppender`) can be tuned using these properties:
+
+.Common async component configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.formatMsgAsync]]`log4j2.formatMsgAsync`
+
+(`LOG4J_FORMAT_MSG_ASYNC`)
+| false
+| If `false`, Log4j will make sure the message is formatted in the caller thread, otherwise the formatting will occur on the asynchronous thread.
+
+**Remark**: messages annotated with link:../javadoc/log4j-api/org/apache/logging/log4j/message/AsynchronouslyFormattable[AsynchronouslyFormattable] will be formatted on the async thread regardless of this setting.
+
+| [[log4j2.asyncQueueFullPolicy]]`log4j2.asyncQueueFullPolicy`
+
+(`LOG4J_ASYNC_QUEUE_FULL_POLICY`)
+| `Default`
+a| Determines the link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy[AsyncQueueFullPolicy] to use when the underlying async component cannot keep up with the logging rate and the queue is filling up.
+
+It accepts the following values:
+
+* `Default`: blocks the calling thread until the event can be added to the queue.
+
+* `Discard`: when the queue is full, it drops the events whose level is equal or less than the threshold level (see <<log4j2.discardThreshold>>).
+
+* the fully qualified class name of a custom implementation
+
+| [[log4j2.discardThreshold]]`log4j2.discardThreshold`
+
+(`LOG4J_DISCARD_THRESHOLD`)
+| `INFO`
+| Determines the threshold level used by a `Discard` queue full policy.
+Log events whose level is equal or less specific than the threshold level will be discarded during a queue full event.
+See also <<log4j2.asyncQueueFullPolicy>>.
+
+|===
+
+==== `AsyncLogger`
+
+Additional properties supported by `AsyncLogger` are documented in the xref:manual/async.adoc#SysPropsAllAsync[System Properties to configure all asynchronous loggers] table.
+
+==== `AsyncLoggerConfig`
+
+Additional properties supported by `AsyncLoggerConfig` are documented in the xref:manual/async.adoc#SysPropsMixedSync-Async[System Properties to configure mixed asynchronous and normal loggers] table.
+
+=== Context selector
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ContextSelector[ContextSelector] component specifies the strategy used by Log4j to create new logger contexts.
+The choice of `ContextSelector` determines in particular:
+
+* how loggers are divided among logger contexts.
+See xref:manual/logsep.adoc[Log Separation] for details.
+
+* the `Logger` implementation used by Log4j Core.
+See xref:manual/async.adoc[Async Logging] as an example of this usage.
+
+.Context selector configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.contextSelector]]`log4j2.contextSelector`
+
+(`LOG4J_CONTEXT_SELECTOR`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[ClassLoaderContextSelector]
+a|
+Specifies the fully qualified class name of the `ContextSelector` implementation to use.
+
+The implementations available by default are:
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/BasicContextSelector[org.apache.logging.log4j
+.core.selector.BasicContextSelector]: creates a single logger context and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/BasicAsyncLoggerContextSelector[org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector]: creates a single logger context and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[org.apache.logging.log4j.core.selector.ClassLoaderContextSelector]: creates a separate logger context per classloader and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector[org.apache.logging.log4j.core.async.AsyncLoggerContextSelector]: creates a separate logger context per classloader and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/osgi/BundleContextSelector[org.apache.logging.log4j.core.osgi.BundleContextSelector]: creates a separate logger context per OSGi bundle and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/JndiContextSelector[org.apache.logging.log4j.core.selector.JndiContextSelector]: creates loggers contexts based on a JNDI lookup and synchronous loggers.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application]] for details.
+
+|===
+
+=== Configuration factory
+
+Since configuration factories are used to parse the configuration file, they can **only** be configured through global configuration properties.
+
+[WARNING]
+====
+Log4j Core supports both local and remote configuration files.
+If a remote configuration file is used, its transport must be secured.
+See <<transport-security>> for details.
+====
+
+.Configuration factory properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationFactory]]`log4j2.configurationFactory`
+
+(`LOG4J_CONFIGURATION_FACTORY`)
+|
+|
+Specifies the fully qualified class name of the **preferred** link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory[ConfigurationFactory] to use.
+
+Log4j will attempt to use the provided configuration factory before any other factory implementation.
+
+| [[log4j2.configurationFile]]`log4j2.configurationFile`
+
+(`LOG4J_CONFIGURATION_FILE`)
+| xref:manual/configuration.adoc#AutomaticConfiguration[automatically detected]
+a|
+Specifies a comma-separated list of URIs or file paths to Log4j 2 configuration files.
+
+If a relative URL is provided, it is interpreted as:
+
+* path to a file, if the file exists,
+* a classpath resource otherwise.
+
+See also xref:manual/configuration.adoc#AutomaticConfiguration[Automatic Configuration].
+
+| [[log4j2.level]]`log4j2.level`
+
+(`LOG4J_LEVEL`)
+| `ERROR`
+a|
+Specifies the level of the root logger if:
+
+* the default configuration is used,
+
+* or the configuration file does not specify a level for the root logger.
+
+| [[log4j2.mergeStrategy]]`log4j2.mergeStrategy`
+
+(`LOG4J_MERGE_STRATEGY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/DefaultMergeStrategy[DefaultMergeStrategy]
+|
+Specifies the fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/MergeStrategy[MergeStrategy] implementation used to merge multiple configuration files into one.
+
+|===
+
+=== Garbage Collection
+
+.GC properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+
+| [[log4j2.enableDirectEncoders]]`log4j2.enableDirectEncoders`
+
+(`LOG4J_ENABLE_DIRECT_ENCODERS`)
+| `true`
+|
+If `true`, garbage-aware layouts will directly encode log events into https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html[ByteBuffers] provided by appenders.
+
+This prevents the creation temporary multiple `String` and `char[]` temporary objects.
+
+| [[log4j2.initialReusableMsgSize]]`log4j2.initialReusableMsgSize`
+
+(`LOG4J_INITIAL_REUSABLE_MSG_SIZE`)
+| 128
+| In GC-free mode, this property determines the initial size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+| [[log4j2.maxReusableMsgSize]]`log4j2.maxReusableMsgSize`
+
+(`LOG4J_MAX_REUSABLE_MSG_SIZE`)
+| 518
+| In GC-free mode, this property determines the maximum size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+The default value allows is equal to `2 × (2 × log4j.initialReusableMsgSize + 2) + 2` and allows the
+``StringBuilder`` to be resized twice by the current JVM resize algorithm.
+
+| [[log4j2.layoutStringBuilderMaxSize]]`log4j2.layout{zwsp}StringBuilderMaxSize`
+
+(`LOG4J_LAYOUT_{zwsp}STRING_BUILDER_MAX_SIZE`)
+| 2048
+| This property determines the maximum size of the reusable ``StringBuilder``sused to format link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent[LogEvents].
+
+| [[log4j2.unboxRingbufferSize]]`log4j2.unboxRingbufferSize`
+
+(`LOG4J_UNBOX_RINGBUFFER_SIZE`)
+| 32
+|
+The link:../javadoc/log4j-api/org/apache/logging/log4j/util/Unbox[Unbox] utility class can be used by users to format primitive values without incurring in the boxing allocation cost.
+
+This property specifies the maximum number of primitive arguments to a log message that will be cached and usually does not need to be changed.
+
+|===
+
+=== JANSI
+
+If the https://fusesource.github.io/jansi/[JANSI] library is on the runtime classpath of the application, the following property can be used to control its usage:
+
+.JANSI properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.skipJansi]]`log4j2.skipJansi`
+
+(`LOG4J_SKIP_JANSI`)
+| `true`
+a| If the following conditions are satisfied:
+
+* Log4j runs on Windows,
+* this property is set to `false`,
+
+Log4j will use the JANSI library to color the output of the console appender.
+
+|===
+
+=== JNDI
+
+Due to the inherent security problems of https://docs.oracle.com/javase/tutorial/jndi/overview/[JNDI], its usage in Log4j is restricted to the `java:` protocol.
+
+Moreover, each JNDI usage must be **explicitly** enabled by the user through the following configuration properties.
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.enableJndiContextSelector]]`log4j2.enableJndiContextSelector`
+
+(`LOG4J_ENABLE_JNDI_CONTEXT_SELECTOR`)
+| `false`
+|
+When `true` the `JndiContextSelector` is enabled for the `java:` protocol.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application] for more details.
+
+| [[log4j2.enableJndiJdbc]]`log4j2.enableJndiJdbc`
+
+(`LOG4J_ENABLE_JNDI_JDBC`)
+| `false`
+| When `true`, a Log4j JDBC Appender can use JNDI to retrieve a https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[DataSource] using the `java:` protocol.
+
+| [[log4j2.enableJndiJms]]`log4j2.enableJndiJms`
+
+(`LOG4J_ENABLE_JNDI_JMS`)
+| `false`
+| When `true`, a Log4j JMS Appender can use JNDI to retrieve the necessary components using the `java:` protocol.
+
+| [[log4j2.enableJndiLookup]]`log4j2.enableJndiLookup`
+
+(`LOG4J_ENABLE_JNDI_LOOKUP`)
+| `false`
+| When `true`, the Log4j JNDI Lookup can use the `java:` protocol.
+
+|===
+
+=== JMX
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableJmx]]`log4j2.disableJmx`
+
+(`LOG4J_DISABLE_JMX`)
+| `true`
+|
+If `false`, Log4j configuration objects like ``LoggerContext``s, ``Appender``s, ``Logger``s, etc.
+will be instrumented with ``MBean``s and can be remotely monitored and managed.
+
+| [[log4j2.jmxNotifyAsync]]`log4j2.jmxNotifyAsync`
+
+(`LOG4J_JMX_NOTIFY_ASYNC`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true`, Log4j's JMX notifications are sent from a separate background thread, otherwise they are sent from the caller thread.
+
+|===
+
+[#log4j-core-thread-context]
+=== Thread context (Log4j Core)
+
+Log4j Core supports the same properties as Simple Logger for the configuration of the thread context.
+See <<simple-logger-thread-context>> for more details.
+
+[#transport-security]
+=== Transport security
+
+Since configuration files can be used to load arbitrary classes into a Log4j Core `Configuration`, users need to ensure that all the configuration elements come from trusted sources (cf. link:/security#threat-common-config-sources[Thread model] for more information).
+
+In order to protect the user Log4j disables the `http` URI scheme by default and provides several configuration options to ensure secure transport of configuration files:
+
+:jsse-default-keystores: https://docs.oracle.com/en/java/javase/21/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-7D9F43B8-AABF-4C5B-93E6-3AFB18B66150
+
+.Transport security properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationAllowedProtocols]]`log4j2.configuration{zwsp}AllowedProtocols`
+
+(`LOG4J_CONFIGURATION_{zwsp}ALLOWED_PROTOCOLS`)
+| file, https, jar
+|
+A comma separated list of URL protocols that may be used to load any kind of configuration source.
+
+To completely prevent accessing the configuration via the Java https://docs.oracle.com/javase/8/docs/api/java/net/URL.html[URL class] specify a value of `_none`.
+
+// TODO: What about 'jar:http:'?
+
+| [[log4j2.configurationAuthorizationProvider]]`log4j2.configuration{zwsp}AuthorizationProvider`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_PROVIDER`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/BasicAuthorizationProvider[BasicAuthorizationProvider]
+| The fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/AuthorizationProvider[AuthorizationProvider] implementation to use with `http` and `https` URL protocols.
+
+3+h| HTTP Basic authentication
+
+| [[log4j2.configurationAuthorizationEncoding]]`log4j2.configuration{zwsp}AuthorizationEncoding`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_ENCODING`)
+| UTF-8
+| The encoding used in Basic Authentication (cf. https://datatracker.ietf.org/doc/html/rfc7617[RFC 7617]).
+
+| [[log4j2.configurationPassword]]`log4j2.configurationPassword`
+
+(`LOG4J_CONFIGURATION_PASSWORD`)
+|
+| The password to use in HTTP Basic authentication.
+
+If used in conjunction with <<log4j2.configurationPasswordDecryptor>> the contents of this variable are
+interpreted by the decryptor.
+
+| [[log4j2.configurationPasswordDecryptor]]`log4j2.configuration{zwsp}PasswordDecryptor`
+
+(`LOG4J_CONFIGURATION_{zwsp}PASSWORD_DECRYPTOR`)
+|
+| Fully qualified class name of an implementation of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/PasswordDecryptor[PasswordDecryptor] to use for the value of the <<log4j2.configurationPassword>> property.
+
+By default, the literal value of the password is used.
+
+| [[log4j2.configurationUsername]]`log4j2.configurationUsername`
+
+(`LOG4J_CONFIGURATION_USERNAME`)
+|
+| The username used in HTTP Basic authentication.
+
+3+h| TLS server authentication properties
+
+| [[log4j2.trustStoreLocation]]`log4j2.trustStoreLocation`
+
+(`LOG4J_TRUST_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java trust store]
+| The location of the trust store.
+
+| [[log4j2.trustStorePassword]]`log4j2.trustStorePassword`
+
+(`LOG4J_TRUST_STORE_PASSWORD`)
+|
+| The password for the trust store.
+
+| [[log4j2.trustStorePasswordFile]]`log4j2.trustStore{zwsp}PasswordFile`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the trust store.
+
+| [[log4j2.trustStorePasswordEnvironmentVariable]]`log4j2.trustStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains password for the trust store.
+
+| [[log4j2.trustStoreType]]`log4j2.trustStoreType`
+
+(`LOG4J_TRUST_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.trustStoreKeyManagerFactoryAlgorithm]]`log4j2.trustStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_TRUST_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+| [[log4j2.sslVerifyHostName]]`log4j2.sslVerifyHostName`
+
+(`LOG4J_SSL_VERIFY_HOST_NAME`)
+| false
+| If `true` enables verification of the name of the TLS server.
+
+3+h| TLS client authentication properties
+
+| [[log4j2.keyStoreLocation]]`log4j2.keyStoreLocation`
+
+(`LOG4J_KEY_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java key store]
+| The location of the private key store.
+
+| [[log4j2.keyStorePassword]]`log4j2.keyStorePassword`
+
+(`LOG4J_KEY_STORE_PASSWORD`)
+|
+| The password for the private key store.
+
+| [[log4j2.keyStorePasswordFile]]`log4j2.keyStore{zwsp}PasswordFile`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the private key store.
+
+| [[log4j2.keyStorePasswordEnvironmentVariable]]`log4j2.keyStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains the password for the private key store.
+
+| [[log4j2.keyStoreType]]`log4j2.keyStoreType`
+
+(`LOG4J_KEY_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.keyStoreKeyManagerFactoryAlgorithm]]`log4j2.keyStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_KEY_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+|===
+
+=== Miscellaneous properties
+
+.Miscellaneous configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.clock]]`log4j2.clock`
+
+(`LOG4J_CLOCK`)
+| `SystemClock`
+a|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/Clock[Clock] implementation used to timestamp log events.
+
+The possible values are:
+
+* `SystemClock`: uses the best available system clock as time source.
+See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/Clock.html#systemDefaultZone--[Clock#systemDefaultZone] for details.
+
+* `SystemMillisClock`: same as `SystemClock`, but truncates the result to a millisecond.
+
+* `CachedClock`: uses a separate thread to update the timestamp value.
+See link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/CachedClock[JavaDoc] for details.
+
+* `CoarseCachedClock`: alternative implementation of `CachedClock` with a slightly lower precision.
+See link:..//javadoc/log4j-core/org/apache/logging/log4j/core/util/CoarseCachedClock[JavaDoc] for details.
+
+* the fully qualified name of a custom implementation.
+
+| [[log4j2.contextDataInjector]]`log4j2.contextDataInjector`
+
+(`LOG4J_CONTEXT_DATA_INJECTOR`)
+| depends on the `ThreadContextMap` implementation
+| Fully specified class name of a link:../javadoc/log4j-core/org/apache/logging/log4j/core/ContextDataInjector[ContextDataInjector] implementation.
+
+The default implementation uses all implementations of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ContextDataProvider[ContextDataProvider] registered with `ServiceLoader`.
+
+| [[log4j2.logEventFactory]]`log4j2.logEventFactory`
+
+(`LOG4J_LOG_EVENT_FACTORY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/DefaultLogEventFactory[DefaultLogEventFactory]
+
+(GC-free mode: link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/ReusableLogEventFactory[ReusableLogEventFactory])
+|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/LogEventFactory[LogEventFactory]
+implementation to use to create log events.
+
+| [[log4j2.shutdownHookEnabled]]`log4j2.shutdownHookEnabled`
+
+(`LOG4J_SHUTDOWN_HOOK_ENABLED`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true` a shutdown hook will be installed to stop all logger contexts when the system stops.
+
+| [[log4j2.shutdownCallbackRegistry]]`log4j2.shutdownCallbackRegistry`
+
+(`LOG4J_SHUTDOWN_CALLBACK_REGISTRY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/DefaultShutdownCallbackRegistry[DefaultShutdownCallbackRegistry]
+|
+The fully qualified class name of a link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry[ShutdownCallbackRegistry] implementation.
+Integrators can use this to customize the shutdown order of the JVM.
+
+The default implementation executes all shutdown actions in a separate `Thread` registered through https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#addShutdownHook-java.lang.Thread-[Runtime#addShutdownHook()].
+
+
+| [[log4j2.uuidSequence]]`log4j2.uuidSequence`
+
+(`LOG4J_UUID_SEQUENCE`)
+| 0
+|
+Provides a `long` see to the UUID generator used by the `%uuid` pattern converter.
+
+Can be used to assure uniqueness of UUIDs generated by multiple JVMs on the same machine.
+
+| [[log4j2.messageFactory]]`log4j2.messageFactory`
+
+(`LOG4J_MESSAGE_FACTORY`)
+| link:../javadoc/log4j-api/org/apache/logging/log4j/message/ParameterizedMessageFactory[ParameterizeMessageFactory]
+
+(GC-free mode: link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessageFactory[ReusableMessageFactory])
+| Default message factory used by loggers if no factory was specified.
+
+| [[log4j2.flowMessageFactory]]`log4j2.flowMessageFactory`
+
+(`LOG4J_FLOW_MESSAGE_FACTORY`)
+| link:../javadoc/log4j-api/org/apache/logging/log4j/message/DefaultFlowMessageFactory[DefaultFlowMessageFactory]
+| Default flow message factory used by Loggers.
+
+| [[log4j2.loggerContextStacktraceOnStart]]`log4j2.loggerContext{zwsp}StacktraceOnStart`
+
+(`LOG4J_LOGGER_CONTEXT_{zwsp}STACKTRACE_ON_START`)
+| `false`
+| Prints a stacktrace to the xref:manual/configuration.adoc#StatusMessages[status logger] at `DEBUG` level when the LoggerContext is started.
+
+For debug purposes only.
+
+| [[log4j2.scriptEnableLanguages]]`log4j2.scriptEnableLanguages`
+
+(`LOG4J_SCRIPT_ENABLE_LANGUAGES`)
+|
+| The list of script languages that are allowed to execute.
+
+The names specified must correspond to those returned by https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/script/ScriptEngineFactory.html#getNames--[ScriptEngineFactory#getNames()].
+
+|===
+
+== JUL-to-Log4j API bridge
+
+The JUL-to-Log4j API bridge provides the following configuration properties:
+
+.JUL configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.julLevelConverter]]`log4j2.julLevelConverter`
+
+(`LOG4J_JUL_LEVEL_CONVERTER`)
+|
+|
+Fully qualified name of an alternative `org.apache.logging.log4j.jul.LevelConverter` implementation.
+
+See xref:log4j-jul.adoc#default-level-conversions[Default Level Conversions] for the default implementation.
+
+| [[log4j2.julLoggerAdapter]]`log4j2.julLoggerAdapter`
+
+(`LOG4J_JUL_LOGGER_ADAPTER`)
+| depends on classpath
+a|
+This property allows users to choose between two implementation of the logging bridge:
+
+* `org.apache.logging.log4j.jul.CoreLoggerAdapter` (default if `log4j-core` present) allows users to modify the Log4j Core configuration through the JUL https://docs.oracle.com/javase/8/docs/api/java/util/logging/Logger.html[Logger] interface,
+
+* `org.apache.logging.log4j.jul.ApiLoggerAdapter` (default if `log4j-core` absent) disables the level mutators in the JUL `Logger` interface.
+
+|===
+
+== Log4j Spring Boot
+
+The Log4j Spring Boot module supports the following configuration properties:
+
+.Spring Boot configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableCloudConfigLoggingSystem]]`log4j2.disable{zwsp}CloudConfigLoggingSystem`
+
+(`LOG4J_DISABLE_{zwsp}CLOUD_CONFIG_LOGGING_SYSTEM`)
+| `false`
+| Disables the usage of the Spring Boot `Log4j2CloudConfigLoggingSystem`.
+
+|===
+
+[#property-sources]
Review Comment:
I think that this is a section for advanced users only. Most of the users will not be interested by this.
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1586701230
##########
src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc:
##########
@@ -122,67 +126,9 @@ logging:
Note that Log4j currently does not directly support encrypting the password.
However, Log4j does use Spring's standard APIs to access properties in the Spring configuration so any customizations made to Spring's property handling would apply to the properties Log4j uses as well.
-If more extensive authentication is required an `AuthorizationProvider` can be implemented and the fully qualified class name in the `log4j2.authorizationProvider` system property, in log4j2.component.properties or in Spring's bootstrap.yml using either the `log4j2.authorizationProvider` key or with the key `logging.auth.authorizationProvider`.
+If more extensive authentication is required an `AuthorizationProvider` can be implemented and the fully qualified class name in the xref:manual/configuration.adoc#log4j2.configurationAuthorizationProvider[log4j2.configurationAuthorizationProvider] system property, in `log4j2.component.properties` or in Spring's `bootstrap.yml` using either the `log4j2.authorizationProvider` key or with the key `logging.auth.authorizationProvider`.
Review Comment:
Neither do I. :wink:
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587650201
##########
src/site/antora/modules/ROOT/pages/manual/async.adoc:
##########
@@ -363,87 +348,95 @@ 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: All system properties were renamed into a more consistent style in
-Log4j 2.10. All old property names are still supported which are
-documented xref:manual/configuration.adoc#SystemProperties[here].
-
[[SysPropsMixedSync-Async]]
.System Properties to configure mixed asynchronous and normal loggers
-[cols="5m,2,10a",options="header"]
+[cols="1,1,5"]
|===
-|System Property |Default Value |Description
+h| Java Property
-|log4j2.asyncLoggerConfigExceptionHandler
-|`default handler`
-|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.
+(Environment Variable)
+h| Default Value
+h| Description
-If not specified, the default exception handler will print a message and
+| [[log4j2.asyncLoggerConfigExceptionHandler]]`log4j2.asyncLoggerConfig{zwsp}ExceptionHandler`
+
+(`LOG4J_ASYNC_LOGGER_CONFIG_{zwsp}EXCEPTION_HANDLER`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerConfigDefaultExceptionHandler[AsyncLoggerConfig{zwsp}DefaultExceptionHandler]
+|
+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.
+
+The default exception handler will print a message and
stack trace to the standard error output stream.
-|log4j2.asyncLoggerConfigRingBufferSize
-|256 * 1024
-|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 behavious
-is determined by the
-link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy.html[AsyncQueueFullPolicy].
-
-|[[asyncLoggerConfigWaitStrategy]]log4j2.asyncLoggerConfigWaitStrategy
-|`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.asyncLoggerConfigTimeout
-|`10`
-|Timeout in milliseconds of `TimeoutBlockingWaitStrategy`. See
-link:#asyncLoggerConfigWaitStrategy[WaitStrategy System Property] for details.
+| [[log4j2.asyncLoggerConfigRingBufferSize]]`log4j2.asyncLoggerConfig{zwsp}RingBufferSize`
+
+(`LOG4J_ASYNC_LOGGER_CONFIG_{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].
+
+| [[log4j2.asyncLoggerConfigWaitStrategy]]`log4j2.asyncLoggerConfig{zwsp}WaitStrategy`
+
+(`LOG4J_ASYNC_LOGGER_CONFIG_{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.asyncLoggerConfigTimeout>>)
+
+* `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.asyncLoggerConfigRetries>> and <<log4j2.asyncLoggerConfigSleepTimeNs>>).
+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:
Fixed in 46550d21f7cf4736bd0c4bcc88713e5bf4f981be
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz merged PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "rgoers (via GitHub)" <gi...@apache.org>.
rgoers commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587134732
##########
src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc:
##########
@@ -122,67 +126,9 @@ logging:
Note that Log4j currently does not directly support encrypting the password.
However, Log4j does use Spring's standard APIs to access properties in the Spring configuration so any customizations made to Spring's property handling would apply to the properties Log4j uses as well.
-If more extensive authentication is required an `AuthorizationProvider` can be implemented and the fully qualified class name in the `log4j2.authorizationProvider` system property, in log4j2.component.properties or in Spring's bootstrap.yml using either the `log4j2.authorizationProvider` key or with the key `logging.auth.authorizationProvider`.
+If more extensive authentication is required an `AuthorizationProvider` can be implemented and the fully qualified class name in the xref:manual/configuration.adoc#log4j2.configurationAuthorizationProvider[log4j2.configurationAuthorizationProvider] system property, in `log4j2.component.properties` or in Spring's `bootstrap.yml` using either the `log4j2.authorizationProvider` key or with the key `logging.auth.authorizationProvider`.
Review Comment:
That is because it is missing a few words. It should read "If more extensive authentication is required an `AuthorizationProvider` can be implemented and the fully qualified class name should be specified in the xref:manual/configuration.adoc#log4j2.configurationAuthorizationProvider[log4j2.configurationAuthorizationProvider] system property, in `log4j2.component.properties` or in Spring's `bootstrap.yml` using either the `log4j2.authorizationProvider` key or with the key `logging.auth.authorizationProvider`."
That said, this is one of thing I am not crazy about the design of. I would prefer that the AuthorizationProvider be injected with the DI system.
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587662670
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -127,9 +127,9 @@ Note the `2` in the file name!
(See xref:manual/configuration.adoc[the Configuration page] for more details.)
. Increase the logging verbosity of the internal status logger: +
-`-Dlog4j2.statusLoggerLevel=TRACE`
+`-Dxref:manual/configuration.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel]=TRACE`
-. Enable all internal debug logging: `-Dlog4j2.debug`.
+. Enable all internal debug logging: `-Dxref:manual/configuration.adoc#log4j2.debug[log4j2.debug]`.
Review Comment:
I reverted the changes in 928d23bfdb70b3f346856fc7c12ffcf6bfb0d196
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587647286
##########
src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc:
##########
@@ -122,67 +126,9 @@ logging:
Note that Log4j currently does not directly support encrypting the password.
However, Log4j does use Spring's standard APIs to access properties in the Spring configuration so any customizations made to Spring's property handling would apply to the properties Log4j uses as well.
-If more extensive authentication is required an `AuthorizationProvider` can be implemented and the fully qualified class name in the `log4j2.authorizationProvider` system property, in log4j2.component.properties or in Spring's bootstrap.yml using either the `log4j2.authorizationProvider` key or with the key `logging.auth.authorizationProvider`.
+If more extensive authentication is required an `AuthorizationProvider` can be implemented and the fully qualified class name in the xref:manual/configuration.adoc#log4j2.configurationAuthorizationProvider[log4j2.configurationAuthorizationProvider] system property, in `log4j2.component.properties` or in Spring's `bootstrap.yml` using either the `log4j2.authorizationProvider` key or with the key `logging.auth.authorizationProvider`.
Review Comment:
@rgoers, thanks.
Fixed in 928d23bfdb70b3f346856fc7c12ffcf6bfb0d196
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587646381
##########
src/site/antora/modules/ROOT/pages/faq.adoc:
##########
@@ -32,7 +32,7 @@ Log4j 2 and onwards use `log4j2.xml`.
====
You can also specify the full path of the configuration file using a system property: +
-`-Dlog4j2.configurationFile=/path/to/log4j2.xml`
+`-Dxref:manual/configuration.adoc#log4j2.configurationFile[log4j2.configurationFile]=/path/to/log4j2.xml`
Review Comment:
Fixed in 928d23bfdb70b3f346856fc7c12ffcf6bfb0d196
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1586704481
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
Review Comment:
Since we are not breaking `Configuration properties` into their own file, I prefer to keep the same fragment identifier as the current site uses.
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1586115098
##########
src/site/antora/modules/ROOT/pages/manual/configuration.adoc:
##########
Review Comment:
That's the plan.
The same way the documentation of "Property Sources" ended up at the end of configuration properties, "Arbiters" will end up at the end of the documentation of the "Configuration File".
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1586825825
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
Review Comment:
Sounds good to me.
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587661639
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
Review Comment:
Fixed in 4c0930a555eed5678ac22b079ed693c6e669597e
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587699370
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
+| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates.
+
+| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()]
+| Sets the timezone id used by status logger. See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html[ZoneId] for the accepted formats.
+
+|===
+
+=== Simple logger
+
+The simple logger implementation contained in `log4j-api` can be configured using these properties:
+
+.Simple logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.simplelogLevel]]`log4j2.simplelogLevel`
+
+(`LOG4J_SIMPLELOG_LEVEL`)
+| ERROR
+| Default level for new logger instances.
+
+| [[log4j2.simplelog.loggerName.level]]`log4j2.simplelog.<loggerName>.level`
+
+(`LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL`)
+| value of <<log4j2.simplelogLevel>>
+| Log level for a logger instance named `<loggerName>`.
+
+| [[log4j2.simplelogShowContextMap]]`log4j2.simplelogShowContextMap`
+
+(`LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP`)
+| false
+| If `true`, the full thread context map is included in each log message.
+
+| [[log4j2.simplelogShowlogname]]`log4j2.simplelogShowlogname`
+
+(`LOG4J_SIMPLELOG_SHOWLOGNAME`)
+| false
+| If `true`, the logger name is included in each log message.
+
+| [[log4j2.simplelogShowShortLogname]]`log4j2.simplelogShowShortLogname`
+
+(`LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME`)
+| true
+| If `true`, only the last component of a logger name is included in each log message.
+
+| [[log4j2.simplelogShowdatetime]]`log4j2.simplelogShowdatetime`
+
+(`LOG4J_SIMPLELOG_SHOWDATETIME`)
+| false
+| If `true`, a timestamp is included in each log message.
+
+| [[log4j2.simplelogDateTimeFormat]]`log4j2.simplelogDateTimeFormat`
+
+(`LOG4J_SIMPLELOG_DATE_TIME_FORMAT`)
+| `yyyy/MM/dd HH:mm:ss:SSS zzz`
+| Date-time format to use. Ignored if <<log4j2.simplelogShowdatetime>> is `false`.
+
+| [[log4j2.simplelogLogFile]]`log4j2.simplelogLogFile`
+
+(`LOG4J_SIMPLELOG_LOG_FILE`)
+| System.err
+a| Specifies the output stream used by all loggers:
+
+* `System.err` logs to the standard error output stream,
+* `System.out` logs to the standard output stream,
+* any other value is interpreted as a file name.
+
+|===
+
+[#simple-logger-thread-context]
+=== Thread context (Simple Logger)
+
+The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
+
+[WARNING]
+====
+These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API.
+
+The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
+
+The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
+====
+
+.Thread context configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableThreadContext]]`log4j2.disableThreadContext`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT`)
+| false
+| If `true`, the `ThreadContext` stack and map are disabled.
+
+| [[log4j2.disableThreadContextStack]]`log4j2.disableThreadContextStack`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_STACK`)
+| false
+| If `true`, the `ThreadContext` stack is disabled.
+
+| [[log4j2.disableThreadContextMap]]`log4j2.disableThreadContextMap`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_MAP`)
+| false
+| If `true`, the `ThreadContext` map is disabled.
+
+| [[log4j2.threadContextMap]]`log4j2.threadContextMap`
+
+(`LOG4J_THREAD_CONTEXT_MAP`)
+| `WebApp`
+
+(GC-free mode: `CopyOnWrite`)
+a| Fully specified class name of a custom `ThreadContextMap` implementation class or one of the predefined constants:
+
+* `NoOp`: to disable the thread context,
+* `WebApp`: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks,
+* `CopyOnWrite`: a copy-on-write implementation,
+* `GarbageFree`: a garbage-free implementation.
+
+| [[isThreadContextMapInheritable]]`log4j2.isThreadContextMapInheritable`
+
+(`LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`)
+| false
+| If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
+
+| [[log4j2.garbagefreeThreadContextMap]]`log4j2.garbagefreeThreadContextMap`
+
+(`LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP`)
+| false
+| If set to `true` selects a garbage-free thread context map implementation.
+Requires <<log4j2.enableThreadlocals>> to be also `true`.
+
+|===
+
+== Log4j Core
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration_new.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
+
+=== Async components
+
+The behavior of all three async components (`AsyncLogger`, `AsyncLoggerConfig` and `AsyncAppender`) can be tuned using these properties:
+
+.Common async component configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.formatMsgAsync]]`log4j2.formatMsgAsync`
+
+(`LOG4J_FORMAT_MSG_ASYNC`)
+| false
+| If `false`, Log4j will make sure the message is formatted in the caller thread, otherwise the formatting will occur on the asynchronous thread.
+
+**Remark**: messages annotated with link:../javadoc/log4j-api/org/apache/logging/log4j/message/AsynchronouslyFormattable[AsynchronouslyFormattable] will be formatted on the async thread regardless of this setting.
+
+| [[log4j2.asyncQueueFullPolicy]]`log4j2.asyncQueueFullPolicy`
+
+(`LOG4J_ASYNC_QUEUE_FULL_POLICY`)
+| `Default`
+a| Determines the link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy[AsyncQueueFullPolicy] to use when the underlying async component cannot keep up with the logging rate and the queue is filling up.
+
+It accepts the following values:
+
+* `Default`: blocks the calling thread until the event can be added to the queue.
+
+* `Discard`: when the queue is full, it drops the events whose level is equal or less than the threshold level (see <<log4j2.discardThreshold>>).
+
+* the fully qualified class name of a custom implementation
+
+| [[log4j2.discardThreshold]]`log4j2.discardThreshold`
+
+(`LOG4J_DISCARD_THRESHOLD`)
+| `INFO`
+| Determines the threshold level used by a `Discard` queue full policy.
+Log events whose level is equal or less specific than the threshold level will be discarded during a queue full event.
+See also <<log4j2.asyncQueueFullPolicy>>.
+
+|===
+
+==== `AsyncLogger`
+
+Additional properties supported by `AsyncLogger` are documented in the xref:manual/async.adoc#SysPropsAllAsync[System Properties to configure all asynchronous loggers] table.
+
+==== `AsyncLoggerConfig`
+
+Additional properties supported by `AsyncLoggerConfig` are documented in the xref:manual/async.adoc#SysPropsMixedSync-Async[System Properties to configure mixed asynchronous and normal loggers] table.
+
+=== Context selector
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ContextSelector[ContextSelector] component specifies the strategy used by Log4j to create new logger contexts.
+The choice of `ContextSelector` determines in particular:
+
+* how loggers are divided among logger contexts.
+See xref:manual/logsep.adoc[Log Separation] for details.
+
+* the `Logger` implementation used by Log4j Core.
+See xref:manual/async.adoc[Async Logging] as an example of this usage.
+
+.Context selector configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.contextSelector]]`log4j2.contextSelector`
+
+(`LOG4J_CONTEXT_SELECTOR`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[ClassLoaderContextSelector]
+a|
+Specifies the fully qualified class name of the `ContextSelector` implementation to use.
+
+The implementations available by default are:
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/BasicContextSelector[org.apache.logging.log4j
+.core.selector.BasicContextSelector]: creates a single logger context and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/BasicAsyncLoggerContextSelector[org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector]: creates a single logger context and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[org.apache.logging.log4j.core.selector.ClassLoaderContextSelector]: creates a separate logger context per classloader and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector[org.apache.logging.log4j.core.async.AsyncLoggerContextSelector]: creates a separate logger context per classloader and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/osgi/BundleContextSelector[org.apache.logging.log4j.core.osgi.BundleContextSelector]: creates a separate logger context per OSGi bundle and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/JndiContextSelector[org.apache.logging.log4j.core.selector.JndiContextSelector]: creates loggers contexts based on a JNDI lookup and synchronous loggers.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application]] for details.
+
+|===
+
+=== Configuration factory
+
+Since configuration factories are used to parse the configuration file, they can **only** be configured through global configuration properties.
+
+[WARNING]
+====
+Log4j Core supports both local and remote configuration files.
+If a remote configuration file is used, its transport must be secured.
+See <<transport-security>> for details.
+====
+
+.Configuration factory properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationFactory]]`log4j2.configurationFactory`
+
+(`LOG4J_CONFIGURATION_FACTORY`)
+|
+|
+Specifies the fully qualified class name of the **preferred** link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory[ConfigurationFactory] to use.
+
+Log4j will attempt to use the provided configuration factory before any other factory implementation.
+
+| [[log4j2.configurationFile]]`log4j2.configurationFile`
+
+(`LOG4J_CONFIGURATION_FILE`)
+| xref:manual/configuration.adoc#AutomaticConfiguration[automatically detected]
+a|
+Specifies a comma-separated list of URIs or file paths to Log4j 2 configuration files.
+
+If a relative URL is provided, it is interpreted as:
+
+* path to a file, if the file exists,
+* a classpath resource otherwise.
+
+See also xref:manual/configuration.adoc#AutomaticConfiguration[Automatic Configuration].
+
+| [[log4j2.level]]`log4j2.level`
+
+(`LOG4J_LEVEL`)
+| `ERROR`
+a|
+Specifies the level of the root logger if:
+
+* the default configuration is used,
+
+* or the configuration file does not specify a level for the root logger.
+
+| [[log4j2.mergeStrategy]]`log4j2.mergeStrategy`
+
+(`LOG4J_MERGE_STRATEGY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/DefaultMergeStrategy[DefaultMergeStrategy]
+|
+Specifies the fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/MergeStrategy[MergeStrategy] implementation used to merge multiple configuration files into one.
+
+|===
+
+=== Garbage Collection
+
+.GC properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+
+| [[log4j2.enableDirectEncoders]]`log4j2.enableDirectEncoders`
+
+(`LOG4J_ENABLE_DIRECT_ENCODERS`)
+| `true`
+|
+If `true`, garbage-aware layouts will directly encode log events into https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html[ByteBuffers] provided by appenders.
+
+This prevents the creation temporary multiple `String` and `char[]` temporary objects.
+
+| [[log4j2.initialReusableMsgSize]]`log4j2.initialReusableMsgSize`
+
+(`LOG4J_INITIAL_REUSABLE_MSG_SIZE`)
+| 128
+| In GC-free mode, this property determines the initial size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+| [[log4j2.maxReusableMsgSize]]`log4j2.maxReusableMsgSize`
+
+(`LOG4J_MAX_REUSABLE_MSG_SIZE`)
+| 518
+| In GC-free mode, this property determines the maximum size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+The default value allows is equal to `2 × (2 × log4j.initialReusableMsgSize + 2) + 2` and allows the
+``StringBuilder`` to be resized twice by the current JVM resize algorithm.
+
+| [[log4j2.layoutStringBuilderMaxSize]]`log4j2.layout{zwsp}StringBuilderMaxSize`
+
+(`LOG4J_LAYOUT_{zwsp}STRING_BUILDER_MAX_SIZE`)
+| 2048
+| This property determines the maximum size of the reusable ``StringBuilder``sused to format link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent[LogEvents].
+
+| [[log4j2.unboxRingbufferSize]]`log4j2.unboxRingbufferSize`
+
+(`LOG4J_UNBOX_RINGBUFFER_SIZE`)
+| 32
+|
+The link:../javadoc/log4j-api/org/apache/logging/log4j/util/Unbox[Unbox] utility class can be used by users to format primitive values without incurring in the boxing allocation cost.
+
+This property specifies the maximum number of primitive arguments to a log message that will be cached and usually does not need to be changed.
+
+|===
+
+=== JANSI
+
+If the https://fusesource.github.io/jansi/[JANSI] library is on the runtime classpath of the application, the following property can be used to control its usage:
+
+.JANSI properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.skipJansi]]`log4j2.skipJansi`
+
+(`LOG4J_SKIP_JANSI`)
+| `true`
+a| If the following conditions are satisfied:
+
+* Log4j runs on Windows,
+* this property is set to `false`,
+
+Log4j will use the JANSI library to color the output of the console appender.
+
+|===
+
+=== JNDI
+
+Due to the inherent security problems of https://docs.oracle.com/javase/tutorial/jndi/overview/[JNDI], its usage in Log4j is restricted to the `java:` protocol.
+
+Moreover, each JNDI usage must be **explicitly** enabled by the user through the following configuration properties.
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.enableJndiContextSelector]]`log4j2.enableJndiContextSelector`
+
+(`LOG4J_ENABLE_JNDI_CONTEXT_SELECTOR`)
+| `false`
+|
+When `true` the `JndiContextSelector` is enabled for the `java:` protocol.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application] for more details.
+
+| [[log4j2.enableJndiJdbc]]`log4j2.enableJndiJdbc`
+
+(`LOG4J_ENABLE_JNDI_JDBC`)
+| `false`
+| When `true`, a Log4j JDBC Appender can use JNDI to retrieve a https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[DataSource] using the `java:` protocol.
+
+| [[log4j2.enableJndiJms]]`log4j2.enableJndiJms`
+
+(`LOG4J_ENABLE_JNDI_JMS`)
+| `false`
+| When `true`, a Log4j JMS Appender can use JNDI to retrieve the necessary components using the `java:` protocol.
+
+| [[log4j2.enableJndiLookup]]`log4j2.enableJndiLookup`
+
+(`LOG4J_ENABLE_JNDI_LOOKUP`)
+| `false`
+| When `true`, the Log4j JNDI Lookup can use the `java:` protocol.
+
+|===
+
+=== JMX
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableJmx]]`log4j2.disableJmx`
+
+(`LOG4J_DISABLE_JMX`)
+| `true`
+|
+If `false`, Log4j configuration objects like ``LoggerContext``s, ``Appender``s, ``Logger``s, etc.
+will be instrumented with ``MBean``s and can be remotely monitored and managed.
+
+| [[log4j2.jmxNotifyAsync]]`log4j2.jmxNotifyAsync`
+
+(`LOG4J_JMX_NOTIFY_ASYNC`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true`, Log4j's JMX notifications are sent from a separate background thread, otherwise they are sent from the caller thread.
+
+|===
+
+[#log4j-core-thread-context]
+=== Thread context (Log4j Core)
+
+Log4j Core supports the same properties as Simple Logger for the configuration of the thread context.
+See <<simple-logger-thread-context>> for more details.
+
+[#transport-security]
+=== Transport security
+
+Since configuration files can be used to load arbitrary classes into a Log4j Core `Configuration`, users need to ensure that all the configuration elements come from trusted sources (cf. link:/security#threat-common-config-sources[Thread model] for more information).
+
+In order to protect the user Log4j disables the `http` URI scheme by default and provides several configuration options to ensure secure transport of configuration files:
+
+:jsse-default-keystores: https://docs.oracle.com/en/java/javase/21/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-7D9F43B8-AABF-4C5B-93E6-3AFB18B66150
+
+.Transport security properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationAllowedProtocols]]`log4j2.configuration{zwsp}AllowedProtocols`
+
+(`LOG4J_CONFIGURATION_{zwsp}ALLOWED_PROTOCOLS`)
+| file, https, jar
+|
+A comma separated list of URL protocols that may be used to load any kind of configuration source.
+
+To completely prevent accessing the configuration via the Java https://docs.oracle.com/javase/8/docs/api/java/net/URL.html[URL class] specify a value of `_none`.
+
+// TODO: What about 'jar:http:'?
+
+| [[log4j2.configurationAuthorizationProvider]]`log4j2.configuration{zwsp}AuthorizationProvider`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_PROVIDER`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/BasicAuthorizationProvider[BasicAuthorizationProvider]
+| The fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/AuthorizationProvider[AuthorizationProvider] implementation to use with `http` and `https` URL protocols.
+
+3+h| HTTP Basic authentication
+
+| [[log4j2.configurationAuthorizationEncoding]]`log4j2.configuration{zwsp}AuthorizationEncoding`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_ENCODING`)
+| UTF-8
+| The encoding used in Basic Authentication (cf. https://datatracker.ietf.org/doc/html/rfc7617[RFC 7617]).
+
+| [[log4j2.configurationPassword]]`log4j2.configurationPassword`
+
+(`LOG4J_CONFIGURATION_PASSWORD`)
+|
+| The password to use in HTTP Basic authentication.
+
+If used in conjunction with <<log4j2.configurationPasswordDecryptor>> the contents of this variable are
+interpreted by the decryptor.
+
+| [[log4j2.configurationPasswordDecryptor]]`log4j2.configuration{zwsp}PasswordDecryptor`
+
+(`LOG4J_CONFIGURATION_{zwsp}PASSWORD_DECRYPTOR`)
+|
+| Fully qualified class name of an implementation of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/PasswordDecryptor[PasswordDecryptor] to use for the value of the <<log4j2.configurationPassword>> property.
+
+By default, the literal value of the password is used.
+
+| [[log4j2.configurationUsername]]`log4j2.configurationUsername`
+
+(`LOG4J_CONFIGURATION_USERNAME`)
+|
+| The username used in HTTP Basic authentication.
+
+3+h| TLS server authentication properties
+
+| [[log4j2.trustStoreLocation]]`log4j2.trustStoreLocation`
+
+(`LOG4J_TRUST_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java trust store]
+| The location of the trust store.
+
+| [[log4j2.trustStorePassword]]`log4j2.trustStorePassword`
+
+(`LOG4J_TRUST_STORE_PASSWORD`)
+|
+| The password for the trust store.
+
+| [[log4j2.trustStorePasswordFile]]`log4j2.trustStore{zwsp}PasswordFile`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the trust store.
+
+| [[log4j2.trustStorePasswordEnvironmentVariable]]`log4j2.trustStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains password for the trust store.
+
+| [[log4j2.trustStoreType]]`log4j2.trustStoreType`
+
+(`LOG4J_TRUST_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.trustStoreKeyManagerFactoryAlgorithm]]`log4j2.trustStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_TRUST_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+| [[log4j2.sslVerifyHostName]]`log4j2.sslVerifyHostName`
+
+(`LOG4J_SSL_VERIFY_HOST_NAME`)
+| false
+| If `true` enables verification of the name of the TLS server.
+
+3+h| TLS client authentication properties
+
+| [[log4j2.keyStoreLocation]]`log4j2.keyStoreLocation`
+
+(`LOG4J_KEY_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java key store]
+| The location of the private key store.
+
+| [[log4j2.keyStorePassword]]`log4j2.keyStorePassword`
+
+(`LOG4J_KEY_STORE_PASSWORD`)
+|
+| The password for the private key store.
+
+| [[log4j2.keyStorePasswordFile]]`log4j2.keyStore{zwsp}PasswordFile`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the private key store.
+
+| [[log4j2.keyStorePasswordEnvironmentVariable]]`log4j2.keyStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains the password for the private key store.
+
+| [[log4j2.keyStoreType]]`log4j2.keyStoreType`
+
+(`LOG4J_KEY_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.keyStoreKeyManagerFactoryAlgorithm]]`log4j2.keyStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_KEY_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+|===
+
+=== Miscellaneous properties
+
+.Miscellaneous configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.clock]]`log4j2.clock`
+
+(`LOG4J_CLOCK`)
+| `SystemClock`
+a|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/Clock[Clock] implementation used to timestamp log events.
+
+The possible values are:
+
+* `SystemClock`: uses the best available system clock as time source.
+See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/Clock.html#systemDefaultZone--[Clock#systemDefaultZone] for details.
+
+* `SystemMillisClock`: same as `SystemClock`, but truncates the result to a millisecond.
+
+* `CachedClock`: uses a separate thread to update the timestamp value.
+See link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/CachedClock[JavaDoc] for details.
+
+* `CoarseCachedClock`: alternative implementation of `CachedClock` with a slightly lower precision.
+See link:..//javadoc/log4j-core/org/apache/logging/log4j/core/util/CoarseCachedClock[JavaDoc] for details.
+
+* the fully qualified name of a custom implementation.
+
+| [[log4j2.contextDataInjector]]`log4j2.contextDataInjector`
+
+(`LOG4J_CONTEXT_DATA_INJECTOR`)
+| depends on the `ThreadContextMap` implementation
+| Fully specified class name of a link:../javadoc/log4j-core/org/apache/logging/log4j/core/ContextDataInjector[ContextDataInjector] implementation.
+
+The default implementation uses all implementations of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ContextDataProvider[ContextDataProvider] registered with `ServiceLoader`.
+
+| [[log4j2.logEventFactory]]`log4j2.logEventFactory`
+
+(`LOG4J_LOG_EVENT_FACTORY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/DefaultLogEventFactory[DefaultLogEventFactory]
+
+(GC-free mode: link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/ReusableLogEventFactory[ReusableLogEventFactory])
+|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/LogEventFactory[LogEventFactory]
+implementation to use to create log events.
+
+| [[log4j2.shutdownHookEnabled]]`log4j2.shutdownHookEnabled`
+
+(`LOG4J_SHUTDOWN_HOOK_ENABLED`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true` a shutdown hook will be installed to stop all logger contexts when the system stops.
+
+| [[log4j2.shutdownCallbackRegistry]]`log4j2.shutdownCallbackRegistry`
+
+(`LOG4J_SHUTDOWN_CALLBACK_REGISTRY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/DefaultShutdownCallbackRegistry[DefaultShutdownCallbackRegistry]
+|
+The fully qualified class name of a link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry[ShutdownCallbackRegistry] implementation.
+Integrators can use this to customize the shutdown order of the JVM.
+
+The default implementation executes all shutdown actions in a separate `Thread` registered through https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#addShutdownHook-java.lang.Thread-[Runtime#addShutdownHook()].
+
+
+| [[log4j2.uuidSequence]]`log4j2.uuidSequence`
+
+(`LOG4J_UUID_SEQUENCE`)
+| 0
+|
+Provides a `long` see to the UUID generator used by the `%uuid` pattern converter.
+
+Can be used to assure uniqueness of UUIDs generated by multiple JVMs on the same machine.
Review Comment:
This way:
- users can be sure to find all the configuration properties on this page, just like Spring Boot users can consult [this page](https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html),
- developers can see what a magnificent set of properties we have, which should "encourage" them to add new properties.
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587672912
##########
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.
+
+**Remark**: Since JRE 8u102 the `Thread.getName()` method does not allocate a new object.
Review Comment:
Fixed in 3507a9ae28e916e28e0409cd1a46796e2df022f5
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587659435
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
+| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates.
+
+| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()]
+| Sets the timezone id used by status logger. See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html[ZoneId] for the accepted formats.
+
+|===
+
+=== Simple logger
+
+The simple logger implementation contained in `log4j-api` can be configured using these properties:
+
+.Simple logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.simplelogLevel]]`log4j2.simplelogLevel`
+
+(`LOG4J_SIMPLELOG_LEVEL`)
+| ERROR
+| Default level for new logger instances.
+
+| [[log4j2.simplelog.loggerName.level]]`log4j2.simplelog.<loggerName>.level`
+
+(`LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL`)
+| value of <<log4j2.simplelogLevel>>
+| Log level for a logger instance named `<loggerName>`.
+
+| [[log4j2.simplelogShowContextMap]]`log4j2.simplelogShowContextMap`
+
+(`LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP`)
+| false
+| If `true`, the full thread context map is included in each log message.
+
+| [[log4j2.simplelogShowlogname]]`log4j2.simplelogShowlogname`
+
+(`LOG4J_SIMPLELOG_SHOWLOGNAME`)
+| false
+| If `true`, the logger name is included in each log message.
+
+| [[log4j2.simplelogShowShortLogname]]`log4j2.simplelogShowShortLogname`
+
+(`LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME`)
+| true
+| If `true`, only the last component of a logger name is included in each log message.
+
+| [[log4j2.simplelogShowdatetime]]`log4j2.simplelogShowdatetime`
+
+(`LOG4J_SIMPLELOG_SHOWDATETIME`)
+| false
+| If `true`, a timestamp is included in each log message.
+
+| [[log4j2.simplelogDateTimeFormat]]`log4j2.simplelogDateTimeFormat`
+
+(`LOG4J_SIMPLELOG_DATE_TIME_FORMAT`)
+| `yyyy/MM/dd HH:mm:ss:SSS zzz`
+| Date-time format to use. Ignored if <<log4j2.simplelogShowdatetime>> is `false`.
+
+| [[log4j2.simplelogLogFile]]`log4j2.simplelogLogFile`
+
+(`LOG4J_SIMPLELOG_LOG_FILE`)
+| System.err
+a| Specifies the output stream used by all loggers:
+
+* `System.err` logs to the standard error output stream,
+* `System.out` logs to the standard output stream,
+* any other value is interpreted as a file name.
+
+|===
+
+[#simple-logger-thread-context]
+=== Thread context (Simple Logger)
+
+The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
+
+[WARNING]
+====
+These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API.
+
+The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
+
+The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
+====
+
+.Thread context configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableThreadContext]]`log4j2.disableThreadContext`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT`)
+| false
+| If `true`, the `ThreadContext` stack and map are disabled.
+
+| [[log4j2.disableThreadContextStack]]`log4j2.disableThreadContextStack`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_STACK`)
+| false
+| If `true`, the `ThreadContext` stack is disabled.
+
+| [[log4j2.disableThreadContextMap]]`log4j2.disableThreadContextMap`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_MAP`)
+| false
+| If `true`, the `ThreadContext` map is disabled.
+
+| [[log4j2.threadContextMap]]`log4j2.threadContextMap`
+
+(`LOG4J_THREAD_CONTEXT_MAP`)
+| `WebApp`
+
+(GC-free mode: `CopyOnWrite`)
+a| Fully specified class name of a custom `ThreadContextMap` implementation class or one of the predefined constants:
+
+* `NoOp`: to disable the thread context,
+* `WebApp`: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks,
+* `CopyOnWrite`: a copy-on-write implementation,
+* `GarbageFree`: a garbage-free implementation.
+
+| [[isThreadContextMapInheritable]]`log4j2.isThreadContextMapInheritable`
+
+(`LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`)
+| false
+| If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
+
+| [[log4j2.garbagefreeThreadContextMap]]`log4j2.garbagefreeThreadContextMap`
+
+(`LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP`)
+| false
+| If set to `true` selects a garbage-free thread context map implementation.
+Requires <<log4j2.enableThreadlocals>> to be also `true`.
+
+|===
+
+== Log4j Core
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration_new.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
+
+=== Async components
Review Comment:
Fixed in 4c0930a555eed5678ac22b079ed693c6e669597e
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#issuecomment-2090555193
@vy,
I reformatted the tables as sections. Can you take a look at this again?
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587665055
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
+| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates.
+
+| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()]
+| Sets the timezone id used by status logger. See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html[ZoneId] for the accepted formats.
+
+|===
+
+=== Simple logger
+
+The simple logger implementation contained in `log4j-api` can be configured using these properties:
+
+.Simple logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.simplelogLevel]]`log4j2.simplelogLevel`
+
+(`LOG4J_SIMPLELOG_LEVEL`)
+| ERROR
+| Default level for new logger instances.
+
+| [[log4j2.simplelog.loggerName.level]]`log4j2.simplelog.<loggerName>.level`
+
+(`LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL`)
+| value of <<log4j2.simplelogLevel>>
+| Log level for a logger instance named `<loggerName>`.
+
+| [[log4j2.simplelogShowContextMap]]`log4j2.simplelogShowContextMap`
+
+(`LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP`)
+| false
+| If `true`, the full thread context map is included in each log message.
+
+| [[log4j2.simplelogShowlogname]]`log4j2.simplelogShowlogname`
+
+(`LOG4J_SIMPLELOG_SHOWLOGNAME`)
+| false
+| If `true`, the logger name is included in each log message.
+
+| [[log4j2.simplelogShowShortLogname]]`log4j2.simplelogShowShortLogname`
+
+(`LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME`)
+| true
+| If `true`, only the last component of a logger name is included in each log message.
+
+| [[log4j2.simplelogShowdatetime]]`log4j2.simplelogShowdatetime`
+
+(`LOG4J_SIMPLELOG_SHOWDATETIME`)
+| false
+| If `true`, a timestamp is included in each log message.
+
+| [[log4j2.simplelogDateTimeFormat]]`log4j2.simplelogDateTimeFormat`
+
+(`LOG4J_SIMPLELOG_DATE_TIME_FORMAT`)
+| `yyyy/MM/dd HH:mm:ss:SSS zzz`
+| Date-time format to use. Ignored if <<log4j2.simplelogShowdatetime>> is `false`.
+
+| [[log4j2.simplelogLogFile]]`log4j2.simplelogLogFile`
+
+(`LOG4J_SIMPLELOG_LOG_FILE`)
+| System.err
+a| Specifies the output stream used by all loggers:
+
+* `System.err` logs to the standard error output stream,
+* `System.out` logs to the standard output stream,
+* any other value is interpreted as a file name.
+
+|===
+
+[#simple-logger-thread-context]
+=== Thread context (Simple Logger)
+
+The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
+
+[WARNING]
+====
+These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API.
+
+The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
+
+The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
+====
+
+.Thread context configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableThreadContext]]`log4j2.disableThreadContext`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT`)
+| false
+| If `true`, the `ThreadContext` stack and map are disabled.
+
+| [[log4j2.disableThreadContextStack]]`log4j2.disableThreadContextStack`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_STACK`)
+| false
+| If `true`, the `ThreadContext` stack is disabled.
+
+| [[log4j2.disableThreadContextMap]]`log4j2.disableThreadContextMap`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_MAP`)
+| false
+| If `true`, the `ThreadContext` map is disabled.
+
+| [[log4j2.threadContextMap]]`log4j2.threadContextMap`
+
+(`LOG4J_THREAD_CONTEXT_MAP`)
+| `WebApp`
+
+(GC-free mode: `CopyOnWrite`)
+a| Fully specified class name of a custom `ThreadContextMap` implementation class or one of the predefined constants:
+
+* `NoOp`: to disable the thread context,
+* `WebApp`: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks,
+* `CopyOnWrite`: a copy-on-write implementation,
+* `GarbageFree`: a garbage-free implementation.
+
+| [[isThreadContextMapInheritable]]`log4j2.isThreadContextMapInheritable`
+
+(`LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`)
+| false
+| If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
+
+| [[log4j2.garbagefreeThreadContextMap]]`log4j2.garbagefreeThreadContextMap`
+
+(`LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP`)
+| false
+| If set to `true` selects a garbage-free thread context map implementation.
+Requires <<log4j2.enableThreadlocals>> to be also `true`.
+
+|===
+
+== Log4j Core
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration_new.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
+
+=== Async components
+
+The behavior of all three async components (`AsyncLogger`, `AsyncLoggerConfig` and `AsyncAppender`) can be tuned using these properties:
+
+.Common async component configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.formatMsgAsync]]`log4j2.formatMsgAsync`
+
+(`LOG4J_FORMAT_MSG_ASYNC`)
+| false
+| If `false`, Log4j will make sure the message is formatted in the caller thread, otherwise the formatting will occur on the asynchronous thread.
+
+**Remark**: messages annotated with link:../javadoc/log4j-api/org/apache/logging/log4j/message/AsynchronouslyFormattable[AsynchronouslyFormattable] will be formatted on the async thread regardless of this setting.
+
+| [[log4j2.asyncQueueFullPolicy]]`log4j2.asyncQueueFullPolicy`
+
+(`LOG4J_ASYNC_QUEUE_FULL_POLICY`)
+| `Default`
+a| Determines the link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy[AsyncQueueFullPolicy] to use when the underlying async component cannot keep up with the logging rate and the queue is filling up.
+
+It accepts the following values:
+
+* `Default`: blocks the calling thread until the event can be added to the queue.
+
+* `Discard`: when the queue is full, it drops the events whose level is equal or less than the threshold level (see <<log4j2.discardThreshold>>).
+
+* the fully qualified class name of a custom implementation
+
+| [[log4j2.discardThreshold]]`log4j2.discardThreshold`
+
+(`LOG4J_DISCARD_THRESHOLD`)
+| `INFO`
+| Determines the threshold level used by a `Discard` queue full policy.
+Log events whose level is equal or less specific than the threshold level will be discarded during a queue full event.
+See also <<log4j2.asyncQueueFullPolicy>>.
+
+|===
+
+==== `AsyncLogger`
+
+Additional properties supported by `AsyncLogger` are documented in the xref:manual/async.adoc#SysPropsAllAsync[System Properties to configure all asynchronous loggers] table.
+
+==== `AsyncLoggerConfig`
+
+Additional properties supported by `AsyncLoggerConfig` are documented in the xref:manual/async.adoc#SysPropsMixedSync-Async[System Properties to configure mixed asynchronous and normal loggers] table.
+
+=== Context selector
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ContextSelector[ContextSelector] component specifies the strategy used by Log4j to create new logger contexts.
+The choice of `ContextSelector` determines in particular:
+
+* how loggers are divided among logger contexts.
+See xref:manual/logsep.adoc[Log Separation] for details.
+
+* the `Logger` implementation used by Log4j Core.
+See xref:manual/async.adoc[Async Logging] as an example of this usage.
+
+.Context selector configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.contextSelector]]`log4j2.contextSelector`
+
+(`LOG4J_CONTEXT_SELECTOR`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[ClassLoaderContextSelector]
+a|
+Specifies the fully qualified class name of the `ContextSelector` implementation to use.
+
+The implementations available by default are:
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/BasicContextSelector[org.apache.logging.log4j
+.core.selector.BasicContextSelector]: creates a single logger context and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/BasicAsyncLoggerContextSelector[org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector]: creates a single logger context and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[org.apache.logging.log4j.core.selector.ClassLoaderContextSelector]: creates a separate logger context per classloader and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector[org.apache.logging.log4j.core.async.AsyncLoggerContextSelector]: creates a separate logger context per classloader and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/osgi/BundleContextSelector[org.apache.logging.log4j.core.osgi.BundleContextSelector]: creates a separate logger context per OSGi bundle and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/JndiContextSelector[org.apache.logging.log4j.core.selector.JndiContextSelector]: creates loggers contexts based on a JNDI lookup and synchronous loggers.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application]] for details.
+
+|===
+
+=== Configuration factory
+
+Since configuration factories are used to parse the configuration file, they can **only** be configured through global configuration properties.
+
+[WARNING]
+====
+Log4j Core supports both local and remote configuration files.
+If a remote configuration file is used, its transport must be secured.
+See <<transport-security>> for details.
+====
+
+.Configuration factory properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationFactory]]`log4j2.configurationFactory`
+
+(`LOG4J_CONFIGURATION_FACTORY`)
+|
+|
+Specifies the fully qualified class name of the **preferred** link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory[ConfigurationFactory] to use.
+
+Log4j will attempt to use the provided configuration factory before any other factory implementation.
+
+| [[log4j2.configurationFile]]`log4j2.configurationFile`
+
+(`LOG4J_CONFIGURATION_FILE`)
+| xref:manual/configuration.adoc#AutomaticConfiguration[automatically detected]
+a|
+Specifies a comma-separated list of URIs or file paths to Log4j 2 configuration files.
+
+If a relative URL is provided, it is interpreted as:
+
+* path to a file, if the file exists,
+* a classpath resource otherwise.
+
+See also xref:manual/configuration.adoc#AutomaticConfiguration[Automatic Configuration].
+
+| [[log4j2.level]]`log4j2.level`
+
+(`LOG4J_LEVEL`)
+| `ERROR`
+a|
+Specifies the level of the root logger if:
+
+* the default configuration is used,
+
+* or the configuration file does not specify a level for the root logger.
+
+| [[log4j2.mergeStrategy]]`log4j2.mergeStrategy`
+
+(`LOG4J_MERGE_STRATEGY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/DefaultMergeStrategy[DefaultMergeStrategy]
+|
+Specifies the fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/MergeStrategy[MergeStrategy] implementation used to merge multiple configuration files into one.
+
+|===
+
+=== Garbage Collection
+
+.GC properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+
+| [[log4j2.enableDirectEncoders]]`log4j2.enableDirectEncoders`
+
+(`LOG4J_ENABLE_DIRECT_ENCODERS`)
+| `true`
+|
+If `true`, garbage-aware layouts will directly encode log events into https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html[ByteBuffers] provided by appenders.
+
+This prevents the creation temporary multiple `String` and `char[]` temporary objects.
+
+| [[log4j2.initialReusableMsgSize]]`log4j2.initialReusableMsgSize`
+
+(`LOG4J_INITIAL_REUSABLE_MSG_SIZE`)
+| 128
+| In GC-free mode, this property determines the initial size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+| [[log4j2.maxReusableMsgSize]]`log4j2.maxReusableMsgSize`
+
+(`LOG4J_MAX_REUSABLE_MSG_SIZE`)
+| 518
+| In GC-free mode, this property determines the maximum size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+The default value allows is equal to `2 × (2 × log4j.initialReusableMsgSize + 2) + 2` and allows the
+``StringBuilder`` to be resized twice by the current JVM resize algorithm.
+
+| [[log4j2.layoutStringBuilderMaxSize]]`log4j2.layout{zwsp}StringBuilderMaxSize`
+
+(`LOG4J_LAYOUT_{zwsp}STRING_BUILDER_MAX_SIZE`)
+| 2048
+| This property determines the maximum size of the reusable ``StringBuilder``sused to format link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent[LogEvents].
+
+| [[log4j2.unboxRingbufferSize]]`log4j2.unboxRingbufferSize`
+
+(`LOG4J_UNBOX_RINGBUFFER_SIZE`)
+| 32
+|
+The link:../javadoc/log4j-api/org/apache/logging/log4j/util/Unbox[Unbox] utility class can be used by users to format primitive values without incurring in the boxing allocation cost.
+
+This property specifies the maximum number of primitive arguments to a log message that will be cached and usually does not need to be changed.
+
+|===
+
+=== JANSI
+
+If the https://fusesource.github.io/jansi/[JANSI] library is on the runtime classpath of the application, the following property can be used to control its usage:
+
+.JANSI properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.skipJansi]]`log4j2.skipJansi`
+
+(`LOG4J_SKIP_JANSI`)
+| `true`
+a| If the following conditions are satisfied:
+
+* Log4j runs on Windows,
+* this property is set to `false`,
+
+Log4j will use the JANSI library to color the output of the console appender.
+
+|===
+
+=== JNDI
+
+Due to the inherent security problems of https://docs.oracle.com/javase/tutorial/jndi/overview/[JNDI], its usage in Log4j is restricted to the `java:` protocol.
+
+Moreover, each JNDI usage must be **explicitly** enabled by the user through the following configuration properties.
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.enableJndiContextSelector]]`log4j2.enableJndiContextSelector`
+
+(`LOG4J_ENABLE_JNDI_CONTEXT_SELECTOR`)
+| `false`
+|
+When `true` the `JndiContextSelector` is enabled for the `java:` protocol.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application] for more details.
+
+| [[log4j2.enableJndiJdbc]]`log4j2.enableJndiJdbc`
+
+(`LOG4J_ENABLE_JNDI_JDBC`)
+| `false`
+| When `true`, a Log4j JDBC Appender can use JNDI to retrieve a https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[DataSource] using the `java:` protocol.
+
+| [[log4j2.enableJndiJms]]`log4j2.enableJndiJms`
+
+(`LOG4J_ENABLE_JNDI_JMS`)
+| `false`
+| When `true`, a Log4j JMS Appender can use JNDI to retrieve the necessary components using the `java:` protocol.
+
+| [[log4j2.enableJndiLookup]]`log4j2.enableJndiLookup`
+
+(`LOG4J_ENABLE_JNDI_LOOKUP`)
+| `false`
+| When `true`, the Log4j JNDI Lookup can use the `java:` protocol.
+
+|===
+
+=== JMX
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableJmx]]`log4j2.disableJmx`
+
+(`LOG4J_DISABLE_JMX`)
+| `true`
+|
+If `false`, Log4j configuration objects like ``LoggerContext``s, ``Appender``s, ``Logger``s, etc.
+will be instrumented with ``MBean``s and can be remotely monitored and managed.
+
+| [[log4j2.jmxNotifyAsync]]`log4j2.jmxNotifyAsync`
+
+(`LOG4J_JMX_NOTIFY_ASYNC`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true`, Log4j's JMX notifications are sent from a separate background thread, otherwise they are sent from the caller thread.
+
+|===
+
+[#log4j-core-thread-context]
+=== Thread context (Log4j Core)
+
+Log4j Core supports the same properties as Simple Logger for the configuration of the thread context.
+See <<simple-logger-thread-context>> for more details.
+
+[#transport-security]
+=== Transport security
+
+Since configuration files can be used to load arbitrary classes into a Log4j Core `Configuration`, users need to ensure that all the configuration elements come from trusted sources (cf. link:/security#threat-common-config-sources[Thread model] for more information).
+
+In order to protect the user Log4j disables the `http` URI scheme by default and provides several configuration options to ensure secure transport of configuration files:
+
+:jsse-default-keystores: https://docs.oracle.com/en/java/javase/21/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-7D9F43B8-AABF-4C5B-93E6-3AFB18B66150
+
+.Transport security properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationAllowedProtocols]]`log4j2.configuration{zwsp}AllowedProtocols`
+
+(`LOG4J_CONFIGURATION_{zwsp}ALLOWED_PROTOCOLS`)
+| file, https, jar
+|
+A comma separated list of URL protocols that may be used to load any kind of configuration source.
+
+To completely prevent accessing the configuration via the Java https://docs.oracle.com/javase/8/docs/api/java/net/URL.html[URL class] specify a value of `_none`.
+
+// TODO: What about 'jar:http:'?
+
+| [[log4j2.configurationAuthorizationProvider]]`log4j2.configuration{zwsp}AuthorizationProvider`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_PROVIDER`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/BasicAuthorizationProvider[BasicAuthorizationProvider]
+| The fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/AuthorizationProvider[AuthorizationProvider] implementation to use with `http` and `https` URL protocols.
+
+3+h| HTTP Basic authentication
+
+| [[log4j2.configurationAuthorizationEncoding]]`log4j2.configuration{zwsp}AuthorizationEncoding`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_ENCODING`)
+| UTF-8
+| The encoding used in Basic Authentication (cf. https://datatracker.ietf.org/doc/html/rfc7617[RFC 7617]).
+
+| [[log4j2.configurationPassword]]`log4j2.configurationPassword`
+
+(`LOG4J_CONFIGURATION_PASSWORD`)
+|
+| The password to use in HTTP Basic authentication.
+
+If used in conjunction with <<log4j2.configurationPasswordDecryptor>> the contents of this variable are
+interpreted by the decryptor.
+
+| [[log4j2.configurationPasswordDecryptor]]`log4j2.configuration{zwsp}PasswordDecryptor`
+
+(`LOG4J_CONFIGURATION_{zwsp}PASSWORD_DECRYPTOR`)
+|
+| Fully qualified class name of an implementation of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/PasswordDecryptor[PasswordDecryptor] to use for the value of the <<log4j2.configurationPassword>> property.
+
+By default, the literal value of the password is used.
+
+| [[log4j2.configurationUsername]]`log4j2.configurationUsername`
+
+(`LOG4J_CONFIGURATION_USERNAME`)
+|
+| The username used in HTTP Basic authentication.
+
+3+h| TLS server authentication properties
+
+| [[log4j2.trustStoreLocation]]`log4j2.trustStoreLocation`
+
+(`LOG4J_TRUST_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java trust store]
+| The location of the trust store.
+
+| [[log4j2.trustStorePassword]]`log4j2.trustStorePassword`
+
+(`LOG4J_TRUST_STORE_PASSWORD`)
+|
+| The password for the trust store.
+
+| [[log4j2.trustStorePasswordFile]]`log4j2.trustStore{zwsp}PasswordFile`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the trust store.
+
+| [[log4j2.trustStorePasswordEnvironmentVariable]]`log4j2.trustStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains password for the trust store.
+
+| [[log4j2.trustStoreType]]`log4j2.trustStoreType`
+
+(`LOG4J_TRUST_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.trustStoreKeyManagerFactoryAlgorithm]]`log4j2.trustStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_TRUST_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+| [[log4j2.sslVerifyHostName]]`log4j2.sslVerifyHostName`
+
+(`LOG4J_SSL_VERIFY_HOST_NAME`)
+| false
+| If `true` enables verification of the name of the TLS server.
+
+3+h| TLS client authentication properties
+
+| [[log4j2.keyStoreLocation]]`log4j2.keyStoreLocation`
+
+(`LOG4J_KEY_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java key store]
+| The location of the private key store.
+
+| [[log4j2.keyStorePassword]]`log4j2.keyStorePassword`
+
+(`LOG4J_KEY_STORE_PASSWORD`)
+|
+| The password for the private key store.
+
+| [[log4j2.keyStorePasswordFile]]`log4j2.keyStore{zwsp}PasswordFile`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the private key store.
+
+| [[log4j2.keyStorePasswordEnvironmentVariable]]`log4j2.keyStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains the password for the private key store.
+
+| [[log4j2.keyStoreType]]`log4j2.keyStoreType`
+
+(`LOG4J_KEY_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.keyStoreKeyManagerFactoryAlgorithm]]`log4j2.keyStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_KEY_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+|===
+
+=== Miscellaneous properties
+
+.Miscellaneous configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.clock]]`log4j2.clock`
+
+(`LOG4J_CLOCK`)
+| `SystemClock`
+a|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/Clock[Clock] implementation used to timestamp log events.
+
+The possible values are:
+
+* `SystemClock`: uses the best available system clock as time source.
+See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/Clock.html#systemDefaultZone--[Clock#systemDefaultZone] for details.
+
+* `SystemMillisClock`: same as `SystemClock`, but truncates the result to a millisecond.
+
+* `CachedClock`: uses a separate thread to update the timestamp value.
+See link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/CachedClock[JavaDoc] for details.
+
+* `CoarseCachedClock`: alternative implementation of `CachedClock` with a slightly lower precision.
+See link:..//javadoc/log4j-core/org/apache/logging/log4j/core/util/CoarseCachedClock[JavaDoc] for details.
+
+* the fully qualified name of a custom implementation.
+
+| [[log4j2.contextDataInjector]]`log4j2.contextDataInjector`
+
+(`LOG4J_CONTEXT_DATA_INJECTOR`)
+| depends on the `ThreadContextMap` implementation
+| Fully specified class name of a link:../javadoc/log4j-core/org/apache/logging/log4j/core/ContextDataInjector[ContextDataInjector] implementation.
+
+The default implementation uses all implementations of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ContextDataProvider[ContextDataProvider] registered with `ServiceLoader`.
+
+| [[log4j2.logEventFactory]]`log4j2.logEventFactory`
+
+(`LOG4J_LOG_EVENT_FACTORY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/DefaultLogEventFactory[DefaultLogEventFactory]
+
+(GC-free mode: link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/ReusableLogEventFactory[ReusableLogEventFactory])
+|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/LogEventFactory[LogEventFactory]
+implementation to use to create log events.
+
+| [[log4j2.shutdownHookEnabled]]`log4j2.shutdownHookEnabled`
+
+(`LOG4J_SHUTDOWN_HOOK_ENABLED`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true` a shutdown hook will be installed to stop all logger contexts when the system stops.
+
+| [[log4j2.shutdownCallbackRegistry]]`log4j2.shutdownCallbackRegistry`
+
+(`LOG4J_SHUTDOWN_CALLBACK_REGISTRY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/DefaultShutdownCallbackRegistry[DefaultShutdownCallbackRegistry]
+|
+The fully qualified class name of a link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry[ShutdownCallbackRegistry] implementation.
+Integrators can use this to customize the shutdown order of the JVM.
+
+The default implementation executes all shutdown actions in a separate `Thread` registered through https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#addShutdownHook-java.lang.Thread-[Runtime#addShutdownHook()].
+
+
+| [[log4j2.uuidSequence]]`log4j2.uuidSequence`
+
+(`LOG4J_UUID_SEQUENCE`)
+| 0
+|
+Provides a `long` see to the UUID generator used by the `%uuid` pattern converter.
+
+Can be used to assure uniqueness of UUIDs generated by multiple JVMs on the same machine.
Review Comment:
The property needs to be mentioned here.
I can shorten the description of the property, but that will leave the reader wondering, were is this actually used?
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "vy (via GitHub)" <gi...@apache.org>.
vy commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587668137
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
+| If set to a value different from `false`, sets the level of the status logger to `TRACE` overriding any other system property.
+
+| [[log4j2.statusEntries]]`log4j2.statusEntries`
+
+(`LOG4J_STATUS_ENTRIES`)
+| 0
+| Specifies the number of status logger entries to cache.
+Once the limit is reached newer entries will overwrite the oldest ones.
+
+| [[log4j2.statusLoggerLevel]]`log4j2.statusLoggerLevel`
+
+(`LOG4J_STATUS_LOGGER_LEVEL`)
+| ERROR
+| Specifies the level of the status logger.
+Can be overridden by <<log4j2.debug>> or the `status` property of the current configuration file.
+
+| [[log4j2.statusLoggerDateFormat]]`log4j2.statusLoggerDateFormat`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html#ISO_INSTANT[DateTimeFormatter#ISO_INSTANT]
+| Sets the https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter] pattern used by status logger to format dates.
+
+| [[log4j2.statusLoggerDateFormatZone]]`log4j2.statusLoggerDateFormatZone`
+
+(`LOG4J_STATUS_LOGGER_DATE_FORMAT_ZONE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html#systemDefault()[ZoneId#systemDefault()]
+| Sets the timezone id used by status logger. See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/ZoneId.html[ZoneId] for the accepted formats.
+
+|===
+
+=== Simple logger
+
+The simple logger implementation contained in `log4j-api` can be configured using these properties:
+
+.Simple logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.simplelogLevel]]`log4j2.simplelogLevel`
+
+(`LOG4J_SIMPLELOG_LEVEL`)
+| ERROR
+| Default level for new logger instances.
+
+| [[log4j2.simplelog.loggerName.level]]`log4j2.simplelog.<loggerName>.level`
+
+(`LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL`)
+| value of <<log4j2.simplelogLevel>>
+| Log level for a logger instance named `<loggerName>`.
+
+| [[log4j2.simplelogShowContextMap]]`log4j2.simplelogShowContextMap`
+
+(`LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP`)
+| false
+| If `true`, the full thread context map is included in each log message.
+
+| [[log4j2.simplelogShowlogname]]`log4j2.simplelogShowlogname`
+
+(`LOG4J_SIMPLELOG_SHOWLOGNAME`)
+| false
+| If `true`, the logger name is included in each log message.
+
+| [[log4j2.simplelogShowShortLogname]]`log4j2.simplelogShowShortLogname`
+
+(`LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME`)
+| true
+| If `true`, only the last component of a logger name is included in each log message.
+
+| [[log4j2.simplelogShowdatetime]]`log4j2.simplelogShowdatetime`
+
+(`LOG4J_SIMPLELOG_SHOWDATETIME`)
+| false
+| If `true`, a timestamp is included in each log message.
+
+| [[log4j2.simplelogDateTimeFormat]]`log4j2.simplelogDateTimeFormat`
+
+(`LOG4J_SIMPLELOG_DATE_TIME_FORMAT`)
+| `yyyy/MM/dd HH:mm:ss:SSS zzz`
+| Date-time format to use. Ignored if <<log4j2.simplelogShowdatetime>> is `false`.
+
+| [[log4j2.simplelogLogFile]]`log4j2.simplelogLogFile`
+
+(`LOG4J_SIMPLELOG_LOG_FILE`)
+| System.err
+a| Specifies the output stream used by all loggers:
+
+* `System.err` logs to the standard error output stream,
+* `System.out` logs to the standard output stream,
+* any other value is interpreted as a file name.
+
+|===
+
+[#simple-logger-thread-context]
+=== Thread context (Simple Logger)
+
+The behavior of the `ThreadContext` class can be fine-tuned using the following properties.
+
+[WARNING]
+====
+These configuration properties are only used by the Log4j Core and Simple Logger implementations of Log4j API.
+
+The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to the SLF4J https://slf4j.org/api/org/slf4j/MDC.html[MDC] class.
+
+The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls.
+====
+
+.Thread context configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableThreadContext]]`log4j2.disableThreadContext`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT`)
+| false
+| If `true`, the `ThreadContext` stack and map are disabled.
+
+| [[log4j2.disableThreadContextStack]]`log4j2.disableThreadContextStack`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_STACK`)
+| false
+| If `true`, the `ThreadContext` stack is disabled.
+
+| [[log4j2.disableThreadContextMap]]`log4j2.disableThreadContextMap`
+
+(`LOG4J_DISABLE_THREAD_CONTEXT_MAP`)
+| false
+| If `true`, the `ThreadContext` map is disabled.
+
+| [[log4j2.threadContextMap]]`log4j2.threadContextMap`
+
+(`LOG4J_THREAD_CONTEXT_MAP`)
+| `WebApp`
+
+(GC-free mode: `CopyOnWrite`)
+a| Fully specified class name of a custom `ThreadContextMap` implementation class or one of the predefined constants:
+
+* `NoOp`: to disable the thread context,
+* `WebApp`: a web application-safe implementation, that only binds JRE classes to `ThreadLocal` to prevent memory leaks,
+* `CopyOnWrite`: a copy-on-write implementation,
+* `GarbageFree`: a garbage-free implementation.
+
+| [[isThreadContextMapInheritable]]`log4j2.isThreadContextMapInheritable`
+
+(`LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE`)
+| false
+| If `true` uses an `InheritableThreadLocal` to copy the thread context map to newly created threads.
+
+| [[log4j2.garbagefreeThreadContextMap]]`log4j2.garbagefreeThreadContextMap`
+
+(`LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP`)
+| false
+| If set to `true` selects a garbage-free thread context map implementation.
+Requires <<log4j2.enableThreadlocals>> to be also `true`.
+
+|===
+
+== Log4j Core
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration_new.adoc#configuration-file[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
+
+=== Async components
+
+The behavior of all three async components (`AsyncLogger`, `AsyncLoggerConfig` and `AsyncAppender`) can be tuned using these properties:
+
+.Common async component configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.formatMsgAsync]]`log4j2.formatMsgAsync`
+
+(`LOG4J_FORMAT_MSG_ASYNC`)
+| false
+| If `false`, Log4j will make sure the message is formatted in the caller thread, otherwise the formatting will occur on the asynchronous thread.
+
+**Remark**: messages annotated with link:../javadoc/log4j-api/org/apache/logging/log4j/message/AsynchronouslyFormattable[AsynchronouslyFormattable] will be formatted on the async thread regardless of this setting.
+
+| [[log4j2.asyncQueueFullPolicy]]`log4j2.asyncQueueFullPolicy`
+
+(`LOG4J_ASYNC_QUEUE_FULL_POLICY`)
+| `Default`
+a| Determines the link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncQueueFullPolicy[AsyncQueueFullPolicy] to use when the underlying async component cannot keep up with the logging rate and the queue is filling up.
+
+It accepts the following values:
+
+* `Default`: blocks the calling thread until the event can be added to the queue.
+
+* `Discard`: when the queue is full, it drops the events whose level is equal or less than the threshold level (see <<log4j2.discardThreshold>>).
+
+* the fully qualified class name of a custom implementation
+
+| [[log4j2.discardThreshold]]`log4j2.discardThreshold`
+
+(`LOG4J_DISCARD_THRESHOLD`)
+| `INFO`
+| Determines the threshold level used by a `Discard` queue full policy.
+Log events whose level is equal or less specific than the threshold level will be discarded during a queue full event.
+See also <<log4j2.asyncQueueFullPolicy>>.
+
+|===
+
+==== `AsyncLogger`
+
+Additional properties supported by `AsyncLogger` are documented in the xref:manual/async.adoc#SysPropsAllAsync[System Properties to configure all asynchronous loggers] table.
+
+==== `AsyncLoggerConfig`
+
+Additional properties supported by `AsyncLoggerConfig` are documented in the xref:manual/async.adoc#SysPropsMixedSync-Async[System Properties to configure mixed asynchronous and normal loggers] table.
+
+=== Context selector
+
+The link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ContextSelector[ContextSelector] component specifies the strategy used by Log4j to create new logger contexts.
+The choice of `ContextSelector` determines in particular:
+
+* how loggers are divided among logger contexts.
+See xref:manual/logsep.adoc[Log Separation] for details.
+
+* the `Logger` implementation used by Log4j Core.
+See xref:manual/async.adoc[Async Logging] as an example of this usage.
+
+.Context selector configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.contextSelector]]`log4j2.contextSelector`
+
+(`LOG4J_CONTEXT_SELECTOR`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[ClassLoaderContextSelector]
+a|
+Specifies the fully qualified class name of the `ContextSelector` implementation to use.
+
+The implementations available by default are:
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/BasicContextSelector[org.apache.logging.log4j
+.core.selector.BasicContextSelector]: creates a single logger context and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/BasicAsyncLoggerContextSelector[org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector]: creates a single logger context and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector[org.apache.logging.log4j.core.selector.ClassLoaderContextSelector]: creates a separate logger context per classloader and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/async/AsyncLoggerContextSelector[org.apache.logging.log4j.core.async.AsyncLoggerContextSelector]: creates a separate logger context per classloader and xref:manual/async.adoc[asynchronous loggers],
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/osgi/BundleContextSelector[org.apache.logging.log4j.core.osgi.BundleContextSelector]: creates a separate logger context per OSGi bundle and synchronous loggers,
+
+* link:../javadoc/log4j-core/org/apache/logging/log4j/core/selector/JndiContextSelector[org.apache.logging.log4j.core.selector.JndiContextSelector]: creates loggers contexts based on a JNDI lookup and synchronous loggers.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application]] for details.
+
+|===
+
+=== Configuration factory
+
+Since configuration factories are used to parse the configuration file, they can **only** be configured through global configuration properties.
+
+[WARNING]
+====
+Log4j Core supports both local and remote configuration files.
+If a remote configuration file is used, its transport must be secured.
+See <<transport-security>> for details.
+====
+
+.Configuration factory properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationFactory]]`log4j2.configurationFactory`
+
+(`LOG4J_CONFIGURATION_FACTORY`)
+|
+|
+Specifies the fully qualified class name of the **preferred** link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/ConfigurationFactory[ConfigurationFactory] to use.
+
+Log4j will attempt to use the provided configuration factory before any other factory implementation.
+
+| [[log4j2.configurationFile]]`log4j2.configurationFile`
+
+(`LOG4J_CONFIGURATION_FILE`)
+| xref:manual/configuration.adoc#AutomaticConfiguration[automatically detected]
+a|
+Specifies a comma-separated list of URIs or file paths to Log4j 2 configuration files.
+
+If a relative URL is provided, it is interpreted as:
+
+* path to a file, if the file exists,
+* a classpath resource otherwise.
+
+See also xref:manual/configuration.adoc#AutomaticConfiguration[Automatic Configuration].
+
+| [[log4j2.level]]`log4j2.level`
+
+(`LOG4J_LEVEL`)
+| `ERROR`
+a|
+Specifies the level of the root logger if:
+
+* the default configuration is used,
+
+* or the configuration file does not specify a level for the root logger.
+
+| [[log4j2.mergeStrategy]]`log4j2.mergeStrategy`
+
+(`LOG4J_MERGE_STRATEGY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/DefaultMergeStrategy[DefaultMergeStrategy]
+|
+Specifies the fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/composite/MergeStrategy[MergeStrategy] implementation used to merge multiple configuration files into one.
+
+|===
+
+=== Garbage Collection
+
+.GC properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+
+| [[log4j2.enableDirectEncoders]]`log4j2.enableDirectEncoders`
+
+(`LOG4J_ENABLE_DIRECT_ENCODERS`)
+| `true`
+|
+If `true`, garbage-aware layouts will directly encode log events into https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html[ByteBuffers] provided by appenders.
+
+This prevents the creation temporary multiple `String` and `char[]` temporary objects.
+
+| [[log4j2.initialReusableMsgSize]]`log4j2.initialReusableMsgSize`
+
+(`LOG4J_INITIAL_REUSABLE_MSG_SIZE`)
+| 128
+| In GC-free mode, this property determines the initial size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+| [[log4j2.maxReusableMsgSize]]`log4j2.maxReusableMsgSize`
+
+(`LOG4J_MAX_REUSABLE_MSG_SIZE`)
+| 518
+| In GC-free mode, this property determines the maximum size of the reusable ``StringBuilder``s used by link:../javadoc/log4j-api/org/apache/logging/log4j/message/ReusableMessage[ReusableMessages] for formatting purposes.
+
+The default value allows is equal to `2 × (2 × log4j.initialReusableMsgSize + 2) + 2` and allows the
+``StringBuilder`` to be resized twice by the current JVM resize algorithm.
+
+| [[log4j2.layoutStringBuilderMaxSize]]`log4j2.layout{zwsp}StringBuilderMaxSize`
+
+(`LOG4J_LAYOUT_{zwsp}STRING_BUILDER_MAX_SIZE`)
+| 2048
+| This property determines the maximum size of the reusable ``StringBuilder``sused to format link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent[LogEvents].
+
+| [[log4j2.unboxRingbufferSize]]`log4j2.unboxRingbufferSize`
+
+(`LOG4J_UNBOX_RINGBUFFER_SIZE`)
+| 32
+|
+The link:../javadoc/log4j-api/org/apache/logging/log4j/util/Unbox[Unbox] utility class can be used by users to format primitive values without incurring in the boxing allocation cost.
+
+This property specifies the maximum number of primitive arguments to a log message that will be cached and usually does not need to be changed.
+
+|===
+
+=== JANSI
+
+If the https://fusesource.github.io/jansi/[JANSI] library is on the runtime classpath of the application, the following property can be used to control its usage:
+
+.JANSI properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.skipJansi]]`log4j2.skipJansi`
+
+(`LOG4J_SKIP_JANSI`)
+| `true`
+a| If the following conditions are satisfied:
+
+* Log4j runs on Windows,
+* this property is set to `false`,
+
+Log4j will use the JANSI library to color the output of the console appender.
+
+|===
+
+=== JNDI
+
+Due to the inherent security problems of https://docs.oracle.com/javase/tutorial/jndi/overview/[JNDI], its usage in Log4j is restricted to the `java:` protocol.
+
+Moreover, each JNDI usage must be **explicitly** enabled by the user through the following configuration properties.
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.enableJndiContextSelector]]`log4j2.enableJndiContextSelector`
+
+(`LOG4J_ENABLE_JNDI_CONTEXT_SELECTOR`)
+| `false`
+|
+When `true` the `JndiContextSelector` is enabled for the `java:` protocol.
+See xref:manual/webapp.adoc#use-jndi-context-selector[Web application] for more details.
+
+| [[log4j2.enableJndiJdbc]]`log4j2.enableJndiJdbc`
+
+(`LOG4J_ENABLE_JNDI_JDBC`)
+| `false`
+| When `true`, a Log4j JDBC Appender can use JNDI to retrieve a https://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html[DataSource] using the `java:` protocol.
+
+| [[log4j2.enableJndiJms]]`log4j2.enableJndiJms`
+
+(`LOG4J_ENABLE_JNDI_JMS`)
+| `false`
+| When `true`, a Log4j JMS Appender can use JNDI to retrieve the necessary components using the `java:` protocol.
+
+| [[log4j2.enableJndiLookup]]`log4j2.enableJndiLookup`
+
+(`LOG4J_ENABLE_JNDI_LOOKUP`)
+| `false`
+| When `true`, the Log4j JNDI Lookup can use the `java:` protocol.
+
+|===
+
+=== JMX
+
+.JMX properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.disableJmx]]`log4j2.disableJmx`
+
+(`LOG4J_DISABLE_JMX`)
+| `true`
+|
+If `false`, Log4j configuration objects like ``LoggerContext``s, ``Appender``s, ``Logger``s, etc.
+will be instrumented with ``MBean``s and can be remotely monitored and managed.
+
+| [[log4j2.jmxNotifyAsync]]`log4j2.jmxNotifyAsync`
+
+(`LOG4J_JMX_NOTIFY_ASYNC`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true`, Log4j's JMX notifications are sent from a separate background thread, otherwise they are sent from the caller thread.
+
+|===
+
+[#log4j-core-thread-context]
+=== Thread context (Log4j Core)
+
+Log4j Core supports the same properties as Simple Logger for the configuration of the thread context.
+See <<simple-logger-thread-context>> for more details.
+
+[#transport-security]
+=== Transport security
+
+Since configuration files can be used to load arbitrary classes into a Log4j Core `Configuration`, users need to ensure that all the configuration elements come from trusted sources (cf. link:/security#threat-common-config-sources[Thread model] for more information).
+
+In order to protect the user Log4j disables the `http` URI scheme by default and provides several configuration options to ensure secure transport of configuration files:
+
+:jsse-default-keystores: https://docs.oracle.com/en/java/javase/21/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-7D9F43B8-AABF-4C5B-93E6-3AFB18B66150
+
+.Transport security properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.configurationAllowedProtocols]]`log4j2.configuration{zwsp}AllowedProtocols`
+
+(`LOG4J_CONFIGURATION_{zwsp}ALLOWED_PROTOCOLS`)
+| file, https, jar
+|
+A comma separated list of URL protocols that may be used to load any kind of configuration source.
+
+To completely prevent accessing the configuration via the Java https://docs.oracle.com/javase/8/docs/api/java/net/URL.html[URL class] specify a value of `_none`.
+
+// TODO: What about 'jar:http:'?
+
+| [[log4j2.configurationAuthorizationProvider]]`log4j2.configuration{zwsp}AuthorizationProvider`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_PROVIDER`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/BasicAuthorizationProvider[BasicAuthorizationProvider]
+| The fully qualified class name of the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/AuthorizationProvider[AuthorizationProvider] implementation to use with `http` and `https` URL protocols.
+
+3+h| HTTP Basic authentication
+
+| [[log4j2.configurationAuthorizationEncoding]]`log4j2.configuration{zwsp}AuthorizationEncoding`
+
+(`LOG4J_CONFIGURATION_{zwsp}AUTHORIZATION_ENCODING`)
+| UTF-8
+| The encoding used in Basic Authentication (cf. https://datatracker.ietf.org/doc/html/rfc7617[RFC 7617]).
+
+| [[log4j2.configurationPassword]]`log4j2.configurationPassword`
+
+(`LOG4J_CONFIGURATION_PASSWORD`)
+|
+| The password to use in HTTP Basic authentication.
+
+If used in conjunction with <<log4j2.configurationPasswordDecryptor>> the contents of this variable are
+interpreted by the decryptor.
+
+| [[log4j2.configurationPasswordDecryptor]]`log4j2.configuration{zwsp}PasswordDecryptor`
+
+(`LOG4J_CONFIGURATION_{zwsp}PASSWORD_DECRYPTOR`)
+|
+| Fully qualified class name of an implementation of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/PasswordDecryptor[PasswordDecryptor] to use for the value of the <<log4j2.configurationPassword>> property.
+
+By default, the literal value of the password is used.
+
+| [[log4j2.configurationUsername]]`log4j2.configurationUsername`
+
+(`LOG4J_CONFIGURATION_USERNAME`)
+|
+| The username used in HTTP Basic authentication.
+
+3+h| TLS server authentication properties
+
+| [[log4j2.trustStoreLocation]]`log4j2.trustStoreLocation`
+
+(`LOG4J_TRUST_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java trust store]
+| The location of the trust store.
+
+| [[log4j2.trustStorePassword]]`log4j2.trustStorePassword`
+
+(`LOG4J_TRUST_STORE_PASSWORD`)
+|
+| The password for the trust store.
+
+| [[log4j2.trustStorePasswordFile]]`log4j2.trustStore{zwsp}PasswordFile`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the trust store.
+
+| [[log4j2.trustStorePasswordEnvironmentVariable]]`log4j2.trustStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_TRUST_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains password for the trust store.
+
+| [[log4j2.trustStoreType]]`log4j2.trustStoreType`
+
+(`LOG4J_TRUST_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.trustStoreKeyManagerFactoryAlgorithm]]`log4j2.trustStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_TRUST_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the trust store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+| [[log4j2.sslVerifyHostName]]`log4j2.sslVerifyHostName`
+
+(`LOG4J_SSL_VERIFY_HOST_NAME`)
+| false
+| If `true` enables verification of the name of the TLS server.
+
+3+h| TLS client authentication properties
+
+| [[log4j2.keyStoreLocation]]`log4j2.keyStoreLocation`
+
+(`LOG4J_KEY_STORE_LOCATION`)
+| see link:{jsse-default-keystores}[Default Java key store]
+| The location of the private key store.
+
+| [[log4j2.keyStorePassword]]`log4j2.keyStorePassword`
+
+(`LOG4J_KEY_STORE_PASSWORD`)
+|
+| The password for the private key store.
+
+| [[log4j2.keyStorePasswordFile]]`log4j2.keyStore{zwsp}PasswordFile`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_FILE`)
+|
+| The name of a file that contains the password for the private key store.
+
+| [[log4j2.keyStorePasswordEnvironmentVariable]]`log4j2.keyStore{zwsp}PasswordEnvironmentVariable`
+
+(`LOG4J_KEY_STORE_{zwsp}PASSWORD_ENVIRONMENT_VARIABLE`)
+|
+| The name of the environment variable that contains the password for the private key store.
+
+| [[log4j2.keyStoreType]]`log4j2.keyStoreType`
+
+(`LOG4J_KEY_STORE_TYPE`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[Default Java `KeyStore` type]
+| The type of private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore[KeyStore types].
+
+| [[log4j2.keyStoreKeyManagerFactoryAlgorithm]]`log4j2.keyStore{zwsp}KeyManagerFactoryAlgorithm`
+
+(`LOG4J_KEY_STORE_{zwsp}KEY_MANAGER_FACTORY_ALGORITHM`)
+| https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[Default Java `KeyManagerFactory` algorithm]
+| Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[KeyManagerFactory] implementation to use for the private key store.
+See https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[KeyManagerFactory types].
+
+|===
+
+=== Miscellaneous properties
+
+.Miscellaneous configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.clock]]`log4j2.clock`
+
+(`LOG4J_CLOCK`)
+| `SystemClock`
+a|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/Clock[Clock] implementation used to timestamp log events.
+
+The possible values are:
+
+* `SystemClock`: uses the best available system clock as time source.
+See https://docs.oracle.com/javase/{java-target-version}/docs/api/java/time/Clock.html#systemDefaultZone--[Clock#systemDefaultZone] for details.
+
+* `SystemMillisClock`: same as `SystemClock`, but truncates the result to a millisecond.
+
+* `CachedClock`: uses a separate thread to update the timestamp value.
+See link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/CachedClock[JavaDoc] for details.
+
+* `CoarseCachedClock`: alternative implementation of `CachedClock` with a slightly lower precision.
+See link:..//javadoc/log4j-core/org/apache/logging/log4j/core/util/CoarseCachedClock[JavaDoc] for details.
+
+* the fully qualified name of a custom implementation.
+
+| [[log4j2.contextDataInjector]]`log4j2.contextDataInjector`
+
+(`LOG4J_CONTEXT_DATA_INJECTOR`)
+| depends on the `ThreadContextMap` implementation
+| Fully specified class name of a link:../javadoc/log4j-core/org/apache/logging/log4j/core/ContextDataInjector[ContextDataInjector] implementation.
+
+The default implementation uses all implementations of link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ContextDataProvider[ContextDataProvider] registered with `ServiceLoader`.
+
+| [[log4j2.logEventFactory]]`log4j2.logEventFactory`
+
+(`LOG4J_LOG_EVENT_FACTORY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/DefaultLogEventFactory[DefaultLogEventFactory]
+
+(GC-free mode: link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/ReusableLogEventFactory[ReusableLogEventFactory])
+|
+Specifies the link:../javadoc/log4j-core/org/apache/logging/log4j/core/impl/LogEventFactory[LogEventFactory]
+implementation to use to create log events.
+
+| [[log4j2.shutdownHookEnabled]]`log4j2.shutdownHookEnabled`
+
+(`LOG4J_SHUTDOWN_HOOK_ENABLED`)
+| `true`
+
+(Web-app mode: `false`)
+|
+If `true` a shutdown hook will be installed to stop all logger contexts when the system stops.
+
+| [[log4j2.shutdownCallbackRegistry]]`log4j2.shutdownCallbackRegistry`
+
+(`LOG4J_SHUTDOWN_CALLBACK_REGISTRY`)
+| link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/DefaultShutdownCallbackRegistry[DefaultShutdownCallbackRegistry]
+|
+The fully qualified class name of a link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry[ShutdownCallbackRegistry] implementation.
+Integrators can use this to customize the shutdown order of the JVM.
+
+The default implementation executes all shutdown actions in a separate `Thread` registered through https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#addShutdownHook-java.lang.Thread-[Runtime#addShutdownHook()].
+
+
+| [[log4j2.uuidSequence]]`log4j2.uuidSequence`
+
+(`LOG4J_UUID_SEQUENCE`)
+| 0
+|
+Provides a `long` see to the UUID generator used by the `%uuid` pattern converter.
+
+Can be used to assure uniqueness of UUIDs generated by multiple JVMs on the same machine.
Review Comment:
Why does it need to be mentioned here?
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Revamp configuration properties (logging-log4j2)
Posted by "ppkarwasz (via GitHub)" <gi...@apache.org>.
ppkarwasz commented on code in PR #2552:
URL: https://github.com/apache/logging-log4j2/pull/2552#discussion_r1587660266
##########
src/site/antora/modules/ROOT/pages/manual/_properties.adoc:
##########
@@ -0,0 +1,1022 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+[#SystemProperties]
+= Global configuration properties
+
+Log4j contains a simple configuration properties sub-system that aggregates data from multiple property sources, such as Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties] and https://docs.oracle.com/javase/tutorial/essential/environment/env.html[Environment Variables].
+See <<property-sources>> for a complete list of supported sources
+
+Global configuration properties are used by Log4j in the following situations:
+
+* to finely tune global Log4j API and Log4j Core services that are independent of the configuration file,
+* to change the default values of attributes used in a configuration file.
+
+Since Log4j 2.10 all the property names follow a common naming scheme:
+
+----
+log4j2.camelCasePropertyName
+----
+
+except the environment variables, which follow the:
+
+----
+LOG4J_CAMEL_CASE_PROPERTY_NAME
+----
+
+convention.
+
+[NOTE]
+====
+If a `log4j2.system.properties` file is available on the classpath its contents are sourced into Java system properties at Log4j startup.
+====
+
+[WARNING]
+====
+To provide backward compatibility with versions older than 2.10 a certain number of additional property names is also supported using a fuzzy matching algorithm.
+
+In case of problems with the properties sub-system, make sure that your application does not use property names with the following case-insensitive prefixes:
+
+* `asyncLogger`,
+* `disableThreadContext`,
+* `isThreadContext`,
+* `org.apache.logging.log4j`
+
+and that all the properties names that start with `log4j` use the normalized form provided by the tables below.
+====
+
+== Meta configuration properties
+
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
+
+.Meta configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.isWebapp]]`log4j2.isWebapp`
+
+(`LOG4J_IS_WEBAPP`)
+| `true` if the https://jakarta.ee/specifications/servlet/6.0/apidocs/jakarta.servlet/jakarta/servlet/servlet[Servlet] class on classpath
+| Setting this property to `true` switches Log4j Core into "Web application mode" (_"Web-app mode"_).
+
+In this mode Log4j is optimized to work in a Servlet container.
+
+This mode is incompatible with <<log4j2.enableThreadlocals>>.
+
+| [[log4j2.enableThreadlocals]]`log4j2.enableThreadlocals`
+
+(`LOG4J_ENABLE_THREADLOCALS`)
+| `!log4j2.isWebapp`
+| Setting this property to `true` switches Log4j Core into "garbage-free mode" (_"GC-free mode"_).
+
+In this mode Log4j uses `ThreadLocal`s for object pooling to prevent object allocations.
+
+This mode is incompatible with <<log4j2.isWebapp>>.
+
+|===
+
+== Log4j API properties
+
+The services included in the `log4j-api` module can be configured exclusively through configuration properties.
+
+=== LoaderUtil
+
+The `LoaderUtil` class is used to load classes specified by the user using a fully qualified class name.
+Therefore, its configuration influences all other services.
+
+It has only one configuration property:
+
+.LoaderUtil configuration properties
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.ignoreTcl]]`log4j2.ignoreTcl`
+
+(`LOG4J_IGNORE_TCL`)
+| `false`
+|
+If `true`, classes are only loaded using the same classloader that loaded Log4j.
+
+Otherwise, an attempt is made to load classes with the current thread's context class loader before falling back to the default class loader.
+
+|===
+
+=== Provider
+
+The runtime classpath of an application **should** contain only a single implementation of the Log4j API.
+In the particular case, when multiple implementations are present, you can select a specific implementation by setting the value of `log4j2.provider` (or environment variable `LOG4J_PROVIDER`) to the fully qualified name of the chosen provider.
+See link:../javadoc/log4j-api/org/apache/logging/log4j/spi/Provider[Provider] for details.
+
+[NOTE]
+====
+For backward compatibility users can specify the link:../javadoc/log4j-api/org/apache/logging/log4j/spi/LoggerContextFactory[LoggerContextFactory] and link:../javadoc/log4j-api/org/apache/logging/log4j/spi/ThreadContextMap[ThreadContextMap] services independently using the `log4j2.loggerContextFactory` and <<log4j2.threadContextMap>> properties respectively.
+====
+
+=== Status Logger
+
+Log4j contains an internal logging mechanism called `StatusLogger` that is used by all Log4j components.
+By default, the status logger only reports errors on the standard error stream, but you can configure it using the following properties.
+
+.Status logger configuration
+[cols="1,1,5"]
+|===
+h| Java Property
+
+(Environment Variable)
+h| Default Value
+h| Description
+
+| [[log4j2.debug]]`log4j2.debug`
+
+(`LOG4J_DEBUG`)
+| false
Review Comment:
Should be fixed now.
--
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: notifications-unsubscribe@logging.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org