This is an automated email from the ASF dual-hosted git repository. pkarwasz pushed a commit to branch doc/2.x/properties in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 820933bd5bdd646e6d1b671eb922ab542b5ba798 Author: Piotr P. Karwasz <[email protected]> AuthorDate: Wed Apr 17 12:27:41 2024 +0200 Revamp property description page 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. --- .../modules/ROOT/pages/manual/_properties.adoc | 1013 ++++++++++++++++++++ .../antora/modules/ROOT/pages/manual/async.adoc | 318 +++--- .../modules/ROOT/pages/manual/configuration.adoc | 644 +------------ .../antora/modules/ROOT/pages/manual/webapp.adoc | 1 + 4 files changed, 1177 insertions(+), 799 deletions(-) diff --git a/src/site/antora/modules/ROOT/pages/manual/_properties.adoc b/src/site/antora/modules/ROOT/pages/manual/_properties.adoc new file mode 100644 index 0000000000..81f45d88cf --- /dev/null +++ b/src/site/antora/modules/ROOT/pages/manual/_properties.adoc @@ -0,0 +1,1013 @@ +//// + 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 + + +| [[log4j2enableDirectEncoders]]`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 a single configuration property: + +.JUL configuration properties +[cols="1,1,5"] +|=== +h| Java Property + +(Environment Variable) +h| Default Value +h| Description + +| [[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`. + +Each property source can define its own naming convention for property names, although most of them support the standard: + +---- +log4j2.camelCasePropertyName +---- + +convention. + +Properties can be overridden by sources with a lower numerical priority (e.g. -100 comes before 100). + +Log4j provides the following implementations: + +.PropertySource priorities and descriptions +[cols="2m,1m,1,1m,5"] +|=== +| Name | Priority | Naming Convention | Module | Description + +| SpringPropertySource +| -100 +| standard +| log4j-spring +| Delegates property resolution to a Spring https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/env/Environment.html[Environment]. See xref:log4j-spring-boot.adoc[] for details. + +| SystemPropertiesPropertySource +| 0 +| standard +| log4j-api +| Resolves properties using Java https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html[System Properties]. + +| EnvironmentPropertySource +| 100 +| **custom** +| log4j-api +a| Resolves properties using environment variables. + +**Warning**: The naming convention of this property source differs from the standard one. +The property name is prefixed with LOG4J_, is in all caps and words are all separated by underscores. + +| PropertyFilePropertySource +| 200 +| standard +| log4j-api +| Resolves properties using all the resources named `log4j2.component.properties` found on the classpath. +This property source should be used to change the default values of an application. +|=== + diff --git a/src/site/antora/modules/ROOT/pages/manual/async.adoc b/src/site/antora/modules/ROOT/pages/manual/async.adoc index fdcece779c..3b8efc401c 100644 --- a/src/site/antora/modules/ROOT/pages/manual/async.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/async.adoc @@ -184,113 +184,105 @@ 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 -|log4j2.asyncLoggerExceptionHandler -|`default handler` +(Environment Variable) +h| Default Value +h| Description + +| [[log4j2.asyncLoggerExceptionHandler]]`log4j2.asyncLogger{zwsp}ExceptionHandler` + +(`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. |=== @@ -370,80 +362,92 @@ 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 + +(Environment Variable) +h| Default Value +h| Description -|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. +| [[log4j2.asyncLoggerConfigExceptionHandler]]`log4j2.asyncLoggerConfig{zwsp}ExceptionHandler` -If not specified, the default exception handler will print a message and +(`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>>. + +|[[log4j2.asyncLoggerConfigTimeout]]`log4j2.asyncLoggerConfig{zwsp}Timeout` + +(`LOG4J_ASYNC_LOGGER_CONFIG_{zwsp}TIMEOUT`) +| `10` +| Timeout in milliseconds of `Timeout` wait strategy (see <<log4j2.asyncLoggerConfigWaitStrategy>>). + +| [[log4j2.asyncLoggerConfigSleepTimeNs]]`log4j2.asyncLoggerConfig{zwsp}SleepTimeNs` + +(`LOG4J_ASYNC_LOGGER_CONFIG_{zwsp}SLEEP_TIME_NS`) +| `100` +| Sleep time in nanoseconds of `Sleep` wait strategy (see <<log4j2.asyncLoggerConfigWaitStrategy>>)). + +| [[log4j2.asyncLoggerConfigRetries]]`log4j2.asyncLoggerConfig{zwsp}Retries` -|log4j2.asyncLoggerConfigSleepTimeNs -|`100` -|Sleep time (in nanoseconds) of `SleepingWaitStrategy`. See -link:#asyncLoggerConfigWaitStrategy[WaitStrategy System Property] for details. +(`LOG4J_ASYNC_LOGGER_CONFIG_{zwsp}RETRIES`) +| `200` +| Total number of spin cycles and `Thread.yield()` cycles of `Sleep` (see <<log4j2.asyncLoggerConfigWaitStrategy>>)). -|log4j2.asyncLoggerConfigRetries -|`200` -|Total number of spin cycles and `Thread.yield()` cycles of `SleepingWaitStrategy`. See -link:#asyncLoggerConfigWaitStrategy[WaitStrategy System Property] for details. +| [[log4j2.asyncLoggerConfigSynchronizeEnqueueWhenQueueFull]]`log4j2.asyncLoggerConfig{zwsp}SynchronizeEnqueueWhenQueueFull` -|AsyncLoggerConfig.SynchronizeEnqueueWhenQueueFull -|`true` +(`LOG4J_ASYNC_LOGGER_CONFIG_{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. +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. |=== diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc index 7e4f33cd9d..ae14df44f8 100644 --- a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc @@ -14,6 +14,7 @@ See the License for the specific language governing permissions and limitations under the License. //// +[#configuration] = Configuration Ralph Goers <[email protected]> @@ -1868,645 +1869,4 @@ public class AwesomeTest { } ---- -[#SystemProperties] -== System Properties - -The Log4j documentation references a number of System Properties that can be used to control various aspects of Log4j 2 behavior. The table below lists these properties along with their default value and a description of what they control. Any spaces present in the property name are for visual flow and should be removed. - -Note that beginning in Log4j 2.10, all system property names have been normalized to follow a consistent naming scheme. While the old property names are still supported for backwards compatibility, it is recommended to update configurations to use the new style. This system is extensible and is enabled through the 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: - -.PropertySource priorities and descriptions -|=== -| 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 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 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.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. -|=== - -The following is a list of available global configuration properties. Note that these can only be set once per JVM process unlike configuration settings available in configuration files. The Property Name column contains the name used in properties files and system properties; Environment Variable for the equivalent environment variable; and Legacy Property Name for the pre-2.10 name. - -.Log4j 2 global configuration properties -|=== -|Property Name (Legacy Property Name) |Environment Variable |Default Value |Description - -| log4j2.configurationFile, log4j.configurationFile) -| LOG4J_CONFIGURATION_FILE -| -| 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. - -| log4j.debug, log4j2.debug -| LOG4J_DEBUG -| -| Log4j2 will print all internal logging to the console if system property -<code>log4j2.debug</code> is either defined empty or its value equals to <code>true</code> (ignoring case). - -| log4j2.mergeStrategy, log4j.mergeStrategy -| LOG4J_MERGE_STRATEGY -| -| - The name of the class that implements the MergeStrategy interface. If not specified - <code>DefaultMergeStrategy</code> will be used when creating a CompositeConfiguration.. - -| log4j.debug, log4j2.debug -| LOG4J_DEBUG -| -| 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). - -| log4j2.mergeStrategy, log4j.mergeStrategy -| LOG4J_MERGE_STRATEGY -| -| The name of the class that implements the MergeStrategy interface. If not specified - `DefaultMergeStrategy` will be used when creating a CompositeConfiguration.. - -| [[contextSelector]]log4j2.contextSelector - ([[Log4jContextSelector]]Log4jContextSelector) -| LOG4J_CONTEXT_SELECTOR -| ClassLoaderContextSelector -| - Creates the `LoggerContext`s. An application can have one or more active LoggerContexts depending - on the circumstances. - See xref:manual/logsep.adoc[Log Separation] for more details. - Available context selector implementation classes:<br> - `org.apache.logging.log4j.core.async .AsyncLoggerContextSelector` - makes xref:manual/async.adoc[all loggers asynchronous].<br> - `org.apache.logging.log4j.core.async .BasicAsyncLoggerContextSelector` - makes xref:manual/async.adoc[all loggers asynchronous] using a single shared AsyncLoggerContext.<br> - `org.apache.logging.log4j.core.selector .BasicContextSelector` - creates a single shared LoggerContext.<br> - `org.apache.logging.log4j.core.selector .ClassLoaderContextSelector` - separate LoggerContexts for each web application.<br> - `org.apache.logging.log4j.core.selector .JndiContextSelector` - use JNDI to locate each web application's LoggerContext.<br> - `org.apache.logging.log4j.core.osgi .BundleContextSelector` - separate LoggerContexts for each OSGi bundle. - -| [[logEventFactory]]log4j2.logEventFactory - ([[Log4jLogEventFactory]]Log4jLogEventFactory) -| LOG4J_LOG_EVENT_FACTORY -| org.apache.logging.log4j.core.impl .DefaultLogEventFactory -| - Factory class used by LoggerConfig to create `LogEvent` instances. - (Ignored when the `AsyncLoggerContextSelector` is used.) - -| [[loggerContextFactory]]log4j2.loggerContextFactory - ([[log4j2.loggerContextFactory]]log4j2.loggerContextFactory) -| LOG4J_LOGGER_CONTEXT_FACTORY -| org.apache.logging.log4j.simple .SimpleLoggerContextFactory -| - Factory class used by LogManager to bootstrap the logging implementation. - The core jar provides `org.apache.logging.log4j.core - .impl.Log4jContextFactory`. - -| [[configurationFactory]]log4j2.configurationFactory - ([[log4j.configurationFactory]]log4j.configurationFactory) -| LOG4J_CONFIGURATION_FACTORY -| -| - Fully specified class name of a class extending `org.apache.logging.log4j.core - .config.ConfigurationFactory`. - If specified, an instance of this class is added to the list of configuration factories. - -| [[configurationAllowedProtocols]]log4j2.Configuration.allowedProtocols - ([[log4j.configurationAllowedProtocols]]log4j.configurationAllowedProtocols) -| LOG4J_CONFIGURATION_ALLOWED_PROTOCOLS -| -| - A comma separated list of the protocols that may be used to load a configuration file. The default is - "https, file, jar". To completely prevent accessing the configuration via a URL specify a value of "_none". - -| [[log4j2.configurationAuthorizationEncoding]]log4j2.configurationAuthorizationEncoding -| LOG4J_CONFIGURATION_AUTHORIZATION_ENCODING -| UTF-8 -| The encoding used in Basic Authentication (cf. <a class="externalLink" href="https://datatracker.ietf.org/doc/html/rfc7617[RFC 7617]). - -| [[configurationAuthorizationProvider]]log4j2.Configuration.authorizationProvider - ([[log4j.configurationAuthorizationProvider]]log4j.configurationAuthorizationProvider -| LOG4J_CONFIGURATION_AUTHORIZATION_PROVIDER -| org.apache.logging.log4j.core.util.BasicAuthorizationProvider -| The fully qualified class name of the AuthorizationProvider. - -| [[configurationPassword]]log4j2.Configuration.password - ([[log4j.configurationPassword]]log4j.configurationPassword -| LOG4J_CONFIGURATION_PASSWORD -| -| The password required to access the remote logging configuration file. - -| [[configurationPasswordDecryptor]]log4j2.Configuration.passwordDecryptor - ([[log4j.configurationPasswordDecryptor]]log4j.configurationPasswordDecryptor -| LOG4J_CONFIGURATION_PASSWORD_DECRYPTOR -| -| If the password is encrypted this class will be used to decrypt it. - -| [[configurationUsername]]log4j2.Configuration.username - ([[log4j.configurationUsername]]log4j.configurationUsername -| LOG4J_CONFIGURATION_USERNAME -| -| The user name required to access the remote logging configuration file. - -| [[shutdownHookEnabled]]log4j2.shutdownHookEnabled - ([[log4j.shutdownHookEnabled]]log4j.shutdownHookEnabled) -| LOG4J_SHUTDOWN_HOOK_ENABLED -| true -| - Overrides the global flag for whether 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-web` module, this is automatically disabled. - -| [[shutdownCallbackRegistry]]log4j2.shutdownCallbackRegistry - ([[log4j.shutdownCallbackRegistry]]log4j.shutdownCallbackRegistry) -| LOG4J_SHUTDOWN_CALLBACK_REGISTRY -| org.apache.logging.log4j.core.util .DefaultShutdownCallbackRegistry -| - Fully specified class name of a class implementing - link:../javadoc/log4j-core/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry.html" class="javadoc[ShutdownCallbackRegistry]. - If specified, an instance of this class is used instead of `DefaultShutdownCallbackRegistry`. - The specified class must have a default constructor. - -| [[clock]]log4j2.clock - ([[log4j.Clock]]log4j.Clock) -| LOG4J_CLOCK -| SystemClock -| - Implementation of the `org.apache.logging.log4j .core.util.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. - -| [[level]]log4j2.level - ([[org.apache.logging.log4j.level]]org.apache.logging.log4j.level) -| LOG4J_LEVEL -| 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). - -| [[disableThreadContext]]log4j2.disableThreadContext - (disableThreadContext) -| LOG4J_DISABLE_THREAD_CONTEXT -| false -| If `true`, the ThreadContext stack and map are disabled. (May be ignored if a custom ThreadContext map is specified.) - -| [[disableThreadContextStack]]log4j2.disableThreadContextStack - (disableThreadContextStack) -| LOG4J_DISABLE_THREAD_CONTEXT_STACK -| false -| If `true`, the ThreadContext stack is disabled. - -| [[disableThreadContextMap]]log4j2.disableThreadContextMap - (disableThreadContextMap) -| LOG4J_DISABLE_THREAD_CONTEXT_MAP -| false -| If `true`, the ThreadContext map is disabled. - (May be ignored if a custom ThreadContext map is specified.) - -| [[log4j2.threadContextMap]]log4j2.threadContextMap - (log4j2.threadContextMap) -| LOG4J_THREAD_CONTEXT_MAP -| -| Fully specified class name of a custom `ThreadContextMap` implementation class. - -| [[isThreadContextMapInheritable]]log4j2.isThreadContextMapInheritable - (isThreadContextMapInheritable) -| LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE -| 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.) - -| [[contextDataInjector]]log4j2.contextDataInjector - ([[log4j2.ContextDataInjector]]log4j2.ContextDataInjector) -| LOG4J_CONTEXT_DATA_INJECTOR -| -| Fully specified class name of a custom `ContextDataInjector` implementation class. - - -| [[garbagefreeThreadContextMap]]log4j2.garbagefreeThreadContextMap - ([[log4j2.garbagefree.threadContextMap]]log4j2.garbagefree.threadContextMap) -| LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP -| false -| Specify "true" to make the ThreadContext map garbage-free. - -| [[disableJmx]]log4j2.disableJmx - ([[log4j2.disable.jmx]]log4j2.disable.jmx) -| LOG4J_DISABLE_JMX -| true -| - If `true`, Log4j configuration objects like LoggerContexts, Appenders, Loggers, etc. - will not be instrumented with MBeans and cannot be remotely monitored and managed. - -| [[jmxNotifyAsync]]log4j2.jmxNotifyAsync - ([[log4j2.jmx.notify.async]]log4j2.jmx.notify.async) -| LOG4J_JMX_NOTIFY_ASYNC -| 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 `log4j2.is.webapp` 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. - -| [[skipJansi]]log4j2.skipJansi - ([[log4j.skipJansi]]log4j.skipJansi) -| LOG4J_SKIP_JANSI -| true -| If `true`, the ConsoleAppender will not try to use the Jansi output stream on Windows. - -| [[ignoreTCL]]log4j2.ignoreTCL - ([[log4j.ignoreTCL]]log4j.ignoreTCL) -| LOG4J_IGNORE_TCL -| 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. - -| [[enableJndiContextSelector]]log4j2.enableJndiContextSelector -| LOG4J_ENABLE_JNDI_CONTEXT_SELECTOR -| false -| When true, the Log4j context selector that uses the JNDI java protocol is enabled. When false, the default, they are disabled. - -| [[enableJndiJdbc]]log4j2.enableJndiJdbc -| LOG4J_ENABLE_JNDI_JDBC -| false -| When true, a Log4j JDBC Appender configured with a `DataSource` which uses JNDI's java protocol is enabled. When false, the default, they are disabled. - -| [[enableJndiJms]]log4j2.enableJndiJms -| LOG4J_ENABLE_JNDI_JMS -| false -| When true, a Log4j JMS Appender that uses JNDI's java protocol is enabled. When false, the default, they are disabled. - -| [[enableJndiLookup]]log4j2.enableJndiLookup -| LOG4J_ENABLE_JNDI_LOOKUP -| false -| When true, a Log4j lookup that uses JNDI's java protocol is enabled. When false, the default, they are disabled. - -| [[uuidSequence]]log4j2.uuidSequence - ([[org.apache.logging.log4j.uuidSequence]]org.apache.logging.log4j.uuidSequence) -| LOG4J_UUID_SEQUENCE -| 0 -| System property that may be used to seed the UUID generation with an integer value. - -| [[simplelogShowContextMap]]log4j2.simplelogShowContextMap - ([[org.apache.logging.log4j.simplelog.showContextMap]]org.apache.logging.log4j .simplelog.showContextMap) -| LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP -| false -| If `true`, the full ThreadContext map is included in each SimpleLogger log message. - -| [[simplelogShowlogname]]log4j2.simplelogShowlogname - ([[org.apache.logging.log4j.simplelog.showlogname]]org.apache.logging.log4j .simplelog.showlogname) -| LOG4J_SIMPLELOG_SHOWLOGNAME -| false -| If `true`, the logger name is included in each SimpleLogger log message. - -| [[simplelogShowShortLogname]]log4j2.simplelogShowShortLogname - ([[org.apache.logging.log4j.simplelog.showShortLogname]]org.apache.logging.log4j .simplelog.showShortLogname) -| LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME -| 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. - -| [[simplelogShowdatetime]]log4j2.simplelogShowdatetime - ([[org.apache.logging.log4j.simplelog.showdatetime]]org.apache.logging.log4j .simplelog.showdatetime) -| LOG4J_SIMPLELOG_SHOWDATETIME -| false -| If `true`, SimpleLogger log messages contain timestamp information. - -| [[simplelogDateTimeFormat]]log4j2.simplelogDateTimeFormat - ([[org.apache.logging.log4j.simplelog.dateTimeFormat]]org.apache.logging.log4j .simplelog.dateTimeFormat) -| LOG4J_SIMPLELOG_DATE_TIME_FORMAT -| "yyyy/MM/dd HH:mm:ss:SSS zzz" -| Date-time format to use. Ignored if `org.apache.logging.log4j .simplelog.showdatetime` is `false`. - -| [[simplelogLogFile]]log4j2.simplelogLogFile - ([[org.apache.logging.log4j.simplelog.logFile]]org.apache.logging.log4j .simplelog.logFile) -| LOG4J_SIMPLELOG_LOG_FILE -| 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. - -| [[simplelogLevel]]log4j2.simplelogLevel - ([[org.apache.logging.log4j.simplelog.level]]org.apache.logging.log4j .simplelog.level) -| LOG4J_SIMPLELOG_LEVEL -| ERROR -| Default level for new SimpleLogger instances. - -| log4j2.simplelog.<loggerName>.level - ([[org.apache.logging.log4j.simplelog.loggerNamelevel]]org.apache.logging.log4j .simplelog.<loggerName>.level) -| LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL -| SimpleLogger default log level -| Log level for a the SimpleLogger instance with the specified name. - -| [[simplelogStatusLoggerLevel]]log4j2.simplelogStatusLoggerLevel - ([[org.apache.logging.log4j.simplelog.StatusLogger.level]]org.apache.logging.log4j.simplelog .StatusLogger.level) -| LOG4J_SIMPLELOG_STATUS_LOGGER_LEVEL -| 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). - -| [[statusLoggerLevel]]log4j2.statusLoggerLevel - ([[log4j2.StatusLogger.level]]log4j2.StatusLogger.level) -| LOG4J_STATUS_LOGGER_LEVEL -| ERROR -| - 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`).</p> - -| [[statusEntries]]log4j2.statusEntries - ([[log4j2.status.entries]]log4j2.status.entries) -| LOG4J_STATUS_ENTRIES -| 200 -| Number of StatusLogger events that are kept in a buffer and can be retrieved with `StatusLogger.getStatusData()`. - -| [[statusLoggerDateformat]]log4j2.statusLoggerDateformat - ([[log4j2.StatusLogger.DateFormat]]log4j2.StatusLogger.DateFormat) -| LOG4J_STATUS_LOGGER_DATEFORMAT -| -| Date-time format string to use as the format for timestamps - in the status logger output. See `java.text.SimpleDateFormat` for supported formats. - -| [[asyncLoggerExceptionHandler]]log4j2.asyncLoggerExceptionHandler - ([[AsyncLogger.ExceptionHandler]]AsyncLogger.ExceptionHandler) -| LOG4J_ASYNC_LOGGER_EXCEPTION_HANDLER -| default handler -| See xref:manual/async.adoc#SysPropsAllAsync[Async Logger System Properties] for details. - -| [[asyncLoggerRingBufferSize]]log4j2.asyncLoggerRingBufferSize - ([[AsyncLogger.RingBufferSize]]AsyncLogger.RingBufferSize) -| LOG4J_ASYNC_LOGGER_RING_BUFFER_SIZE -| 256*1024 or 4*1024 in garbage-free mode -| See xref:manual/async.adoc#SysPropsAllAsync[Async Logger System Properties] for details. - -| [[asyncLoggerWaitStrategy]]log4j2.asyncLoggerWaitStrategy - ([[AsyncLogger.WaitStrategy]]AsyncLogger.WaitStrategy) -| LOG4J_ASYNC_LOGGER_WAIT_STRATEGY -| Timeout -| See xref:manual/async.adoc#SysPropsAllAsync[Async Logger System Properties] for details. - -| [[asyncLoggerTimeout]]log4j2.asyncLoggerTimeout - ([[AsyncLogger.Timeout]]AsyncLogger.Timeout) -| LOG4J_ASYNC_LOGGER_TIMEOUT -| 10 -| See xref:manual/async.adoc#SysPropsAllAsync[Async Logger System Properties] for details. - -| [[asyncLoggerSleepTimeNs]]log4j2.asyncLoggerSleepTimeNs - ([[AsyncLogger.SleepTimeNs]]AsyncLogger.SleepTimeNs) -| LOG4J_ASYNC_LOGGER_SLEEP_TIME_NS -| 100 -| See xref:manual/async.adoc#SysPropsAllAsync[Async Logger System Properties] for details. - -| [[asyncLoggerRetries]]log4j2.asyncLoggerRetries - ([[AsyncLogger.Retries]]AsyncLogger.Retries) -| LOG4J_ASYNC_LOGGER_SLEEP_TIME_NS -| 200 -| See xref:manual/async.adoc#SysPropsAllAsync[Async Logger System Properties] for details. - -| [[AsyncLogger.SynchronizeEnqueueWhenQueueFull]]AsyncLogger.SynchronizeEnqueueWhenQueueFull -| ASYNC_LOGGER_SYNCHRONIZE_ENQUEUE_WHEN_QUEUE_FULL -| true -| See xref:manual/async.adoc#SysPropsAllAsync[Async Logger System Properties] for details. - -| [[asyncLoggerThreadNameStrategy]]log4j2.asyncLoggerThreadNameStrategy - ([[AsyncLogger.ThreadNameStrategy]]AsyncLogger.ThreadNameStrategy) -| LOG4J_ASYNC_LOGGER_THREAD_NAME_STRATEGY -| CACHED -| See xref:manual/async.adoc#SysPropsAllAsync[Async Logger System Properties] for details. - -| [[asyncLoggerConfigExceptionHandler]]log4j2.asyncLoggerConfigExceptionHandler - ([[AsyncLoggerConfig.ExceptionHandler]]AsyncLoggerConfig.ExceptionHandler) -| LOG4J_ASYNC_LOGGER_CONFIG_EXCEPTION_HANDLER -| default handler -| See xref:manual/async.adoc#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details. - -| [[asyncLoggerConfigRingBufferSize]]log4j2.asyncLoggerConfigRingBufferSize - ([[AsyncLoggerConfig.RingBufferSize]]AsyncLoggerConfig.RingBufferSize) -| LOG4J_ASYNC_LOGGER_CONFIG_RING_BUFFER_SIZE -| 256*1024 or 4*1024 in garbage-free mode -| See xref:manual/async.adoc#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details. - -| [[asyncLoggerConfigWaitStrategy]]log4j2.asyncLoggerConfigWaitStrategy - ([[AsyncLoggerConfig.WaitStrategy]]AsyncLoggerConfig.WaitStrategy) -| LOG4J_ASYNC_LOGGER_CONFIG_WAIT_STRATEGY -| Timeout -| See xref:manual/async.adoc#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details. - -| [[AsyncLoggerConfig.SynchronizeEnqueueWhenQueueFull]]AsyncLoggerConfig.SynchronizeEnqueueWhenQueueFull -| ASYNC_LOGGER_CONFIG_SYNCHRONIZE_ENQUEUE_WHEN_QUEUE_FULL -| true -| See xref:manual/async.adoc#SysPropsMixedSync-Async[Mixed Async/Synchronous Logger System Properties] for details. - -| [[julLoggerAdapter]]log4j2.julLoggerAdapter - ([[log4j.jul.LoggerAdapter]]log4j.jul.LoggerAdapter) -| LOG4J_JUL_LOGGER_ADAPTER -| 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. - -| [[formatMsgAsync]]log4j2.formatMsgAsync - ([[log4j.format.msg.async]]log4j.format.msg.async) - -| LOG4J_FORMAT_MSG_ASYNC -| 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. - -| [[asyncQueueFullPolicy]]log4j2.asyncQueueFullPolicy - ([[log4j2.AsyncQueueFullPolicy]]log4j2.AsyncQueueFullPolicy) -| LOG4J_ASYNC_QUEUE_FULL_POLICY -| -| 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. - -| [[discardThreshold]]log4j2.discardThreshold - ([[log4j2.DiscardThreshold]]log4j2.DiscardThreshold) -| LOG4J_DISCARD_THRESHOLD -| 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 `log4j2.AsyncQueueFullPolicy`. - -| [[messageFactory]]log4j2.messageFactory - ([[log4j2.messageFactory]]log4j2.messageFactory) -| LOG4J_MESSAGE_FACTORY -| org.apache.logging.log4j.message. ParameterizedMessageFactory or - org.apache.logging.log4j.message. ReusableMessageFactory in garbage-free mode -| Default message factory used by Loggers if no factory was specified. - -| [[flowMessageFactory]]log4j2.flowMessageFactory - ([[log4j2.flowMessageFactory]]log4j2.flowMessageFactory) -| LOG4J_FLOW_MESSAGE_FACTORY -| org.apache.logging.log4j.message. DefaultFlowMessageFactory -| Default flow message factory used by Loggers. - -| [[isWebapp]]log4j2.isWebapp - ([[log4j2.is.webapp]]log4j2.is.webapp) -| LOG4J_IS_WEBAPP -| 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). - -| [[enableThreadlocals]]log4j2.enableThreadlocals - ([[log4j2.enable.threadlocals]]log4j2.enable.threadlocals) -| LOG4J_ENABLE_THREADLOCALS -| !log4j2.isWebapp -| This system property can be used to switch off the use of those thread locals, which can cause classloader leaks in a web application. -This will partly disable Log4j's garbage-free behaviour: to be fully garbage-free, Log4j stores objects in ThreadLocal fields to reuse them, instead of creating new objects for each log event. - -| [[enableDirectEncoders]]log4j2.enableDirectEncoders - ([[log4j2.enable.direct.encoders]]log4j2.enable.direct.encoders) -| LOG4J_ENABLE_DIRECT_ENCODERS -| 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. - -| [[initialReusableMsgSize]]log4j2.initialReusableMsgSize - ([[log4j.initialReusableMsgSize]]log4j.initialReusableMsgSize) -| LOG4J_INITIAL_REUSABLE_MSG_SIZE -| 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. - -| [[maxReusableMsgSize]]log4j2.maxReusableMsgSize - ([[log4j.maxReusableMsgSize]]log4j.maxReusableMsgSize) -| LOG4J_MAX_REUSABLE_MSG_SIZE -| 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. - -| [[layoutStringBuilderMaxSize]]log4j2.layoutStringBuilderMaxSize - ([[log4j.layoutStringBuilder.maxSize]]log4j.layoutStringBuilder.maxSize) -| LOG4J_LAYOUT_STRING_BUILDER_MAX_SIZE -| 2048 -| This property determines the maximum size of the thread-local reusable StringBuilders - used to format the log event to text by Layouts that extend AbstractStringLayout. - -| [[unboxRingbufferSize]]log4j2.unboxRingbufferSize - ([[log4j.unbox.ringbuffer.size]]log4j.unbox.ringbuffer.size) -| LOG4J_UNBOX_RINGBUFFER_SIZE -| 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 `log4j.unbox.ringbuffer.size` to the desired ring buffer size. - Note that the specified number will be rounded up to the nearest power of 2. - -| [[loggerContextStacktraceOnStart]]log4j2.loggerContextStacktraceOnStart - ([[log4j.LoggerContext.stacktrace.on.start]]log4j.LoggerContext.stacktrace.on.start) -| LOG4J_LOGGER_CONTEXT_STACKTRACE_ON_START -| false -| Prints a stacktrace to the xref:#StatusMessages[status logger] at DEBUG level when the LoggerContext is started. For debug purposes. - -| [[log4j2.trustStoreLocation]]log4j2.trustStoreLocation -| LOG4J_TRUST_STORE_LOCATION -| -| The location of the trust store. If not provided the default trust store will be used. - -| [[log4j2.trustStorePassword]]log4j2.trustStorePassword -| LOG4J_TRUST_STORE_PASSWORD -| -| Password needed to access the trust store. - -| [[log4j2.trustStorePasswordFile]]log4j2.trustStorePasswordFile -| LOG4J_TRUST_STORE_PASSWORD_FILE -| -| The location of a file that contains the password for the trust store. - -| [[log4j2.trustStorePasswordEnvironmentVariable]]log4j2.trustStorePasswordEnvironmentVariable -| LOG4J_TRUST_STORE_PASSWORD_ENVIRONMENT_VARIABLE -| -| The name of the environment variable that contains the trust store password. - -| [[log4j2.trustStoreType]]log4j2.trustStoreType -| LOG4J_TRUST_STORE_TYPE -| -| The type of key store used for the trust store. - -| [[log4j2.trustStoreKeyManagerFactoryAlgorithm]]log4j2.trustStoreKeyManagerFactoryAlgorithm -| LOG4J_TRUST_STORE_KEY_MANAGER_FACTORY_ALGORITHM -| -| Java cryptographic algorithm. - -| [[log4j2.keyStoreLocation]]log4j2.keyStoreLocation -| LOG4J_KEY_STORE_LOCATION -| -| The location of the key store. If not provided the default key store will be used. - -| [[log4j2.keyStorePassword]]log4j2.keyStorePassword -| LOG4J_KEY_STORE_PASSWORD -| -| Password needed to access the key store. - -| [[log4j2.keyStorePasswordFile]]log4j2.keyStorePasswordFile -| LOG4J_KEY_STORE_PASSWORD_FILE -| -| The location of a file that contains the password for the key store. - -| [[log4j2.keyStorePasswordEnvironmentVariable]]log4j2.keyStorePasswordEnvironmentVariable -| LOG4J_KEY_STORE_PASSWORD_ENVIRONMENT_VARIABLE -| -| The name of the environment variable that contains the key store password. - -| [[log4j2.keyStoreType]]log4j2.keyStoreType -| LOG4J_KEY_STORE_TYPE -| | The type of key store. - -| [[log4j2.keyStoreKeyManagerFactoryAlgorithm]]log4j2.keyStoreKeyManagerFactoryAlgorithm -| LOG4J_KEY_STORE_KEY_MANAGER_FACTORY_ALGORITHM -| -| Java cryptographic algorithm. - -| [[log4j2.sslVerifyHostName]]log4j2.sslVerifyHostName -| -| false -| true or false if the host name should be verified - -| [[log4j2.Script.enableLanguages]]log4j2.Script.enableLanguages -| -| -| The list of script languages that are allowed to execute. The names specified must have a ScriptEngine installed - that advertises the same language(s) in order for scripting to be enabled. If no languages are specified, which is - the default, the ScriptManager will not be installed. - -| [[log4j2.disableCloudConfigLoggingSystem]]log4j2.disableCloudConfigLoggingSystem -| -| -| Disables the usage of the Spring Boot `Log4j2CloudConfigLoggingSystem`. Defaults to `false`. - -|=== +include::_properties.adoc[leveloffset=+1] diff --git a/src/site/antora/modules/ROOT/pages/manual/webapp.adoc b/src/site/antora/modules/ROOT/pages/manual/webapp.adoc index 8362d80f7d..2ec1cef20f 100644 --- a/src/site/antora/modules/ROOT/pages/manual/webapp.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/webapp.adoc @@ -140,6 +140,7 @@ When specifying these context parameters, you must specify them in the deploymen </context-param> ---- +[#use-jndi-context-selector] ==== Use the JndiContextSelector [source,xml]
