[PR] Port system properties documentation to `main` (logging-log4j2)

["ppkarwasz (via GitHub)" <gi...@apache.org>]

ppkarwasz opened a new pull request, #2590:
URL: https://github.com/apache/logging-log4j2/pull/2590

   Ports to `main` the changes introduced in #2552 .
   
   Part of #2525
   


-- 
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] Port system properties documentation to `main` (logging-log4j2)

["ppkarwasz (via GitHub)" <gi...@apache.org>]

ppkarwasz merged PR #2590:
URL: https://github.com/apache/logging-log4j2/pull/2590


-- 
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] Port system properties documentation to `main` (logging-log4j2)

["ppkarwasz (via GitHub)" <gi...@apache.org>]

ppkarwasz commented on code in PR #2590:
URL: https://github.com/apache/logging-log4j2/pull/2590#discussion_r1604618187


##########
src/site/antora/modules/ROOT/pages/manual/systemproperties.adoc:
##########
@@ -14,895 +14,272 @@
     See the License for the specific language governing permissions and
     limitations under the License.
 ////
+[id=system-properties]
+= 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.
+
+Configuration properties are used by Log4j in the following situations:
+
+* to finely tune 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.
+
+Log4j 3 introduces significant changes in the configuration properties subsystem by adding support for logger context specific properties.
+Two kinds of configuration properties can be used:
+
+Logger context scoped properties::
++
+These properties apply only to a single logger context.
+If `<contextName>` is the name of a logger context, it can be tuned using properties of the form:
++
+----
+log4j.contexts.<contextName>.propertyName
+----
++
+If the configuration property is specified using environment variables, the naming convention used is:
++
+----
+LOG4J_CONTEXTS_<contextName>_PROPERTY_NAME
+----
++
+[WARNING]
+====
+Not all configuration properties can be used this way.
+Properties that specify global Log4j services, such as the logging provider used, can not be restricted to a single logger context.
+====
+
+Global configuration properties::
++
+Global configuration properties can be used to provide a **default** value for context scoped properties described above.
+Their generic syntax is:
++
+----
+log4j.propertyName
+----
++
+where `propertyName` is a sequence of camelcase words separated by dots.
+As usual, the environment variable property source adopts a different convention:
++
+----
+LOG4J_PROPERTY_NAME
+----
 
