This is an automated email from the ASF dual-hosted git repository. pkarwasz pushed a commit to branch doc/2.x/configuration in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 553dd7b0c4f16c2e0012d145fdb0a47b8f805c87 Author: Piotr P. Karwasz <[email protected]> AuthorDate: Fri May 10 23:36:59 2024 +0200 Move configuration properties to separate page --- src/site/antora/modules/ROOT/pages/log4j-jul.adoc | 21 +++++++++--- .../pages/log4j-spring-cloud-config-client.adoc | 8 +++-- .../modules/ROOT/pages/manual/appenders.adoc | 2 +- .../antora/modules/ROOT/pages/manual/async.adoc | 6 ++-- .../modules/ROOT/pages/manual/configuration.adoc | 39 +++++++++++++--------- .../pages/manual/configuration/properties.adoc | 4 +-- .../modules/ROOT/pages/manual/garbagefree.adoc | 8 ++--- src/site/antora/modules/ROOT/pages/manual/jmx.adoc | 15 ++++++--- 8 files changed, 66 insertions(+), 37 deletions(-) diff --git a/src/site/antora/modules/ROOT/pages/log4j-jul.adoc b/src/site/antora/modules/ROOT/pages/log4j-jul.adoc index c0d869e14e..e141ea0613 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-jul.adoc +++ b/src/site/antora/modules/ROOT/pages/log4j-jul.adoc @@ -35,15 +35,28 @@ This must be done either through the command line (i.e., using the `-Djava.util. == Compatibility -The use of a http://docs.oracle.com/javase/6/docs/api/java/util/logging/Filter.html[`java.util.logging.Filter`] is supported on a per-http://docs.oracle.com/javase/6/docs/api/java/util/logging/Logger.html[`Logger`] basis. +The use of a +https://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Filter.html[java.util.logging.Filter] +is supported on a +https://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Logger.html[per-Logger] +basis. However, it is recommended to use the standard xref:manual/filters.adoc[Filters] feature in Log4j instead. -The use of http://docs.oracle.com/javase/6/docs/api/java/util/logging/Handler.html[`java.util.logging.Handler`] classes is _NOT_ supported. -Custom Handlers should instead use an appropriate xref:manual/appenders.adoc[Appender] or code their own link:javadoc/log4j-core/org/apache/logging/log4j/core/Appender.adoc[`Appender`] plugin. +The use of +https://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Handler.html[java.util.logging.Handler] +classes is +_NOT_ supported. +Custom Handlers should instead use an appropriate +xref:manual/appenders.adoc[Appender] +or code their own +link:../javadoc/log4j-core/org/apache/logging/log4j/core/Appender.html[Appender] +plugin. Java logging levels are translated into Log4j logging levels dynamically. The following table lists the conversions between a Java logging level and its equivalent Log4j level. -Custom levels should be implemented as an implementation of `LevelConverter`, and the Log4j property xref:manual/configuration.adoc#log4j2.julLevelConverter[log4j2.julLevelConverter] must be set to your custom class name. +Custom levels should be implemented as an implementation of `LevelConverter`, and the Log4j property +xref:manual/configuration/properties.adoc#log4j2.julLevelConverter[log4j2.julLevelConverter] +must be set to your custom class name. Using the default `LevelConverter` implementation, custom logging levels are mapped to whatever the current level of the `Logger` being logged to is using. [#default-level-conversions] diff --git a/src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc b/src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc index dd81aa136e..5eca408a29 100644 --- a/src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc +++ b/src/site/antora/modules/ROOT/pages/log4j-spring-cloud-config-client.adoc @@ -24,7 +24,9 @@ Spring Boot applications initialize logging 3 times. . SpringApplication declares a Logger. This Logger will be initialized using Log4j's "normal" mechanisms. -Thus the xref:manual/configuration.adoc#log4j2.configurationFile[`log4j2.configurationFile`] system property will be checked to see if a specific configuration file has been provided, otherwise it will search for a configuration file on the classpath. +Thus, the +xref:manual/configuration/properties.adoc#log4j2.configurationFile[`log4j2.configurationFile`] +system property will be checked to see if a specific configuration file has been provided, otherwise it will search for a configuration file on the classpath. The property may also be declare in log4j2.component.properties. == Usage @@ -122,7 +124,9 @@ logging: Note that Log4j currently does not directly support encrypting the password. However, Log4j does use Spring's standard APIs to access properties in the Spring configuration so any customizations made to Spring's property handling would apply to the properties Log4j uses as well. -If more extensive authentication is required an `AuthorizationProvider` can be implemented and its fully qualified class name should be specified in the xref:manual/configuration.adoc#log4j2.configurationAuthorizationProvider[log4j2.configurationAuthorizationProvider] system property, in log4j2.component.properties or in Spring's `bootstrap.yml` using either the `log4j2.authorizationProvider` or `logging.auth.authorizationProvider` key. +If more extensive authentication is required an `AuthorizationProvider` can be implemented and its fully qualified class name should be specified in the +xref:manual/configuration/properties.adoc#log4j2.configurationAuthorizationProvider[log4j2.configurationAuthorizationProvider] +system property, in log4j2.component.properties or in Spring's `bootstrap.yml` using either the `log4j2.authorizationProvider` or `logging.auth.authorizationProvider` key. For the properties required by TLS configuration see xref:manual/configuration.adoc#transport-security[the Transport Security configuration]. diff --git a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc index 95e7c6fea8..1431c9b49d 100644 --- a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc @@ -120,7 +120,7 @@ There are also a few system properties that can be used to maintain application throughput even when the underlying appender cannot keep up with the logging rate and the queue is filling up. See the details for system properties -xref:manual/configuration.adoc#log4j2.AsyncQueueFullPolicy[`log4j2.AsyncQueueFullPolicy` +xref:manual/configuration/properties.adoc#log4j2.asyncQueueFullPolicy[`log4j2.AsyncQueueFullPolicy` and `log4j2.DiscardThreshold`]. A typical AsyncAppender configuration might look like: diff --git a/src/site/antora/modules/ROOT/pages/manual/async.adoc b/src/site/antora/modules/ROOT/pages/manual/async.adoc index a727e64fb5..53e8e9f24f 100644 --- a/src/site/antora/modules/ROOT/pages/manual/async.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/async.adoc @@ -117,7 +117,7 @@ classpath. Prior to Log4j-2.9, disruptor-3.0.0.jar or higher was required._ This is simplest to configure and gives the best performance. -To make all loggers asynchronous, add the disruptor jar to the classpath and set the system property xref:manual/configuration.adoc#log4j2.contextSelector[log4j2.contextSelector] to `org.apache.logging.log4j.core.async.AsyncLoggerContextSelector` or `org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector`. +To make all loggers asynchronous, add the disruptor jar to the classpath and set the system property xref:manual/configuration/properties.adoc#log4j2.contextSelector[log4j2.contextSelector] to `org.apache.logging.log4j.core.async.AsyncLoggerContextSelector` or `org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector`. By default, link:#Location[location] is not passed to the I/O thread by asynchronous loggers. If one of your layouts or custom filters needs @@ -183,7 +183,7 @@ There are also a few system properties that can be used to maintain application throughput even when the underlying appender cannot keep up with the logging rate and the queue is filling up. See the details for system properties -xref:manual/configuration.adoc#log4j2.asyncQueueFullPolicy[`log4j2.asyncQueueFullPolicy` +xref:manual/configuration/properties.adoc#log4j2.asyncQueueFullPolicy[`log4j2.asyncQueueFullPolicy` and `log4j2.discardThreshold`]. [#MixedSync-Async] @@ -257,7 +257,7 @@ There are also a few system properties that can be used to maintain application throughput even when the underlying appender cannot keep up with the logging rate and the queue is filling up. See the details for system properties -xref:manual/configuration.adoc#log4j2.asyncQueueFullPolicy[`log4j2.asyncQueueFullPolicy` +xref:manual/configuration/properties.adoc#log4j2.asyncQueueFullPolicy[`log4j2.asyncQueueFullPolicy` and `log4j2.discardThreshold`]. [#custom-waitstrategy] diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc index 770694bd8b..3f64c8b866 100644 --- a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc @@ -29,7 +29,7 @@ Since version 2.0 the configuration file format is considered as part of the pub [NOTE] ==== -To prevent a chicken-and-egg problem some configuration options, such as the location of the configuration file can be supplied only through <<system-properties>>. +To prevent a chicken-and-egg problem some configuration options, such as the location of the configuration file can be supplied only through xref:manual/configuration/properties.adoc[System properties]. ==== [#log4j-core-configuration-file] @@ -62,7 +62,9 @@ Upon initialization of a new logger context, Log4j assigns it a context name and . Files named `log4j2<contextName>.<extension>` . Files named `log4j2.<extension>`, . If no configuration file could be located a link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/DefaultConfiguration[DefaultConfiguration] is used and a warning is printed by the status logger. -The default configuration prints all messages less specific than <<log4j2.level>> to the console. +The default configuration prints all messages less specific than +xref:manual/configuration/properties.adoc#log4j2.level[log4j2.level] +to the console. [CAUTION] ==== @@ -104,11 +106,12 @@ See xref:manual/webapp.adoc#configuration[Log4j [NOTE] ==== -It is also possible to override the location of the configuration file using the <<log4j2.configurationFile>> +It is also possible to override the location of the configuration file using the +xref:./configuration/properties.adoc#log4j2.configurationFile[log4j2.configurationFile] configuration property. In this case Log4j will guess the configuration file format from the extension of the provided configuration file or will use the default configuration factory if the extension is unknown. -See <<log4j2.configurationFactory>> for details. +See xref:./configuration/properties.adoc#log4j2.configurationFile[log4j2.configurationFile] for details. ==== === Syntax @@ -398,14 +401,15 @@ Unless the new configuration file removes an appender, the old one continues to |=== | Type | link:../javadoc/log4j-api/org/apache/logging/log4j/Level.html[LEVEL] | Status | **DEPRECATED** -| Default value (since 2.24.0) | <<log4j2.statusLoggerLevel>> +| Default value (since 2.24.0) | xref:./configuration/properties.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel] | Default value (before 2.24.0) | value of `log4j2.defaultStatusLevel` |=== Overrides the logging level of the status logger. -WARNING: Since 2.24.0 this attribute is deprecated and should be replaced with the <<log4j2.statusLoggerLevel>> -variable. +WARNING: Since 2.24.0 this attribute is deprecated and will be replaced with the +xref:./configuration/properties.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel] +configuration property. [id=configuration-attribute-schema] ==== `schema` @@ -490,7 +494,8 @@ If `true` (default), all the messages received by this logger will also be trans | Type | link:../javadoc/log4j-api/org/apache/logging/log4j/Level.html[Level] | Default value a| -* <<log4j2.level>>, for `Root` and `AsyncRoot`, +* xref:./configuration/properties.adoc#log4j2.level[log4j2.level], +for `Root` and `AsyncRoot`, * inherited from the parent logger, for `Logger` and `AsyncLogger`. |=== @@ -507,12 +512,14 @@ See also xref:manual/filters.adoc#filters[Filters] if you require additional fil | Type | `boolean` | Default value a| -* `false`, if an asynchrounous `ContextSelector` is used. +* `false`, if an asynchronous `ContextSelector` is used. * Otherwise, ** `true` for `Root` and `Logger`, ** `false` for `AsyncRoot` and `AsyncLogger`. -See <<log4j2.contextSelector>> for more details. +See +xref:./configuration/properties.adoc#log4j2.contextSelector[log4j2.contextSelector] +for more details. |=== Specifies whether Log4j is allowed to compute location information. @@ -632,7 +639,7 @@ If `name` contains a `:` character, it is expanded as in the rule below. ==== `${lookup:name}`:: -If both these considitions hold: +If both these conditions hold: + -- * `lookup` is a prefix assigned to a xref:manual/lookups.adoc[Lookup], @@ -663,7 +670,7 @@ If `name` contains a `:` character, it is expanded as in the rule below. `${lookup:name:-default}`:: + -If both these considitions hold: +If both these conditions hold: + -- * `lookup` is a prefix assigned to a xref:manual/lookups.adoc[Lookup], @@ -732,10 +739,10 @@ Java properties:: include::example$configuration/routing.properties[tag=appender] ---- ==== -<1> The `pattern` attribute is evaluated at configuration time and also each time a log event is routed. Therefore, the dollar `$` sign needs to be escaped. + +<1> The `pattern` attribute is evaluated at configuration time and also each time a log event is routed. +Therefore, the dollar `$` sign needs to be escaped. <2> All the attributes inside the `File` element have a **deferred** evaluation, therefore they need only one `$` sign. [#log4j-core-programmatic-configuration] -== Programmatic configuration - -include::_properties.adoc[leveloffset=+1] \ No newline at end of file +== Programmatic configuration \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration/properties.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration/properties.adoc index 30a502fe3a..3b132b4f6b 100644 --- a/src/site/antora/modules/ROOT/pages/manual/configuration/properties.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/configuration/properties.adoc @@ -152,7 +152,7 @@ include::partial$properties-async-logger-config.adoc[leveloffset=+2] [id=properties-properties-context-selector] === 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 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. @@ -243,7 +243,7 @@ include::partial$properties-log4j-spring-boot.adoc[leveloffset=+2] [id=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]. +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: diff --git a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc index 220a49fc4e..1763e1bcee 100644 --- a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc @@ -82,7 +82,7 @@ reference these fields after the web application is undeployed. To avoid causing memory leaks, Log4j will not use these ThreadLocals when it detects that it is used in a web application (when the `javax.servlet.Servlet` class is in the classpath, or when system -property xref:manual/configuration.adoc#log4j2.isWebapp[log4j2.isWebapp] is set to `true`). +property xref:manual/configuration/properties.adoc#log4j2.isWebapp[log4j2.isWebapp] is set to `true`). Some garbage-reducing functionality does not rely on ThreadLocals and is enabled by default for all applications: in Log4j 2.6, converting log @@ -112,8 +112,8 @@ you may also configure a xref:manual/async.adoc#WaitStrategy[custom wait strateg There are separate system properties for manually controlling the mechanisms Log4j uses to avoid creating temporary objects: -* xref:manual/configuration.adoc#log4j2.enableThreadlocals[log4j2.enableThreadlocals] - if "true" (the default for non-web applications) objects are stored in ThreadLocal fields and reused, otherwise new objects are created for each log event. -* xref:manual/configuration.adoc#log4j2.enableDirectEncoders[log4j2.enableDirectEncoders] - if "true" (the default) +* xref:manual/configuration/properties.adoc#log4j2.enableThreadlocals[log4j2.enableThreadlocals] - if "true" (the default for non-web applications) objects are stored in ThreadLocal fields and reused, otherwise new objects are created for each log event. +* xref:manual/configuration/properties.adoc#log4j2.enableDirectEncoders[log4j2.enableDirectEncoders] - if "true" (the default) log events are converted to text and this text is converted to bytes without creating temporary objects. Note: _synchronous_ logging performance may be worse @@ -122,7 +122,7 @@ the shared buffer. If your application is multi-threaded and logging performance is important, consider using Async Loggers. * The ThreadContext map is _not_ garbage-free by default, but from Log4j 2.7 it can be configured to be garbage-free by setting system property -xref:manual/configuration.adoc#log4j2.garbagefreeThreadContextMap[log4j2.garbagefreeThreadContextMap] to "true". +xref:manual/configuration/properties.adoc#log4j2.garbagefreeThreadContextMap[log4j2.garbagefreeThreadContextMap] to "true". Instead of system properties, the above properties can also be specified in a file named `log4j2.component.properties` by including this file in diff --git a/src/site/antora/modules/ROOT/pages/manual/jmx.adoc b/src/site/antora/modules/ROOT/pages/manual/jmx.adoc index a5439324f6..cf47226659 100644 --- a/src/site/antora/modules/ROOT/pages/manual/jmx.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/jmx.adoc @@ -34,15 +34,20 @@ JMX support is disabled by default. NOTE: JMX support was enabled by default in Log4j 2 versions before 2.24.0. -To enable JMX support, set the following system property when starting the Java VM: +To enable JMX support, set the +xref:manual/configuration/properties.adoc#log4j2.disableJmx[log4j2.disableJmx] +system property when starting the Java VM: -`xref:manual/configuration.adoc#log4j2.disableJmx[log4j2.disableJmx]=false` +`log4j2.disableJmx=false` [#Local] == Local Monitoring and Management -To perform local monitoring you need to specify the `xref:manual/configuration.adoc#log4j2.disableJmx[log4j2.disableJmx]=false` system -property. The JConsole tool that is included in the Java JDK can be +To perform local monitoring you need to set the +xref:manual/configuration/properties.adoc#log4j2.disableJmx[log4j2 +.disableJmx] +system property to `false`. +The JConsole tool that is included in the Java JDK can be used to monitor your application. Start JConsole by typing `$JAVA_HOME/bin/jconsole` in a command shell. For more details, see Oracle's documentation on @@ -55,7 +60,7 @@ to use JConsole]. To enable monitoring and management from remote systems, set the following two system properties when starting the Java VM: -`xref:manual/configuration.adoc#log4j2.disableJmx[log4j2.disableJmx]=false` +`log4j2.disableJmx=false` and