-[#SystemProperties]
-== System Properties
-
-The Log4j documentation references a number of System Properties that
-can be used to control various aspects of Log4j 2 behavior. How properties
-are handled has undergone significant changes in Log4j 3.x so properties
-defined for applications using Log4j 2.x may need to be modified to work
-with Log4j 3.x.
-
-=== Property Name Aliases
-
-Older versions of Log4j used a different format for property names. Many of these names are still supported via
-the use of aliases. Log4j locates all files named `META-INF/log4j2-propertyMapping.json` in which the old property
-names are mapped to their new counterparts. Applications may make use of this by creating a file with the same path
-in a jar or classes folder that is on the class path. Note that these files are read when Log4j initializes and are
-used to remap settings located in a Properties object managed by a PropertySource, such as the System Properties or
-environment variables.
-
-=== Application Scoped Properties and Property Names
-
-Log4j is designed to allow multiple applications to reside in the same JVM
-and allow each to have their own set of Loggers and logging configuration,
-so it is somewhat logical that the applications may want to take advantage
-of Log4j functionality in different ways. Log4j achieves this through the
-use of the LoggerContext. A LoggerContext is the anchor point for the configuration
-and all the Loggers in the application. However, how an application is assigned its
-own LoggerContext depends greatly on the environment it is running in.
-
-In a typical web container, such as Tomcat or Jetty, the application server runs
-in its own ClassLoader and then creates a separate child ClassLoader for each application.
-In this environment, Log4j's default ContextSelector, ClassLoaderContextSelector, works
-well by associating the LoggerContext with the current ClassLoader. However,
-JEE environments typically will need to use the JndiContextSelector to locate the
-LoggerContext by the JNDI name associated with the application.
-
-So how does this relate to application scoped properties? The application will need to
-provide a file containing the application specific properties, locate them as
-system properties or environment variables, or in Log4j's system scoped properties files.
-This is achieved using the following rules:
-
-1. In general, Log4j properties are named using the scheme ``log4j2.\{contextName}.\{componentName}.\{key}``.
-A contextName of ``\*`` indicates the property is system wide. For example, the Log4j configuration file
-could be identified as ``log4j2.*.Configuration.file`` as the system wide value while
-``log4j2.PaymentUI.Configuration.file`` would only apply to the application with the context name
-of PaymentUI. Note that property names are case sensitive.
-2. Applications that use the ClassLoaderContextSelector will typically have unpredictable names and so
-cannot be configured as system properties or in Log4j's ``log4j2.components.properties`` or
-``log4j2.components.json`` files. Instead, they should be placed into a file named
-``META-INF/log4j2.context.properties`` or ``META-INF/log4j2.context.json`` in the classpath
-of the ClassLoader for the application. In this case the properties should be specified only as
-``\{componentName}.\{key}``, leaving off the leading "log4j2" and contextName since these properties
-only apply to the context in which they are located.
-3. While applications that use names to identify the LoggerContext can also use the ``META-INF/log4j2.context``
-files, generally this is not very useful since they may share ClassLoaders. Instead, they can
-use files named ``META-INF/log4j2.\{contextName}.properties`` or ``META-INF/log4j2.\{contextName}.json``.
-Like the properties specified in item 2 above, these properties must also specify their properties as
-``\{componentName}.\{key}`` leaving off the leading "log4j2" and contextName.
-
-=== Custom Property Sources
-
-Properties are located using PropertySources. This system is extensible
-and is enabled through the
-link:../javadoc/log4j-api/org/apache/logging/log4j/util/PropertySource.html[`PropertySource`]
-interface. Additional property source classes can be added through the
-standard `ServiceLoader` mechanism in Java SE.
-
-
-Properties can be overridden by sources with a lower number priority
-(e.g.., -100 comes before 100). The following sources are all available
-by default:
+[TIP]
+====
+You can specify configuration properties using a `log4j2.component.properties` resource at the root of your classpath.
+The configuration properties sub-system will take care of merging the content of all these resources.
+====
 
-.PropertySource priorities and descriptions
-[cols="2,1,5",frame="all"]
-|===
-|Source |Priority |Description
-
-|Spring Boot Properties
-|-100
-|This property source is enabled only if the Java application uses Spring Boot and the
-`log4j-spring` module is present. It resolves properties using a Spring
-link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/env/Environment.html[Environment].
-
-|System Properties
-|0
-|All properties can be set using normal system
-property patterns. These have the lowest numerical priority among commonly available property sources
-and can override included `log4j2.component.properties` files or environment variables. If a `log4j2.system.properties` file is available on the classpath its contents are
-sourced into Java system properties at Log4j startup.
-
-|Environment Variables
-|100
-|Environment variables are all prefixed
-with `LOG4J_`, are in all caps, and words are all separated by
-underscores. Only this naming scheme is support for environment
-variables as there were no old naming schemes to maintain compatibility
-with.
-
-|`log4j2.context.json` or `log4j2.\{contextName}.json`
-|110
-|Properties in these files only apply to the specific LoggerContext to which they are bound, either by name or ClassLoader.
-
-|`log4j2.context.properties' or `log4j2.\{contextName}.properties`
-|120
-|Properties in these files only apply to the specific LoggerContext to which they are bound, either by name or ClassLoader.
-
-|`log4j2.component.properties` file
-|200
-|Including this file on the classpath can be used as an alternative to providing properties as system
-properties. This is the property source with highest numerical priority and can be used to provide
-default values that can be overridden by the system administrator.
-|===
+[IMPORTANT]
+====
+The names of **all** configuration properties changed between Log4j 2 and Log4j 3.
 
-The table below lists these properties that are included as part of the Log4j API along with their
-default value and a description of what they control. The component identifies tha category the property
-fits into, the alias includes values from Log4j 2.x that are still allowed, the Scope identifies whether
-the setting may be applied system wide and/or to a LoggerContext.
+To help users with the migration process the properties described in
+link:/log4j/2.x/manual/systemproperties.html[Log4j 2 configuration properties]
+are still supported through a backward-compatibility mechanism.
+This mechanism is based on `META-INF/log4j/propertyMapping.json` classpath resources.
 
-.Log4j 2 API configuration properties
-[cols="1,1,3,1,2,3",frame="all"]
-|===
-|Component Name |Property Key |Alias |Scope |Default Value |Description
-
-|GC
-|initialReusableMsgSize
-|log4j2.initialReusableMsgSize, LOG4J_INITIAL_REUSABLE_MSG_SIZE
-|System/Application
-|128
-|In GC-free mode, this property determines the initial size of the reusable StringBuilders where the
-message text is formatted and potentially passed to background threads.
-
-|GC
-|maxReusableMsgSize
-|log4j2.maxReusableMsgSize, LOG4J_MAX_REUSABLE_MSG_SIZE
-|System/Application
-|518
-|In GC-free mode, this property determines the maximum size of the reusable StringBuilders where the
-message text is formatted and potentially passed to background threads.
-
-|Loader
-|forceTCLOnly
-|log4j2.forceTCLOnly, LOG4J_FORCE_TCL_ONLY
-|System
-|false
-|If `true`, classes and configuration are only loaded with the default context class loader.
-Otherwise, log4j also uses the log4j classloader, parent classloaders and the system classloader.
-
-|Loader
-|ignoreTCL
-|log4j2.ignoreTCL, LOG4J_IGNORE_TCL
-|System
-|false
-|If `true`, classes are only loaded with the default class loader. Otherwise, an attempt is made to load
-classes with the current thread's context class loader before falling back to the default class loader.
-
-|LoggerContext
-|factory
-|log4j2.loggerContextFactory, LOG4J_LOGGER_CONTEXT_FACTORY
-|System
-|org.apache.logging.log4j.simple.SimpleLoggerContextFactory
-|Factory class used by LogManager tobootstrap the logging implementation. The core jar provides
-`org.apache.logging.log4j.core.impl.Log4jContextFactory`.
-
-|Message
-|factory
-|log4j2.messageFactory, LOG4J_MESSAGE_FACTORY
-|System/Application
-`org.apache.logging.log4j.message.ReusableMessageFactory`
-|Default message factory used by Loggers if no factory was specified.
-
-|Message
-|flowMessageFactory
-|log4j2.flowMessageFactory, LOG4J_FLOW_MESSAGE_FACTORY
-|System/Application
-|org.apache.logging.log4j.message.DefaultFlowMessageFactory
-|Default flow message factory used by Loggers.
-
-|SimpleLogger
-|showContextMap
-|log4j2.simplelogShowContextMap, LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP
-|System
-|false
-|If `true`, the full ThreadContext map is included in each SimpleLogger log message.
-
-|SimpleLogger
-|showLogName
-|log4j2.simplelogShowlogname, LOG4J_SIMPLELOG_SHOWLOGNAME
-|System
-|false
-|If `true` the logger name is included in each SimpleLogger log message.
-
-|SimpleLogger
-|showShortLogName
-|log4j2.simplelogShowShortLogname, LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME
-|System
-|true
-|If `true`, only the last component of a logger name is included in SimpleLogger log messages. (E.g.,
-if the logger name is "mycompany.myproject.mycomponent", only "mycomponent" is logged.
-
-|SimpleLogger
-|showDateTime
-|log4j2.simplelogShowdatetime, LOG4J_SIMPLELOG_SHOWDATETIME
-|System
-|false
-|If `true`, SimpleLogger log messages contain timestamp information.
-
-|SimpleLogger
-|dateTimeFormat
-|log4j2.simplelogDateTimeFormat, LOG4J_SIMPLELOG_DATE_TIME_FORMAT
-|System
-|"yyyy/MM/dd HH:mm:ss:SSS zzz"
-|Date-time format to use. Ignored if `SimpleLogger.showDateTime` is `false`.
-
-|SimpleLogger
-|logFile
-|log4j2.simplelogLogFile, LOG4J_SIMPLELOG_LOG_FILE
-|System
-|system.err
-|"system.err" (case-insensitive) logs to System.err, "system.out" (case-insensitive)
-logs to System.out, any other value is interpreted as a file name to save SimpleLogger messages to.
-
-|SimpleLogger
-|level
-|log4j2.simplelogLevel, LOG4J_SIMPLELOG_LEVEL
-|System
-|ERROR
-|Default level for new SimpleLogger instances.
-
-|SimpleLogger
-|statusLoggerLevel
-|log4j2.simplelogStatusLoggerLevel, LOG4J_SIMPLELOG_STATUS_LOGGER_LEVEL
-|System
-|ERROR
-|This property is used to control the initial StatusLogger level, and can be overridden in code by calling
-`StatusLogger.getLogger() .setLevel(someLevel)`. Note that the
-StatusLogger level is only used to determine the status log output level
-until a listener is registered. In practice, a listener is registered
-when a configuration is found, and from that point onwards, status
-messages are only sent to the listeners (depending on their
-statusLevel).
-
-|StatusLogger
-|debug
-|log4j2.debug, LOG4J_DEBUG
-|System/Application
-|false
-|Log4j2 will print all
-internal logging to the console if system property `log4j2.debug` is either
-defined empty or its value equals to `true` (ignoring case).
-
-|StatusLogger
-|entries
-|log4j2.statusEntries, LOG4J_STATUS_ENTRIES
-|System
-|200
-|Number of StatusLogger events that are kept in a buffer and can be retrieved with `StatusLogger.getStatusData()`.
-
-|StatusLogger
-|dateFormat
-|log4j2.statusLoggerDateformat, LOG4J_STATUS_LOGGER_DATEFORMAT
-|System
-|
-|Date-time format string to use as the format for timestamps in the status logger output. See
-`java.text.SimpleDateFormat` for supported formats.
-
-|StatusLogger
-|defaultLevel
-|log4j2.defaultStatusLevel, LOG4J_DEFAULT_STATUS_LEVEL
-|System
-|ERROR
-|The StatusLogger logs events that occur in the logging system to the console. During configuration,
-AbstractConfiguration registers a StatusConsoleListener with the StatusLogger that may redirect status log
-events from the default console output to a file. The listener also
-supports fine-grained filtering. This system property specifies the
-default status log level for the listener to use if the configuration
-does not specify a status level.
-
-Note: this property is used by the log4j-core implementation only after a configuration file has been found.
-
-|StatusLogger
-|level
-|log4j2.statusLoggerLevel, LOG4J_STATUS_LOGGER_LEVEL
-|System
-|WARN
-|The initial "listenersLevel" of the StatusLogger. If StatusLogger listeners are added, the
-"listenerLevel" is changed to that of the most verbose listener. If any listeners are
-registered, the listenerLevel is used to quickly determine if an interested listener exists.
-
-By default, StatusLogger listeners are added when a configuration is
-found and by the JMX StatusLoggerAdmin MBean. For example, if a
-configuration contains `<Configuration status="trace">`, a listener with
-statusLevel TRACE is registered and the StatusLogger listenerLevel is
-set to TRACE, resulting in verbose status messages displayed on the
-console.
-
-If no listeners are registered, the listenersLevel is not used, and the
-StatusLogger output level is determined by
-`StatusLogger.getLogger().getLevel()` (see property
-`org.apache.logging.log4j.simplelog .StatusLogger.level`).
-
-|ThreadContext
-|enable
-|
-|System
-|true
-|If `false`,the ThreadContext stack and map are disabled. (May be ignored if a
-custom ThreadContext map is specified.) NOTE - this setting changed from `log4j2.disableThreadContext`
-in 2.x so cannot be mapped to 3.0 since it has the opposite meaning.
-
-|ThreadContext
-|enableStack
-|
-|System
-|false
-|If `false`, the ThreadContext stack is disabled. NOTE - this setting changed from
-`log4j2.disableThreadContextStack` in 2.x so cannot be mapped to 3.0 since it has the opposite meaning.
-
-|ThreadContext
-|enableMap
-|
-|System
-|false
-|If `false`, the ThreadContext map is disabled. (May be ignored if a custom ThreadContext map is specified.)
-NOTE - this setting changed from `log4j2.disableThreadContextMap` in 2.x so cannot be mapped to 3.0
-since it has the opposite meaning.
-
-|ThreadContext
-|garbageFree
-|log4j2.garbagefreeThreadContextMap, LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP
-|System
-|false
-|Specify "true" to make the ThreadContext map garbage-free.
-
-|ThreadContext
-|mapClass
-|log4j2.threadContextMap, LOG4J_THREAD_CONTEXT_MAP
-|System
-|
-|Fully specified
-class name of a custom `ThreadContextMap` implementation class.
-
-|ThreadContext
-|mapInheritable
-|log4j2.isThreadContextMapInheritable, LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE
-|System
-|false
-|If `true` use a `InheritableThreadLocal` to implement the ThreadContext map. Otherwise, use a plain `ThreadLocal`.
-(May be ignored if a custom ThreadContext map is specified.)
-
-|Unbox
-|ringBufferSize
-|log4j2.unboxRingbufferSize, LOG4J_UNBOX_RINGBUFFER_SIZE
-|System
-|32
-|The `org.apache.logging.log4j.util.Unbox` utility manages a small
-thread-local ring buffer of StringBuilders. Each time one of the `box()`
-methods is called, the next slot in the ring buffer is used, until the
-ring buffer is full and the first slot is reused. By default the Unbox
-ring buffer has 32 slots, so user code can have up to 32 boxed
-primitives in a single logger call.
-
-If more slots are required, set system property
-`Unbox.ringBufferSize` to the desired ring buffer size. Note that
-the specified number will be rounded up to the nearest power of 2.
-
-
-|Web
-|isWebApp
-|log4j2.isWebapp, LOG4J_IS_WEBAPP
-|System
-|true if `Servlet` class on class path
-|This system property can be used to force Log4j 2 to behave as if it is part of a web application (when true) or
-as if it is not part of a web application (when false).
+Users that use shading in their applications should take care of removing all `META-INF/log4j/propertyMapping.json`
+resources and use only Log4j 3 property names.
+====
 
-|===
+[WARNING]
+====
+Since Log4j Core 3 uses Log4j API 2 to support **global** configuration properties, these properties are looked up using a fuzzy matching algorithm.
 
-The table below lists these properties that are included as part of the Log4j Implementation along with their
-default value and a description of what they control. The component identifies tha category the property
-fits into, the alias includes values from Log4j 2.x that are still allowed, the Scope identifies whether
-the setting may be applied system wide and/or to a LoggerContext.
+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:
 
-.Log4j 2 Core configuration properties
-[cols="1,1,3,1,2,3"]
-|===
-|Component Name |Property Key |Alias |Scope |Default Value |Description
-
-
-|AsyncLogger
-|discardThreshold
-|log4j2.discardThreshold, LOG4J_DISCARD_THRESHOLD
-|System
-|INFO
-|Used by the DiscardingAsyncQueueFullPolicy to determine which events to drop when the queue becomes full.
-By default, `INFO`, `DEBUG` and `TRACE` level events are discarded when the queue is full. This property only has
-effect if `Discard` is specified as the `AsyncLogger.QueueFullPolicy`.
-
-|AsyncLogger
-|exceptionHandler
-|log4j2.asyncLoggerExceptionHandler, LOG4J_ASYNC_LOGGER_EXCEPTION_HANDLER
-|System
-|default handler
-|See link:async.html#SysPropsAllAsync[Async Logger System Properties] for details.
-
-|AsyncLogger
-|formatMsg
-|log4j2.formatMsgAsync, LOG4J_FORMAT_MSG_ASYNC
-|System
-|false
-|If `false` (the default), Log4j will make sure the message is formatted in the caller thread, to ensure the
-value at the time of the call to the logger is the value that is logged.
-
-|AsyncLogger
-|queueFullPolicy
-|log4j2.asyncQueueFullPolicy, LOG4J_ASYNC_QUEUE_FULL_POLICY
-|System
-|
-|Used by Async Loggers and the AsyncAppender to maintain application throughput even when the underlying
-appender cannot keep up with the logging rate and the queue is filling up.
-
-If no value is specified (the default) events are never discarded. If the queue is full, the logger call blocks
-until the event can be added to the queue.
-
-Specify `Discard` to drop events whose level is equal or less than the threshold level (INFO by default) when
-the queue is full.
-
-|AsyncLogger
-|retries
-|log4j2.asyncLoggerRetries, LOG4J_ASYNC_LOGGER_RETRIES
-|System
-|200
-|See link:async.html#SysPropsAllAsync[Async Logger System Properties] for details.
-
-|AsyncLogger
-|ringBufferSize
-|log4j2.asyncLoggerRingBufferSize, LOG4J_ASYNC_LOGGER_RING_BUFFER_SIZE
-|System
-|256 * 1024 or 4 * 1024 in garbage-free mode
-|See link:async.html#SysPropsAllAsync[Async Logger System Properties] for details.
-
-|AsyncLogger
-|sleepTimeNS
-|log4j2.asyncLoggerSleepTimeNs, LOG4J_ASYNC_LOGGER_SLEEP_TIME_NS
-|System
-|100
-|See link:async.html#SysPropsAllAsync[Async Logger System Properties] for details.
-
-|AsyncLogger
-|timeout
-|log4j2.asyncLoggerTimeout, LOG4J_ASYNC_LOGGER_TIMEOUT
-|System
-|10
-|See link:async.html#SysPropsAllAsync[Async Logger System Properties] for details.
-
-|AsyncLogger
-|waitStrategy
-|log4j2.asyncLoggerWaitStrategy, LOG4J_ASYNC_LOGGER_WAIT_STRATEGY
-|System
-|Timeout
-|See link:async.html#SysPropsAllAsync[Async Logger System Properties] for details.
-
-|AsyncLogger
-|syncronizeEnqueueWhenQueueFull
-|AsyncLogger.SynchronizeEnqueueWhenQueueFull, ASYNC_LOGGER_SYNCHRONIZE_ENQUEUE_WHEN_QUEUE_FULL
-|System
-|true
-|See link:async.html#SysPropsAllAsync[Async Logger System Properties] for details.
-
-|AsyncLogger
-|threadNameStrategy
-|log4j2.asyncLoggerThreadNameStrategy, LOG4J_ASYNC_LOGGER_THREAD_NAME_STRATEGY
-|System
-|CACHED
-|See link:async.html#SysPropsAllAsync[Async Logger System Properties] for details.
-
-|AsyncLoggerConfig
-|exceptionHandler
-|log4j2.asyncLoggerConfigExceptionHandler, LOG4J_ASYNC_LOGGER_CONFIG_EXCEPTION_HANDLER
-|System
-|default handler
-|See link:async.html#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details.
-
-|AsyncLoggerConfig
-|ringBufferSize
-|log4j2.asyncLoggerConfigRingBufferSize, LOG4J_ASYNC_LOGGER_CONFIG_RING_BUFFER_SIZE
-|System
-|256 * 1024 or 4 * 1024 in garbage-free mode
-|See link:async.html#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details.
-
-|AsyncLoggerConfig
-|waitStrategy
-|log4j2.asyncLoggerConfigWaitStrategy, LOG4J_ASYNC_LOGGER_CONFIG_WAIT_STRATEGY
-|System
-|Timeout
-|See link:async.html#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details.
-
-|AsyncLoggerConfig
-|timeout
-|log4j2.asyncLoggerConfigTimeout, LOG4J_ASYNC_LOGGER_CONFIG_TIMEOUT
-|System
-|10
-|See link:async.html#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details.
-
-|AsyncLoggerConfig
-|sleepTimeNS
-|log4j2.asyncLoggerConfigSleepTimeNs, LOG4J_ASYNC_LOGGER_CONFIG_SLEEP_TIME_NS
-|System
-|100
-|See link:async.html#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details.
-
-|AsyncLoggerConfig
-|retries
-|log4j2.asyncLoggerConfigRetries, LOG4J_ASYNC_LOGGER_CONFIG_RETRIES
-|System
-|200
-|See link:async.html#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details.
-
-|AsyncLoggerConfig
-|synchronizeEnqueueWhenQueueFull
-|AsyncLoggerConfig.SynchronizeEnqueueWhenQueueFull, ASYNC_LOGGER_CONFIG_SYNCHRONIZE_ENQUEUE_WHEN_QUEUE_FULL
-|System
-|true
-|See link:async.html#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details.
-
-|Configuration
-|allowedProtocols
-|log4j2.Configuration.allowedProtocols, LOG4J_CONFIGURATION_ALLOWED_PROTOCOLS
-|System/Application
-| 
-|A comma separated list of the protocols that may be used to load a configuration file. The default is https.
-To completely prevent accessing the configuration via a URL specify a value of "_none".
-
-|Configuration
-|authorizationProvider
-|log4j2.Configuration.authorizationProvider, LOG4J_CONFIGURATION_AUTHORIZATION_PROVIDER
-|System/Application
-|org.apache.logging.log4j.core.util.BasicAuthorizationProvider
-|The fully qualified class name of the AuthorizationProvider.
-
-|Configuration
-|clock
-|log4j2.clock, LOG4J_CLOCK
-|System/Application
-|SystemClock
-|Implementation of the `org.apache.logging.log4j .core.time.Clock` interface that is
-used for timestamping the log events. +
-By default, `System.currentTimeMillis` is called on every log event. +
-You can also specify a fully qualified class name of a custom class that implements the `Clock` interface.
-
-|Configuration
-|factory
-|log4j2.configurationFactory, LOG4J_CONFIGURATION_FACTORY
-|System/Application
-| 
-|Fully specified class name of a classextending
-`org.apache.logging.log4j.core .config.ConfigurationFactory`.
-If specified, an instance of this class is added to the list ofconfiguration factories.
-
-|Configuration
-|File
-|log4j2.configurationFile, LOG4J_CONFIGURATION_FILE
-|System
-| 
-|Path to an Log4j 2 configuration file. May
-also contain a comma separated list of configuration file names. May contain a URL.
-When specified as a URL the "override" query parameter may be used to specify additional
-configuration file locations.
-
-|Configuration
-|jansiEnabled
-|NBSP
-|System/Application
-|false
-|If `false`, the ConsoleAppender will not try to use the Jansi output stream on Windows.
-NOTE - this setting was named `log4j2.skipJansi in 2.x so cannot be mapped to 3.0 since it has the opposite meaning.
-
-|Configuration
-|mergeStrategy
-|log4j2.mergeStrategy, LOG4J_MERGE_STRATEGY
-|System/Application
-| 
-|The name of the class that implements the MergeStrategy interface. If not
-specified `DefaultMergeStrategy` will be used when creating a CompositeConfiguration.
-
-|Configuration
-|password
-|log4j2.Configuration.password, LOG4J_CONFIGURATION_PASSWORD
-|System/Application
-| 
-|The password required to access the remote logging configuration file.
-
-|Configuration
-|passwordDecryptor
-|log4j2.Configuration.passwordDecryptor, LOG4J_CONFIGURATION_DECRYPTOR
-|System/Application
-| 
-|If the password is encrypted this class will be used to decrypt it.
-
-|Configuration
-|userName
-|log4j2.Configuration.username, LOG4J_CONFIGURATION_USERNAME
-|System/Application
-| 
-|The user name required to access the remote logging configuration file.
-
-|Configuration
-|usePreciseClock
-|log4j2.usePreciseClock, LOG4J_USE_PRECISE_CLOCK
-|System/Application
-|false
-|When false the clock resolution will be in milliseconds. When true it will use the smallest granularity supported by
-the JVM. The precise clock is not garbage free. This setting only applies when Log4j's default SystemClock is used.
-
-|Configuration
-|level
-|log4j2.level, LOG4J_LEVEL
-|System/Application
-|ERROR
-|Log level of the default configuration. The default configuration is used if the ConfigurationFactory
-could not successfully create a configuration (e.g. no log4j2.xml file was found).
-
-|GC
-|enableDirectEncoders
-|log4j2.enableDirectEncoders, LOG4J_ENABLE_DIRECT_ENCODERS
-|System/Application
-|true
-|This property can be used to force
-garbage-aware Layouts and Appenders to revert to the pre-2.6 behaviour
-where converting log events to text generates temporary objects like
-Strings and char[] arrays, and converting this text to bytes generates
-temporary byte[] arrays. By default, this property is `true` and
-garbage-aware Layouts and Appenders that convert log events to text will
-convert this text to bytes without creating temporary objects.
-
-|GC
-|layoutStringBuilderMaxSize
-|log4j2.layoutStringBuilderMaxSize, LOG4J_LAYOUT_STRING_BUILDER_MAX_SIZE
-|System/Application
-|2048
-|This property determinesthe maximum size of the thread-local reusable StringBuilders used to
-format the log event to text by Layouts that extend AbstractStringLayout.
-
-
-|JMX
-|enabled
-|NBSP
-|System/Application
-|true
-|If `false`, Log4j configuration objects like LoggerContexts, Appenders, Loggers, etc. will not be instrumented
-with MBeans and cannot be remotely monitored and managed. NOTE - this setting was `log4j2.disableJmx` in 2.x
-so cannot be mapped to 3.0 since it has the opposite meaning.
-
-|JMX
-|notifyAsync
-|log4j2.jmxNotifyAsync, LOG4J_JMX_NOTIFY_ASYNC
-|System/Application
-|false for web apps, true otherwise
-|If `true`, log4j's JMX notifications are sent from a separate background thread,
-otherwise they are sent from the caller thread. If system property
-`Web.isWebApp` is `true` or the `javax.servlet.Servlet` class is on
-the classpath, the default behaviour is to use the caller thread to send
-JMX notifications.
-
-|JNDI
-|contextSelector
-|NBSP
-|System/Application
-|false
-|When true, the JndiContextSelector is enabled if the log4j-jndi jar is present on the classpath.
-
-|JNDI
-|enableJDBC
-|NBSP
-|System/Application
-|false
-|When true, the use of JNDI the JdbcAppender is enabled if the log4j-jndi jar is present on the classpath.
-
-|JNDI
-|enableJMS
-|NBSP
-|System/Application
-|false
-|When true, the use of JNDI the JMS Appender is enabled if the log4j-jndi and log4j-jakarta-jms jars are present on the
-classpath.
-
-|JNDI
-|enableLookup
-|NBSP
-|System/Application
-|false
-|When true, the use of JndiLookup is enabled if the log4j-jndi jar is present on the classpath.
-
-|LoggerContext
-|selector
-|log4j2.contextSelector, LOG4J_CONTEXT_SELECTOR
-|System
-|ClassLoaderContextSelector
-|Creates the `LoggerContext`s. An
-application can have one or more active LoggerContexts depending on the
-circumstances. See link:logsep.html[Log Separation] for more details.
-Available context selector implementation classes: +
-`org.apache.logging.log4j.core.async .AsyncLoggerContextSelector` -
-makes link:async.html[all loggers asynchronous]. +
-`org.apache.logging.log4j.core.async .BasicAsyncLoggerContextSelector` -
-makes link:async.html[all loggers asynchronous] using a single shared
-AsyncLoggerContext. +
-`org.apache.logging.log4j.core.selector .BasicContextSelector` - creates
-a single shared LoggerContext. +
-`org.apache.logging.log4j.core.selector .ClassLoaderContextSelector` -
-separate LoggerContexts for each web application. +
-`org.apache.logging.log4j.core.selector .JndiContextSelector` - use JNDI
-to locate each web application's LoggerContext. +
-`org.apache.logging.log4j.core.osgi .BundleContextSelector` - separate
-LoggerContexts for each OSGi bundle.
-
-|Logger
-|logEventFactory
-|log4j2.logEventFactory, LOG4J_LOG_EVENT_FACTORY
-|System/Application
-|org.apache.logging.log4j.core.impl .DefaultLogEventFactory
-|Factory class used by LoggerConfig to create `LogEvent` instances. (Ignored when
-the `AsyncLoggerContextSelector` is used.)
-
-|LoggerContext
-|shutdownHookEnabled
-|log4j2.shutdownHookEnabled, LOG4J_SHUTDOWN_HOOK_ENABLED
-|System/Application
-|true
-|Overrides the global flag forwhether or not a shutdown hook should be used to stop a
-`LoggerContext`. By default, this is enabled and can be
-disabled on a per-configuration basis. When running with the `log4j-jakarta-web`
-module, this is automatically disabled.
-
-|LoggerContext
-|shutdownCallbackRegistry
-|log4j2.shutdownCallbackRegistry, LOG4J_SHUTDOWN_CALLBACK_REGISTRY
-|System/Application
-|org.apache.logging.log4j.core.util.DefaultShutdownCallbackRegistry
-|Fully specified class name of a class implementing
-link:../log4j-core/apidocs/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry.html[ShutdownCallbackRegistry].
-If specified, an instance of this class is used instead of `DefaultShutdownCallbackRegistry`. The specified class
-must have a default constructor.
-
-|LoggerContext
-|stackTraceOnStart
-|log4j2.loggerContextStacktraceOnStart, LOG4J_LOGGER_CONTEXT_STACKTRACE_ON_START
-|System/Application
-|false
-|Prints a stacktrace to the status logger at DEBUG level when the
-LoggerContext is started. For debug purposes.
-
-|TransportSecurity
-|keyStoreLocation
-|log4j2.keyStoreLocation, LOG4J_KEY_STORE_LOCATION
-|System
-|
-|The location of the key store. If not provided the default key store will be used.
-
-|TransportSecurity
-|keyStorePassword
-|log4j2.keyStorePassword, LOG4J_KEY_STORE_PASSWORD
-|System
-|
-|Password needed to access the trust store.
-
-|TransportSecurity
-|keyStorePasswordFile
-|log4j2.keyStorePasswordFile, LOG4J_KEY_STORE_PASSWORD_FILE
-|System
-|
-|The location of a file that contains the password for the key store.
-
-|TransportSecurity
-|keyStorePasswordEnvironmentVariable
-|log4j2.keyStorePasswordEnvironmentVariable, LOG4J_KEY_STORE_PASSWORD_ENVIRONMENT_VARIABLE
-|System
-|
-|The name of the environment variable that contains the key store password.
-
-|TransportSecurity
-|keyStoreType
-|log4j2.keyStoreType, LOG4J_KEY_STORE_TYPE
-|System
-|
-|The type of key store used for the trust store.
-
-|TransportSecurity
-|keyStoreKeyManagerFactoryAlgorithm
-|log4j2.keyStoreKeyManagerFactoryAlgorithm, LOG4J_KEY_STORE_KEY_MANAGER_FACTORY_ALGORITHM
-|System
-|
-|Java cryptographic algorithm.
-
-|TransportSecurity
-|sslVerifyHostName
-|log4j2.sslVerifyHostName, LOG4J_SSL_VERIFY_HOSTNAME
-|System/Application
-|false
-|true or false if the host name should be verified
-
-|TransportSecurity
-|trustStoreLocation
-|log4j2.trustStoreLocation, LOG4J_TRUST_STORE_LOCATION
-|System
-|
-|The location of the trust store. If not provided the default trust store will be used.
-
-|TransportSecurity
-|trustStorePassword
-|log4j2.trustStorePassword, LOG4J_TRUST_STORE_PASSWORD
-|System
-|
-|Password needed to access the trust store.
-
-|TransportSecuirty
-|trustStorePasswordFile
-|log4j2.trustStorePasswordFile, LOG4J_TRUST_STORE_PASSWORD_FILE
-|System
-|
-|The location of a file that contains the password for the trust store.
-
-|TransportSecuirty
-|trustStorePasswordEnvironmentVariable
-|log4j2.trustStorePasswordEnvironmentVariable, LOG4J_TRUST_STORE_PASSWORD_ENVIRONMENT_VARIABLE
-|System
-|
-|The name of the environment variable that contains the trust store password.
-
-|TransportSecurity
-|trustStoreType
-|log4j2.trustStoreType, LOG4J_TRUST_STORE_TYPE
-|System
-|
-|The type of key store used for the trust store.
-
-|TransportSecurity
-|trustStoreKeyManagerFactoryAlgorithm
-|log4j2.trustStoreKeyManagerFactoryAlgorithm, LOG4J_TRUST_STORE_KEY_MANAGER_FACTORY_ALGORITHM
-|System
-|
-|Java cryptographic algorithm.
-
-|UUID
-|sequence
-|log4j2.uuidSequence, LOG4J_UUID_SEQUENCE
-|System
-|0
-|System property that may be used to seed the UUID generation with an integer value.
+* `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.
+====
 
-The table below lists the properties that are included as part of the Log4j JUL component along with their
-default value and a description of what they control. The component identifies tha category the property
-fits into, the alias includes values from Log4j 2.x that are still allowed, the Scope identifies whether
-the setting may be applied system wide and/or to a LoggerContext.
+[id=properties-meta]
+== Meta configuration properties
 
-.Log4j 3 JUL properties
-[cols="1,1,3,1,2,3"]
-|===
-|Component Name |Property Key |Alias |Scope |Default Value |Description
-
-|JUL
-|loggerAdapter
-|log4j2.julLoggerAdapter, LOG4J_JUL_LOGGER_ADAPTER
-|System
-|org.apache.logging.log4j .jul.ApiLoggerAdapter
-|Default LoggerAdapter to use in the JUL adapter.
-By default, if log4j-core is available, then the class `org.apache.logging.log4j.jul .CoreLoggerAdapter` will be used.
-Otherwise, the `ApiLoggerAdapter` will be used. Custom implementations
-must provide a public default constructor.
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
 
-|===
+include::partial$manual/systemproperties/properties-meta.adoc[leveloffset=+1]
+
+[id=properties-log4j-api]
+== Log4j API properties
+
+In order to configure Log4j API, see the
+link:/log4j/2.x/manual/systemproperties.html#properties-log4j-api[Log4j 2 site].
+
+[id=properties-log4j-core]
+== Log4j Core properties
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration.adoc[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
+
+[id=properties-async]
+=== Async components
+
+The behavior of all three async components (`AsyncLogger`, `AsyncLoggerConfig` and `AsyncAppender`) can be tuned using these properties:
+
+include::partial$manual/systemproperties/properties-async.adoc[leveloffset=+2]
+
+[id=properties-properties-context-selector]
+=== Logger context
+
+The
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/LoggerContext.html[LoggerContext]
+is one of the principal Log4j components (see
+xref:manual/architecture.adoc[]), which determines among other things, the way
+link:../javadoc/log4j-api/org/apache/logging/log4j/Logger.html[Logger]s are created.
+
+It can be customized using these properties:
+
+include::partial$manual/systemproperties/properties-logger-context.adoc[leveloffset=+2]
+
+[id=properties-configuration-factory]
+=== 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 <<properties-transport-security>> for details.
+====
+
+include::partial$manual/systemproperties/properties-configuration-factory.adoc[leveloffset=+2]
+
+[id=properties-message]
+=== Log messages
+
+The way Log4j builds
+link:../javadoc/log4j-api/org/apache/logging/log4j/message/Message.html[Message]s can be customized using these properties:
+
+include::partial$manual/systemproperties/properties-message.adoc[leveloffset=+2]
+
+[id=properties-log-event]
+=== Log events
+
+The way Log4j builds
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html[LogEvent]s can be customized using these properties:
+
+include::partial$manual/systemproperties/properties-log-event.adoc[leveloffset=+2]
+
+[id=properties-garbage-collection]
+=== Garbage Collection
+
+include::partial$manual/systemproperties/properties-garbage-collection.adoc[leveloffset=+2]
+
+[id=properties-jansi]
+=== 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:
+
+include::partial$manual/systemproperties/properties-jansi.adoc[leveloffset=+2]
 
-The table below lists the properties that are included as part of the Log4j Script component along with their
-default value and a description of what they control. The component identifies tha category the property
-fits into, the alias includes values from Log4j 2.x that are still allowed, the Scope identifies whether
-the setting may be applied system wide and/or to a LoggerContext.
+[id=properties-log4j-core-thread-context]
+=== Thread context
 
-.Log4j 3 Script properties
-[cols="1,1,3,1,2,3"]
+To configure the thread context used by Log4j Core, you can use the following properties:
+
+include::partial$manual/systemproperties/properties-thread-context.adoc[leveloffset=+2]
+
+[id=properties-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:
+
+include::partial$manual/systemproperties/properties-auth.adoc[leveloffset=+2]
+
+include::partial$manual/systemproperties/properties-transport-security.adoc[leveloffset=+2]
+
+[id=properties-log4j-core-misc]
+=== Miscellaneous properties
+
+include::partial$manual/systemproperties/properties-log4j-core-misc.adoc[leveloffset=+2]
+
+[id=properties-other-components]
+== Other components
+
+[id=properties-log4j-async-logger]
+=== Asynchronous Logger properties
+
+Asynchronous loggers support the following additional properties:
+
+include::partial$manual/systemproperties/properties-async-logger.adoc[leveloffset=+2]
+
+[id=properties-jndi-support]
+=== JNDI support
+
+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.
+
+include::partial$manual/systemproperties/properties-log4j-jndi.adoc[leveloffset=+2]
+
+[id=properties-log4j-jul]
+=== JUL-to-Log4j API bridge properties
+
+The JUL-to-Log4j API bridge provides the following configuration properties:
+
+include::partial$manual/systemproperties/properties-log4j-jul.adoc[leveloffset=+2]
+
+[id=properties-log4j-script]
+=== Script support
+
+Script support can be configured using the following properties:
+
+include::partial$manual/systemproperties/properties-log4j-script.adoc[leveloffset=+2]
+
+[id=property-sources]
+== Property sources

Review Comment:
   Fixed in eb4c54d564c8bd379dcbde03f17c9ea69b26d468



-- 
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] Port system properties documentation to `main` (logging-log4j2)

["ppkarwasz (via GitHub)" <gi...@apache.org>]

ppkarwasz commented on code in PR #2590:
URL: https://github.com/apache/logging-log4j2/pull/2590#discussion_r1603916609


##########
src/site/antora/modules/ROOT/pages/manual/systemproperties.adoc:
##########
@@ -14,895 +14,272 @@
     See the License for the specific language governing permissions and
     limitations under the License.
 ////
+[id=system-properties]
+= 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.
+
+Configuration properties are used by Log4j in the following situations:
+
+* to finely tune 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.
+
+Log4j 3 introduces significant changes in the configuration properties subsystem by adding support for logger context specific properties.
+Two kinds of configuration properties can be used:
+
+Logger context scoped properties::
++
+These properties apply only to a single logger context.
+If `<contextName>` is the name of a logger context, it can be tuned using properties of the form:
++
+----
+log4j.contexts.<contextName>.propertyName
+----
++
+If the configuration property is specified using environment variables, the naming convention used is:
++
+----
+LOG4J_CONTEXTS_<contextName>_PROPERTY_NAME
+----
++
+[WARNING]
+====
+Not all configuration properties can be used this way.
+Properties that specify global Log4j services, such as the logging provider used, can not be restricted to a single logger context.
+====
+
+Global configuration properties::
++
+Global configuration properties can be used to provide a **default** value for context scoped properties described above.
+Their generic syntax is:
++
+----
+log4j.propertyName
+----
++
+where `propertyName` is a sequence of camelcase words separated by dots.
+As usual, the environment variable property source adopts a different convention:
++
+----
+LOG4J_PROPERTY_NAME
+----
 
-[#SystemProperties]
-== System Properties
-
-The Log4j documentation references a number of System Properties that
-can be used to control various aspects of Log4j 2 behavior. How properties
-are handled has undergone significant changes in Log4j 3.x so properties
-defined for applications using Log4j 2.x may need to be modified to work
-with Log4j 3.x.
-
-=== Property Name Aliases
-
-Older versions of Log4j used a different format for property names. Many of these names are still supported via
-the use of aliases. Log4j locates all files named `META-INF/log4j2-propertyMapping.json` in which the old property
-names are mapped to their new counterparts. Applications may make use of this by creating a file with the same path
-in a jar or classes folder that is on the class path. Note that these files are read when Log4j initializes and are
-used to remap settings located in a Properties object managed by a PropertySource, such as the System Properties or
-environment variables.
-
-=== Application Scoped Properties and Property Names
-
-Log4j is designed to allow multiple applications to reside in the same JVM
-and allow each to have their own set of Loggers and logging configuration,
-so it is somewhat logical that the applications may want to take advantage
-of Log4j functionality in different ways. Log4j achieves this through the
-use of the LoggerContext. A LoggerContext is the anchor point for the configuration
-and all the Loggers in the application. However, how an application is assigned its
-own LoggerContext depends greatly on the environment it is running in.
-
-In a typical web container, such as Tomcat or Jetty, the application server runs
-in its own ClassLoader and then creates a separate child ClassLoader for each application.
-In this environment, Log4j's default ContextSelector, ClassLoaderContextSelector, works
-well by associating the LoggerContext with the current ClassLoader. However,
-JEE environments typically will need to use the JndiContextSelector to locate the
-LoggerContext by the JNDI name associated with the application.
-
-So how does this relate to application scoped properties? The application will need to
-provide a file containing the application specific properties, locate them as
-system properties or environment variables, or in Log4j's system scoped properties files.
-This is achieved using the following rules:
-
-1. In general, Log4j properties are named using the scheme ``log4j2.\{contextName}.\{componentName}.\{key}``.
-A contextName of ``\*`` indicates the property is system wide. For example, the Log4j configuration file
-could be identified as ``log4j2.*.Configuration.file`` as the system wide value while
-``log4j2.PaymentUI.Configuration.file`` would only apply to the application with the context name
-of PaymentUI. Note that property names are case sensitive.
-2. Applications that use the ClassLoaderContextSelector will typically have unpredictable names and so
-cannot be configured as system properties or in Log4j's ``log4j2.components.properties`` or
-``log4j2.components.json`` files. Instead, they should be placed into a file named
-``META-INF/log4j2.context.properties`` or ``META-INF/log4j2.context.json`` in the classpath
-of the ClassLoader for the application. In this case the properties should be specified only as
-``\{componentName}.\{key}``, leaving off the leading "log4j2" and contextName since these properties
-only apply to the context in which they are located.
-3. While applications that use names to identify the LoggerContext can also use the ``META-INF/log4j2.context``
-files, generally this is not very useful since they may share ClassLoaders. Instead, they can
-use files named ``META-INF/log4j2.\{contextName}.properties`` or ``META-INF/log4j2.\{contextName}.json``.
-Like the properties specified in item 2 above, these properties must also specify their properties as
-``\{componentName}.\{key}`` leaving off the leading "log4j2" and contextName.
-
-=== Custom Property Sources
-
-Properties are located using PropertySources. This system is extensible
-and is enabled through the
-link:../javadoc/log4j-api/org/apache/logging/log4j/util/PropertySource.html[`PropertySource`]
-interface. Additional property source classes can be added through the
-standard `ServiceLoader` mechanism in Java SE.
-
-
-Properties can be overridden by sources with a lower number priority
-(e.g.., -100 comes before 100). The following sources are all available
-by default:
+[TIP]
+====
+You can specify configuration properties using a `log4j2.component.properties` resource at the root of your classpath.
+The configuration properties sub-system will take care of merging the content of all these resources.
+====
 
-.PropertySource priorities and descriptions
-[cols="2,1,5",frame="all"]
-|===
-|Source |Priority |Description
-
-|Spring Boot Properties
-|-100
-|This property source is enabled only if the Java application uses Spring Boot and the
-`log4j-spring` module is present. It resolves properties using a Spring
-link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/env/Environment.html[Environment].
-
-|System Properties
-|0
-|All properties can be set using normal system
-property patterns. These have the lowest numerical priority among commonly available property sources
-and can override included `log4j2.component.properties` files or environment variables. If a `log4j2.system.properties` file is available on the classpath its contents are
-sourced into Java system properties at Log4j startup.
-
-|Environment Variables
-|100
-|Environment variables are all prefixed
-with `LOG4J_`, are in all caps, and words are all separated by
-underscores. Only this naming scheme is support for environment
-variables as there were no old naming schemes to maintain compatibility
-with.
-
-|`log4j2.context.json` or `log4j2.\{contextName}.json`
-|110
-|Properties in these files only apply to the specific LoggerContext to which they are bound, either by name or ClassLoader.
-
-|`log4j2.context.properties' or `log4j2.\{contextName}.properties`
-|120
-|Properties in these files only apply to the specific LoggerContext to which they are bound, either by name or ClassLoader.
-
-|`log4j2.component.properties` file
-|200
-|Including this file on the classpath can be used as an alternative to providing properties as system
-properties. This is the property source with highest numerical priority and can be used to provide
-default values that can be overridden by the system administrator.
-|===
+[IMPORTANT]
+====
+The names of **all** configuration properties changed between Log4j 2 and Log4j 3.
 
-The table below lists these properties that are included as part of the Log4j API along with their
-default value and a description of what they control. The component identifies tha category the property
-fits into, the alias includes values from Log4j 2.x that are still allowed, the Scope identifies whether
-the setting may be applied system wide and/or to a LoggerContext.
+To help users with the migration process the properties described in
+link:/log4j/2.x/manual/systemproperties.html[Log4j 2 configuration properties]
+are still supported through a backward-compatibility mechanism.
+This mechanism is based on `META-INF/log4j/propertyMapping.json` classpath resources.
 
-.Log4j 2 API configuration properties
-[cols="1,1,3,1,2,3",frame="all"]
-|===
-|Component Name |Property Key |Alias |Scope |Default Value |Description
-
-|GC
-|initialReusableMsgSize
-|log4j2.initialReusableMsgSize, LOG4J_INITIAL_REUSABLE_MSG_SIZE
-|System/Application
-|128
-|In GC-free mode, this property determines the initial size of the reusable StringBuilders where the
-message text is formatted and potentially passed to background threads.
-
-|GC
-|maxReusableMsgSize
-|log4j2.maxReusableMsgSize, LOG4J_MAX_REUSABLE_MSG_SIZE
-|System/Application
-|518
-|In GC-free mode, this property determines the maximum size of the reusable StringBuilders where the
-message text is formatted and potentially passed to background threads.
-
-|Loader
-|forceTCLOnly
-|log4j2.forceTCLOnly, LOG4J_FORCE_TCL_ONLY
-|System
-|false
-|If `true`, classes and configuration are only loaded with the default context class loader.
-Otherwise, log4j also uses the log4j classloader, parent classloaders and the system classloader.
-
-|Loader
-|ignoreTCL
-|log4j2.ignoreTCL, LOG4J_IGNORE_TCL
-|System
-|false
-|If `true`, classes are only loaded with the default class loader. Otherwise, an attempt is made to load
-classes with the current thread's context class loader before falling back to the default class loader.
-
-|LoggerContext
-|factory
-|log4j2.loggerContextFactory, LOG4J_LOGGER_CONTEXT_FACTORY
-|System
-|org.apache.logging.log4j.simple.SimpleLoggerContextFactory
-|Factory class used by LogManager tobootstrap the logging implementation. The core jar provides
-`org.apache.logging.log4j.core.impl.Log4jContextFactory`.
-
-|Message
-|factory
-|log4j2.messageFactory, LOG4J_MESSAGE_FACTORY
-|System/Application
-`org.apache.logging.log4j.message.ReusableMessageFactory`
-|Default message factory used by Loggers if no factory was specified.
-
-|Message
-|flowMessageFactory
-|log4j2.flowMessageFactory, LOG4J_FLOW_MESSAGE_FACTORY
-|System/Application
-|org.apache.logging.log4j.message.DefaultFlowMessageFactory
-|Default flow message factory used by Loggers.
-
-|SimpleLogger
-|showContextMap
-|log4j2.simplelogShowContextMap, LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP
-|System
-|false
-|If `true`, the full ThreadContext map is included in each SimpleLogger log message.
-
-|SimpleLogger
-|showLogName
-|log4j2.simplelogShowlogname, LOG4J_SIMPLELOG_SHOWLOGNAME
-|System
-|false
-|If `true` the logger name is included in each SimpleLogger log message.
-
-|SimpleLogger
-|showShortLogName
-|log4j2.simplelogShowShortLogname, LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME
-|System
-|true
-|If `true`, only the last component of a logger name is included in SimpleLogger log messages. (E.g.,
-if the logger name is "mycompany.myproject.mycomponent", only "mycomponent" is logged.
-
-|SimpleLogger
-|showDateTime
-|log4j2.simplelogShowdatetime, LOG4J_SIMPLELOG_SHOWDATETIME
-|System
-|false
-|If `true`, SimpleLogger log messages contain timestamp information.
-
-|SimpleLogger
-|dateTimeFormat
-|log4j2.simplelogDateTimeFormat, LOG4J_SIMPLELOG_DATE_TIME_FORMAT
-|System
-|"yyyy/MM/dd HH:mm:ss:SSS zzz"
-|Date-time format to use. Ignored if `SimpleLogger.showDateTime` is `false`.
-
-|SimpleLogger
-|logFile
-|log4j2.simplelogLogFile, LOG4J_SIMPLELOG_LOG_FILE
-|System
-|system.err
-|"system.err" (case-insensitive) logs to System.err, "system.out" (case-insensitive)
-logs to System.out, any other value is interpreted as a file name to save SimpleLogger messages to.
-
-|SimpleLogger
-|level
-|log4j2.simplelogLevel, LOG4J_SIMPLELOG_LEVEL
-|System
-|ERROR
-|Default level for new SimpleLogger instances.
-
-|SimpleLogger
-|statusLoggerLevel
-|log4j2.simplelogStatusLoggerLevel, LOG4J_SIMPLELOG_STATUS_LOGGER_LEVEL
-|System
-|ERROR
-|This property is used to control the initial StatusLogger level, and can be overridden in code by calling
-`StatusLogger.getLogger() .setLevel(someLevel)`. Note that the
-StatusLogger level is only used to determine the status log output level
-until a listener is registered. In practice, a listener is registered
-when a configuration is found, and from that point onwards, status
-messages are only sent to the listeners (depending on their
-statusLevel).
-
-|StatusLogger
-|debug
-|log4j2.debug, LOG4J_DEBUG
-|System/Application
-|false
-|Log4j2 will print all
-internal logging to the console if system property `log4j2.debug` is either
-defined empty or its value equals to `true` (ignoring case).
-
-|StatusLogger
-|entries
-|log4j2.statusEntries, LOG4J_STATUS_ENTRIES
-|System
-|200
-|Number of StatusLogger events that are kept in a buffer and can be retrieved with `StatusLogger.getStatusData()`.
-
-|StatusLogger
-|dateFormat
-|log4j2.statusLoggerDateformat, LOG4J_STATUS_LOGGER_DATEFORMAT
-|System
-|
-|Date-time format string to use as the format for timestamps in the status logger output. See
-`java.text.SimpleDateFormat` for supported formats.
-
-|StatusLogger
-|defaultLevel
-|log4j2.defaultStatusLevel, LOG4J_DEFAULT_STATUS_LEVEL
-|System
-|ERROR
-|The StatusLogger logs events that occur in the logging system to the console. During configuration,
-AbstractConfiguration registers a StatusConsoleListener with the StatusLogger that may redirect status log
-events from the default console output to a file. The listener also
-supports fine-grained filtering. This system property specifies the
-default status log level for the listener to use if the configuration
-does not specify a status level.
-
-Note: this property is used by the log4j-core implementation only after a configuration file has been found.
-
-|StatusLogger
-|level
-|log4j2.statusLoggerLevel, LOG4J_STATUS_LOGGER_LEVEL
-|System
-|WARN
-|The initial "listenersLevel" of the StatusLogger. If StatusLogger listeners are added, the
-"listenerLevel" is changed to that of the most verbose listener. If any listeners are
-registered, the listenerLevel is used to quickly determine if an interested listener exists.
-
-By default, StatusLogger listeners are added when a configuration is
-found and by the JMX StatusLoggerAdmin MBean. For example, if a
-configuration contains `<Configuration status="trace">`, a listener with
-statusLevel TRACE is registered and the StatusLogger listenerLevel is
-set to TRACE, resulting in verbose status messages displayed on the
-console.
-
-If no listeners are registered, the listenersLevel is not used, and the
-StatusLogger output level is determined by
-`StatusLogger.getLogger().getLevel()` (see property
-`org.apache.logging.log4j.simplelog .StatusLogger.level`).
-
-|ThreadContext
-|enable
-|
-|System
-|true
-|If `false`,the ThreadContext stack and map are disabled. (May be ignored if a
-custom ThreadContext map is specified.) NOTE - this setting changed from `log4j2.disableThreadContext`
-in 2.x so cannot be mapped to 3.0 since it has the opposite meaning.
-
-|ThreadContext
-|enableStack
-|
-|System
-|false
-|If `false`, the ThreadContext stack is disabled. NOTE - this setting changed from
-`log4j2.disableThreadContextStack` in 2.x so cannot be mapped to 3.0 since it has the opposite meaning.
-
-|ThreadContext
-|enableMap
-|
-|System
-|false
-|If `false`, the ThreadContext map is disabled. (May be ignored if a custom ThreadContext map is specified.)
-NOTE - this setting changed from `log4j2.disableThreadContextMap` in 2.x so cannot be mapped to 3.0
-since it has the opposite meaning.
-
-|ThreadContext
-|garbageFree
-|log4j2.garbagefreeThreadContextMap, LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP
-|System
-|false
-|Specify "true" to make the ThreadContext map garbage-free.
-
-|ThreadContext
-|mapClass
-|log4j2.threadContextMap, LOG4J_THREAD_CONTEXT_MAP
-|System
-|
-|Fully specified
-class name of a custom `ThreadContextMap` implementation class.
-
-|ThreadContext
-|mapInheritable
-|log4j2.isThreadContextMapInheritable, LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE
-|System
-|false
-|If `true` use a `InheritableThreadLocal` to implement the ThreadContext map. Otherwise, use a plain `ThreadLocal`.
-(May be ignored if a custom ThreadContext map is specified.)
-
-|Unbox
-|ringBufferSize
-|log4j2.unboxRingbufferSize, LOG4J_UNBOX_RINGBUFFER_SIZE
-|System
-|32
-|The `org.apache.logging.log4j.util.Unbox` utility manages a small
-thread-local ring buffer of StringBuilders. Each time one of the `box()`
-methods is called, the next slot in the ring buffer is used, until the
-ring buffer is full and the first slot is reused. By default the Unbox
-ring buffer has 32 slots, so user code can have up to 32 boxed
-primitives in a single logger call.
-
-If more slots are required, set system property
-`Unbox.ringBufferSize` to the desired ring buffer size. Note that
-the specified number will be rounded up to the nearest power of 2.
-
-
-|Web
-|isWebApp
-|log4j2.isWebapp, LOG4J_IS_WEBAPP
-|System
-|true if `Servlet` class on class path
-|This system property can be used to force Log4j 2 to behave as if it is part of a web application (when true) or
-as if it is not part of a web application (when false).
+Users that use shading in their applications should take care of removing all `META-INF/log4j/propertyMapping.json`
+resources and use only Log4j 3 property names.
+====
 
-|===
+[WARNING]
+====
+Since Log4j Core 3 uses Log4j API 2 to support **global** configuration properties, these properties are looked up using a fuzzy matching algorithm.
 
-The table below lists these properties that are included as part of the Log4j Implementation along with their
-default value and a description of what they control. The component identifies tha category the property
-fits into, the alias includes values from Log4j 2.x that are still allowed, the Scope identifies whether
-the setting may be applied system wide and/or to a LoggerContext.
+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:
 
-.Log4j 2 Core configuration properties
-[cols="1,1,3,1,2,3"]
-|===
-|Component Name |Property Key |Alias |Scope |Default Value |Description
-
-
-|AsyncLogger
-|discardThreshold
-|log4j2.discardThreshold, LOG4J_DISCARD_THRESHOLD
-|System
-|INFO
-|Used by the DiscardingAsyncQueueFullPolicy to determine which events to drop when the queue becomes full.
-By default, `INFO`, `DEBUG` and `TRACE` level events are discarded when the queue is full. This property only has
-effect if `Discard` is specified as the `AsyncLogger.QueueFullPolicy`.
-
-|AsyncLogger
-|exceptionHandler
-|log4j2.asyncLoggerExceptionHandler, LOG4J_ASYNC_LOGGER_EXCEPTION_HANDLER
-|System
-|default handler
-|See link:async.html#SysPropsAllAsync[Async Logger System Properties] for details.
-
-|AsyncLogger
-|formatMsg
-|log4j2.formatMsgAsync, LOG4J_FORMAT_MSG_ASYNC
-|System
-|false
-|If `false` (the default), Log4j will make sure the message is formatted in the caller thread, to ensure the
-value at the time of the call to the logger is the value that is logged.
-
-|AsyncLogger
-|queueFullPolicy
-|log4j2.asyncQueueFullPolicy, LOG4J_ASYNC_QUEUE_FULL_POLICY
-|System
-|
-|Used by Async Loggers and the AsyncAppender to maintain application throughput even when the underlying
-appender cannot keep up with the logging rate and the queue is filling up.
-
-If no value is specified (the default) events are never discarded. If the queue is full, the logger call blocks
-until the event can be added to the queue.
-
-Specify `Discard` to drop events whose level is equal or less than the threshold level (INFO by default) when
-the queue is full.
-
-|AsyncLogger
-|retries
-|log4j2.asyncLoggerRetries, LOG4J_ASYNC_LOGGER_RETRIES
-|System
-|200
-|See link:async.html#SysPropsAllAsync[Async Logger System Properties] for details.
-
-|AsyncLogger
-|ringBufferSize
-|log4j2.asyncLoggerRingBufferSize, LOG4J_ASYNC_LOGGER_RING_BUFFER_SIZE
-|System
-|256 * 1024 or 4 * 1024 in garbage-free mode
-|See link:async.html#SysPropsAllAsync[Async Logger System Properties] for details.
-
-|AsyncLogger
-|sleepTimeNS
-|log4j2.asyncLoggerSleepTimeNs, LOG4J_ASYNC_LOGGER_SLEEP_TIME_NS
-|System
-|100
-|See link:async.html#SysPropsAllAsync[Async Logger System Properties] for details.
-
-|AsyncLogger
-|timeout
-|log4j2.asyncLoggerTimeout, LOG4J_ASYNC_LOGGER_TIMEOUT
-|System
-|10
-|See link:async.html#SysPropsAllAsync[Async Logger System Properties] for details.
-
-|AsyncLogger
-|waitStrategy
-|log4j2.asyncLoggerWaitStrategy, LOG4J_ASYNC_LOGGER_WAIT_STRATEGY
-|System
-|Timeout
-|See link:async.html#SysPropsAllAsync[Async Logger System Properties] for details.
-
-|AsyncLogger
-|syncronizeEnqueueWhenQueueFull
-|AsyncLogger.SynchronizeEnqueueWhenQueueFull, ASYNC_LOGGER_SYNCHRONIZE_ENQUEUE_WHEN_QUEUE_FULL
-|System
-|true
-|See link:async.html#SysPropsAllAsync[Async Logger System Properties] for details.
-
-|AsyncLogger
-|threadNameStrategy
-|log4j2.asyncLoggerThreadNameStrategy, LOG4J_ASYNC_LOGGER_THREAD_NAME_STRATEGY
-|System
-|CACHED
-|See link:async.html#SysPropsAllAsync[Async Logger System Properties] for details.
-
-|AsyncLoggerConfig
-|exceptionHandler
-|log4j2.asyncLoggerConfigExceptionHandler, LOG4J_ASYNC_LOGGER_CONFIG_EXCEPTION_HANDLER
-|System
-|default handler
-|See link:async.html#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details.
-
-|AsyncLoggerConfig
-|ringBufferSize
-|log4j2.asyncLoggerConfigRingBufferSize, LOG4J_ASYNC_LOGGER_CONFIG_RING_BUFFER_SIZE
-|System
-|256 * 1024 or 4 * 1024 in garbage-free mode
-|See link:async.html#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details.
-
-|AsyncLoggerConfig
-|waitStrategy
-|log4j2.asyncLoggerConfigWaitStrategy, LOG4J_ASYNC_LOGGER_CONFIG_WAIT_STRATEGY
-|System
-|Timeout
-|See link:async.html#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details.
-
-|AsyncLoggerConfig
-|timeout
-|log4j2.asyncLoggerConfigTimeout, LOG4J_ASYNC_LOGGER_CONFIG_TIMEOUT
-|System
-|10
-|See link:async.html#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details.
-
-|AsyncLoggerConfig
-|sleepTimeNS
-|log4j2.asyncLoggerConfigSleepTimeNs, LOG4J_ASYNC_LOGGER_CONFIG_SLEEP_TIME_NS
-|System
-|100
-|See link:async.html#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details.
-
-|AsyncLoggerConfig
-|retries
-|log4j2.asyncLoggerConfigRetries, LOG4J_ASYNC_LOGGER_CONFIG_RETRIES
-|System
-|200
-|See link:async.html#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details.
-
-|AsyncLoggerConfig
-|synchronizeEnqueueWhenQueueFull
-|AsyncLoggerConfig.SynchronizeEnqueueWhenQueueFull, ASYNC_LOGGER_CONFIG_SYNCHRONIZE_ENQUEUE_WHEN_QUEUE_FULL
-|System
-|true
-|See link:async.html#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details.
-
-|Configuration
-|allowedProtocols
-|log4j2.Configuration.allowedProtocols, LOG4J_CONFIGURATION_ALLOWED_PROTOCOLS
-|System/Application
-| 
-|A comma separated list of the protocols that may be used to load a configuration file. The default is https.
-To completely prevent accessing the configuration via a URL specify a value of "_none".
-
-|Configuration
-|authorizationProvider
-|log4j2.Configuration.authorizationProvider, LOG4J_CONFIGURATION_AUTHORIZATION_PROVIDER
-|System/Application
-|org.apache.logging.log4j.core.util.BasicAuthorizationProvider
-|The fully qualified class name of the AuthorizationProvider.
-
-|Configuration
-|clock
-|log4j2.clock, LOG4J_CLOCK
-|System/Application
-|SystemClock
-|Implementation of the `org.apache.logging.log4j .core.time.Clock` interface that is
-used for timestamping the log events. +
-By default, `System.currentTimeMillis` is called on every log event. +
-You can also specify a fully qualified class name of a custom class that implements the `Clock` interface.
-
-|Configuration
-|factory
-|log4j2.configurationFactory, LOG4J_CONFIGURATION_FACTORY
-|System/Application
-| 
-|Fully specified class name of a classextending
-`org.apache.logging.log4j.core .config.ConfigurationFactory`.
-If specified, an instance of this class is added to the list ofconfiguration factories.
-
-|Configuration
-|File
-|log4j2.configurationFile, LOG4J_CONFIGURATION_FILE
-|System
-| 
-|Path to an Log4j 2 configuration file. May
-also contain a comma separated list of configuration file names. May contain a URL.
-When specified as a URL the "override" query parameter may be used to specify additional
-configuration file locations.
-
-|Configuration
-|jansiEnabled
-|NBSP
-|System/Application
-|false
-|If `false`, the ConsoleAppender will not try to use the Jansi output stream on Windows.
-NOTE - this setting was named `log4j2.skipJansi in 2.x so cannot be mapped to 3.0 since it has the opposite meaning.
-
-|Configuration
-|mergeStrategy
-|log4j2.mergeStrategy, LOG4J_MERGE_STRATEGY
-|System/Application
-| 
-|The name of the class that implements the MergeStrategy interface. If not
-specified `DefaultMergeStrategy` will be used when creating a CompositeConfiguration.
-
-|Configuration
-|password
-|log4j2.Configuration.password, LOG4J_CONFIGURATION_PASSWORD
-|System/Application
-| 
-|The password required to access the remote logging configuration file.
-
-|Configuration
-|passwordDecryptor
-|log4j2.Configuration.passwordDecryptor, LOG4J_CONFIGURATION_DECRYPTOR
-|System/Application
-| 
-|If the password is encrypted this class will be used to decrypt it.
-
-|Configuration
-|userName
-|log4j2.Configuration.username, LOG4J_CONFIGURATION_USERNAME
-|System/Application
-| 
-|The user name required to access the remote logging configuration file.
-
-|Configuration
-|usePreciseClock
-|log4j2.usePreciseClock, LOG4J_USE_PRECISE_CLOCK
-|System/Application
-|false
-|When false the clock resolution will be in milliseconds. When true it will use the smallest granularity supported by
-the JVM. The precise clock is not garbage free. This setting only applies when Log4j's default SystemClock is used.
-
-|Configuration
-|level
-|log4j2.level, LOG4J_LEVEL
-|System/Application
-|ERROR
-|Log level of the default configuration. The default configuration is used if the ConfigurationFactory
-could not successfully create a configuration (e.g. no log4j2.xml file was found).
-
-|GC
-|enableDirectEncoders
-|log4j2.enableDirectEncoders, LOG4J_ENABLE_DIRECT_ENCODERS
-|System/Application
-|true
-|This property can be used to force
-garbage-aware Layouts and Appenders to revert to the pre-2.6 behaviour
-where converting log events to text generates temporary objects like
-Strings and char[] arrays, and converting this text to bytes generates
-temporary byte[] arrays. By default, this property is `true` and
-garbage-aware Layouts and Appenders that convert log events to text will
-convert this text to bytes without creating temporary objects.
-
-|GC
-|layoutStringBuilderMaxSize
-|log4j2.layoutStringBuilderMaxSize, LOG4J_LAYOUT_STRING_BUILDER_MAX_SIZE
-|System/Application
-|2048
-|This property determinesthe maximum size of the thread-local reusable StringBuilders used to
-format the log event to text by Layouts that extend AbstractStringLayout.
-
-
-|JMX
-|enabled
-|NBSP
-|System/Application
-|true
-|If `false`, Log4j configuration objects like LoggerContexts, Appenders, Loggers, etc. will not be instrumented
-with MBeans and cannot be remotely monitored and managed. NOTE - this setting was `log4j2.disableJmx` in 2.x
-so cannot be mapped to 3.0 since it has the opposite meaning.
-
-|JMX
-|notifyAsync
-|log4j2.jmxNotifyAsync, LOG4J_JMX_NOTIFY_ASYNC
-|System/Application
-|false for web apps, true otherwise
-|If `true`, log4j's JMX notifications are sent from a separate background thread,
-otherwise they are sent from the caller thread. If system property
-`Web.isWebApp` is `true` or the `javax.servlet.Servlet` class is on
-the classpath, the default behaviour is to use the caller thread to send
-JMX notifications.
-
-|JNDI
-|contextSelector
-|NBSP
-|System/Application
-|false
-|When true, the JndiContextSelector is enabled if the log4j-jndi jar is present on the classpath.
-
-|JNDI
-|enableJDBC
-|NBSP
-|System/Application
-|false
-|When true, the use of JNDI the JdbcAppender is enabled if the log4j-jndi jar is present on the classpath.
-
-|JNDI
-|enableJMS
-|NBSP
-|System/Application
-|false
-|When true, the use of JNDI the JMS Appender is enabled if the log4j-jndi and log4j-jakarta-jms jars are present on the
-classpath.
-
-|JNDI
-|enableLookup
-|NBSP
-|System/Application
-|false
-|When true, the use of JndiLookup is enabled if the log4j-jndi jar is present on the classpath.
-
-|LoggerContext
-|selector
-|log4j2.contextSelector, LOG4J_CONTEXT_SELECTOR
-|System
-|ClassLoaderContextSelector
-|Creates the `LoggerContext`s. An
-application can have one or more active LoggerContexts depending on the
-circumstances. See link:logsep.html[Log Separation] for more details.
-Available context selector implementation classes: +
-`org.apache.logging.log4j.core.async .AsyncLoggerContextSelector` -
-makes link:async.html[all loggers asynchronous]. +
-`org.apache.logging.log4j.core.async .BasicAsyncLoggerContextSelector` -
-makes link:async.html[all loggers asynchronous] using a single shared
-AsyncLoggerContext. +
-`org.apache.logging.log4j.core.selector .BasicContextSelector` - creates
-a single shared LoggerContext. +
-`org.apache.logging.log4j.core.selector .ClassLoaderContextSelector` -
-separate LoggerContexts for each web application. +
-`org.apache.logging.log4j.core.selector .JndiContextSelector` - use JNDI
-to locate each web application's LoggerContext. +
-`org.apache.logging.log4j.core.osgi .BundleContextSelector` - separate
-LoggerContexts for each OSGi bundle.
-
-|Logger
-|logEventFactory
-|log4j2.logEventFactory, LOG4J_LOG_EVENT_FACTORY
-|System/Application
-|org.apache.logging.log4j.core.impl .DefaultLogEventFactory
-|Factory class used by LoggerConfig to create `LogEvent` instances. (Ignored when
-the `AsyncLoggerContextSelector` is used.)
-
-|LoggerContext
-|shutdownHookEnabled
-|log4j2.shutdownHookEnabled, LOG4J_SHUTDOWN_HOOK_ENABLED
-|System/Application
-|true
-|Overrides the global flag forwhether or not a shutdown hook should be used to stop a
-`LoggerContext`. By default, this is enabled and can be
-disabled on a per-configuration basis. When running with the `log4j-jakarta-web`
-module, this is automatically disabled.
-
-|LoggerContext
-|shutdownCallbackRegistry
-|log4j2.shutdownCallbackRegistry, LOG4J_SHUTDOWN_CALLBACK_REGISTRY
-|System/Application
-|org.apache.logging.log4j.core.util.DefaultShutdownCallbackRegistry
-|Fully specified class name of a class implementing
-link:../log4j-core/apidocs/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry.html[ShutdownCallbackRegistry].
-If specified, an instance of this class is used instead of `DefaultShutdownCallbackRegistry`. The specified class
-must have a default constructor.
-
-|LoggerContext
-|stackTraceOnStart
-|log4j2.loggerContextStacktraceOnStart, LOG4J_LOGGER_CONTEXT_STACKTRACE_ON_START
-|System/Application
-|false
-|Prints a stacktrace to the status logger at DEBUG level when the
-LoggerContext is started. For debug purposes.
-
-|TransportSecurity
-|keyStoreLocation
-|log4j2.keyStoreLocation, LOG4J_KEY_STORE_LOCATION
-|System
-|
-|The location of the key store. If not provided the default key store will be used.
-
-|TransportSecurity
-|keyStorePassword
-|log4j2.keyStorePassword, LOG4J_KEY_STORE_PASSWORD
-|System
-|
-|Password needed to access the trust store.
-
-|TransportSecurity
-|keyStorePasswordFile
-|log4j2.keyStorePasswordFile, LOG4J_KEY_STORE_PASSWORD_FILE
-|System
-|
-|The location of a file that contains the password for the key store.
-
-|TransportSecurity
-|keyStorePasswordEnvironmentVariable
-|log4j2.keyStorePasswordEnvironmentVariable, LOG4J_KEY_STORE_PASSWORD_ENVIRONMENT_VARIABLE
-|System
-|
-|The name of the environment variable that contains the key store password.
-
-|TransportSecurity
-|keyStoreType
-|log4j2.keyStoreType, LOG4J_KEY_STORE_TYPE
-|System
-|
-|The type of key store used for the trust store.
-
-|TransportSecurity
-|keyStoreKeyManagerFactoryAlgorithm
-|log4j2.keyStoreKeyManagerFactoryAlgorithm, LOG4J_KEY_STORE_KEY_MANAGER_FACTORY_ALGORITHM
-|System
-|
-|Java cryptographic algorithm.
-
-|TransportSecurity
-|sslVerifyHostName
-|log4j2.sslVerifyHostName, LOG4J_SSL_VERIFY_HOSTNAME
-|System/Application
-|false
-|true or false if the host name should be verified
-
-|TransportSecurity
-|trustStoreLocation
-|log4j2.trustStoreLocation, LOG4J_TRUST_STORE_LOCATION
-|System
-|
-|The location of the trust store. If not provided the default trust store will be used.
-
-|TransportSecurity
-|trustStorePassword
-|log4j2.trustStorePassword, LOG4J_TRUST_STORE_PASSWORD
-|System
-|
-|Password needed to access the trust store.
-
-|TransportSecuirty
-|trustStorePasswordFile
-|log4j2.trustStorePasswordFile, LOG4J_TRUST_STORE_PASSWORD_FILE
-|System
-|
-|The location of a file that contains the password for the trust store.
-
-|TransportSecuirty
-|trustStorePasswordEnvironmentVariable
-|log4j2.trustStorePasswordEnvironmentVariable, LOG4J_TRUST_STORE_PASSWORD_ENVIRONMENT_VARIABLE
-|System
-|
-|The name of the environment variable that contains the trust store password.
-
-|TransportSecurity
-|trustStoreType
-|log4j2.trustStoreType, LOG4J_TRUST_STORE_TYPE
-|System
-|
-|The type of key store used for the trust store.
-
-|TransportSecurity
-|trustStoreKeyManagerFactoryAlgorithm
-|log4j2.trustStoreKeyManagerFactoryAlgorithm, LOG4J_TRUST_STORE_KEY_MANAGER_FACTORY_ALGORITHM
-|System
-|
-|Java cryptographic algorithm.
-
-|UUID
-|sequence
-|log4j2.uuidSequence, LOG4J_UUID_SEQUENCE
-|System
-|0
-|System property that may be used to seed the UUID generation with an integer value.
+* `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.
+====
 
-The table below lists the properties that are included as part of the Log4j JUL component along with their
-default value and a description of what they control. The component identifies tha category the property
-fits into, the alias includes values from Log4j 2.x that are still allowed, the Scope identifies whether
-the setting may be applied system wide and/or to a LoggerContext.
+[id=properties-meta]
+== Meta configuration properties
 
-.Log4j 3 JUL properties
-[cols="1,1,3,1,2,3"]
-|===
-|Component Name |Property Key |Alias |Scope |Default Value |Description
-
-|JUL
-|loggerAdapter
-|log4j2.julLoggerAdapter, LOG4J_JUL_LOGGER_ADAPTER
-|System
-|org.apache.logging.log4j .jul.ApiLoggerAdapter
-|Default LoggerAdapter to use in the JUL adapter.
-By default, if log4j-core is available, then the class `org.apache.logging.log4j.jul .CoreLoggerAdapter` will be used.
-Otherwise, the `ApiLoggerAdapter` will be used. Custom implementations
-must provide a public default constructor.
+In order to rapidly optimize Log4j Core for a particular usage, you can use the following properties:
 
-|===
+include::partial$manual/systemproperties/properties-meta.adoc[leveloffset=+1]
+
+[id=properties-log4j-api]
+== Log4j API properties
+
+In order to configure Log4j API, see the
+link:/log4j/2.x/manual/systemproperties.html#properties-log4j-api[Log4j 2 site].
+
+[id=properties-log4j-core]
+== Log4j Core properties
+
+While the only required configuration of the `log4j-core` library is provided by the xref:manual/configuration.adoc[configuration file], the library offers many configuration properties that can be used to finely tune the way it works.
+
+[id=properties-async]
+=== Async components
+
+The behavior of all three async components (`AsyncLogger`, `AsyncLoggerConfig` and `AsyncAppender`) can be tuned using these properties:
+
+include::partial$manual/systemproperties/properties-async.adoc[leveloffset=+2]
+
+[id=properties-properties-context-selector]
+=== Logger context
+
+The
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/LoggerContext.html[LoggerContext]
+is one of the principal Log4j components (see
+xref:manual/architecture.adoc[]), which determines among other things, the way
+link:../javadoc/log4j-api/org/apache/logging/log4j/Logger.html[Logger]s are created.
+
+It can be customized using these properties:
+
+include::partial$manual/systemproperties/properties-logger-context.adoc[leveloffset=+2]
+
+[id=properties-configuration-factory]
+=== 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 <<properties-transport-security>> for details.
+====
+
+include::partial$manual/systemproperties/properties-configuration-factory.adoc[leveloffset=+2]
+
+[id=properties-message]
+=== Log messages
+
+The way Log4j builds
+link:../javadoc/log4j-api/org/apache/logging/log4j/message/Message.html[Message]s can be customized using these properties:
+
+include::partial$manual/systemproperties/properties-message.adoc[leveloffset=+2]
+
+[id=properties-log-event]
+=== Log events
+
+The way Log4j builds
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/LogEvent.html[LogEvent]s can be customized using these properties:
+
+include::partial$manual/systemproperties/properties-log-event.adoc[leveloffset=+2]
+
+[id=properties-garbage-collection]
+=== Garbage Collection
+
+include::partial$manual/systemproperties/properties-garbage-collection.adoc[leveloffset=+2]
+
+[id=properties-jansi]
+=== 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:
+
+include::partial$manual/systemproperties/properties-jansi.adoc[leveloffset=+2]
 
-The table below lists the properties that are included as part of the Log4j Script component along with their
-default value and a description of what they control. The component identifies tha category the property
-fits into, the alias includes values from Log4j 2.x that are still allowed, the Scope identifies whether
-the setting may be applied system wide and/or to a LoggerContext.
+[id=properties-log4j-core-thread-context]
+=== Thread context
 
-.Log4j 3 Script properties
-[cols="1,1,3,1,2,3"]
+To configure the thread context used by Log4j Core, you can use the following properties:
+
+include::partial$manual/systemproperties/properties-thread-context.adoc[leveloffset=+2]
+
+[id=properties-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:
+
+include::partial$manual/systemproperties/properties-auth.adoc[leveloffset=+2]
+
+include::partial$manual/systemproperties/properties-transport-security.adoc[leveloffset=+2]
+
+[id=properties-log4j-core-misc]
+=== Miscellaneous properties
+
+include::partial$manual/systemproperties/properties-log4j-core-misc.adoc[leveloffset=+2]
+
+[id=properties-other-components]
+== Other components
+
+[id=properties-log4j-async-logger]
+=== Asynchronous Logger properties
+
+Asynchronous loggers support the following additional properties:
+
+include::partial$manual/systemproperties/properties-async-logger.adoc[leveloffset=+2]
+
+[id=properties-jndi-support]
+=== JNDI support
+
+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.
+
+include::partial$manual/systemproperties/properties-log4j-jndi.adoc[leveloffset=+2]
+
+[id=properties-log4j-jul]
+=== JUL-to-Log4j API bridge properties
+
+The JUL-to-Log4j API bridge provides the following configuration properties:
+
+include::partial$manual/systemproperties/properties-log4j-jul.adoc[leveloffset=+2]
+
+[id=properties-log4j-script]
+=== Script support
+
+Script support can be configured using the following properties:
+
+include::partial$manual/systemproperties/properties-log4j-script.adoc[leveloffset=+2]
+
+[id=property-sources]
+== Property sources

Review Comment:
   This section needs to be updated.



-- 
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