You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by pk...@apache.org on 2024/04/30 17:40:34 UTC
(logging-log4j2) 02/02: Add links to properties page
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 03e6685347ae604003885370976669f22b3de6c2
Author: Piotr P. Karwasz <pi...@karwasz.org>
AuthorDate: Tue Apr 30 19:20:11 2024 +0200
Add links to properties page
---
src/site/antora/modules/ROOT/pages/faq.adoc | 6 +-
.../antora/modules/ROOT/pages/log4j-jmx-gui.adoc | 2 +-
src/site/antora/modules/ROOT/pages/log4j-jul.adoc | 40 +--
.../pages/log4j-spring-cloud-config-client.adoc | 68 +----
.../modules/ROOT/pages/manual/_properties.adoc | 13 +-
.../antora/modules/ROOT/pages/manual/async.adoc | 15 +-
.../modules/ROOT/pages/manual/configuration.adoc | 15 +-
.../modules/ROOT/pages/manual/garbagefree.adoc | 9 +-
src/site/antora/modules/ROOT/pages/manual/jmx.adoc | 6 +-
.../antora/modules/ROOT/pages/manual/layouts.adoc | 322 +++++++++------------
10 files changed, 193 insertions(+), 303 deletions(-)
diff --git a/src/site/antora/modules/ROOT/pages/faq.adoc b/src/site/antora/modules/ROOT/pages/faq.adoc
index 64dc81f017..c333a1c529 100644
--- a/src/site/antora/modules/ROOT/pages/faq.adoc
+++ b/src/site/antora/modules/ROOT/pages/faq.adoc
@@ -32,7 +32,7 @@ Log4j 2 and onwards use `log4j2.xml`.
====
You can also specify the full path of the configuration file using a system property: +
-`-Dlog4j2.configurationFile=/path/to/log4j2.xml`
+`-Dxref:manual/configuration.adoc#log4j2.configurationFile[log4j2.configurationFile]=/path/to/log4j2.xml`
That property can also be included in a classpath resource file named `log4j2.component.properties`.
@@ -127,9 +127,9 @@ Note the `2` in the file name!
(See xref:manual/configuration.adoc[the Configuration page] for more details.)
. Increase the logging verbosity of the internal status logger: +
-`-Dlog4j2.statusLoggerLevel=TRACE`
+`-Dxref:manual/configuration.adoc#log4j2.statusLoggerLevel[log4j2.statusLoggerLevel]=TRACE`
-. Enable all internal debug logging: `-Dlog4j2.debug`.
+. Enable all internal debug logging: `-Dxref:manual/configuration.adoc#log4j2.debug[log4j2.debug]`.
This disables level-based status logger filtering and effectively allows all status logs.
[#separate_log_files]
diff --git a/src/site/antora/modules/ROOT/pages/log4j-jmx-gui.adoc b/src/site/antora/modules/ROOT/pages/log4j-jmx-gui.adoc
index 4dd0239289..abf21f6270 100644
--- a/src/site/antora/modules/ROOT/pages/log4j-jmx-gui.adoc
+++ b/src/site/antora/modules/ROOT/pages/log4j-jmx-gui.adoc
@@ -23,5 +23,5 @@ The client GUI can be run as a stand-alone application or as a JConsole plug-in.
====
The Java VM to be monitored has to enable Log4j JMX support, set the following system property when starting the Java VM:
-`log4j2.disableJmx=false`
+`xref:manual/configuration.adoc#log4j2.disableJmx[log4j2.disableJmx]=false`
====
diff --git a/src/site/antora/modules/ROOT/pages/log4j-jul.adoc b/src/site/antora/modules/ROOT/pages/log4j-jul.adoc
index 1077ecc270..c0d869e14e 100644
--- a/src/site/antora/modules/ROOT/pages/log4j-jul.adoc
+++ b/src/site/antora/modules/ROOT/pages/log4j-jul.adoc
@@ -43,40 +43,42 @@ Custom Handlers should instead use an appropriate xref:manual/appenders.adoc[App
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 `log4j.jul.levelConverter` 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.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]
=== Default Level Conversions
+.JUL to Log4j level conversion
|===
| Java Level | Log4j Level
-| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#OFF[`OFF`]
-| `OFF`
+| http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#OFF[OFF]
+| link:../javadoc/log4j-api/org/apache/logging/log4j/Level#OFF[OFF]
-| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#SEVERE[`SEVERE`]
-| `ERROR`
+| http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#SEVERE[SEVERE]
+| link:../javadoc/log4j-api/org/apache/logging/log4j/Level#ERROR[ERROR]
-| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#WARNING[`WARNING`]
-| `WARN`
+| http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#WARNING[WARNING]
+| link:../javadoc/log4j-api/org/apache/logging/log4j/Level#WARN[WARN]
-| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#INFO[`INFO`]
-| `INFO`
+| http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#OFF[OFF]
+| link:../javadoc/log4j-api/org/apache/logging/log4j/Level#INFO[INFO]
-| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#CONFIG[`CONFIG`]
-| `CONFIG`
+| http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#CONFIG[CONFIG]
+| custom `CONFIG` level
-| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINE[`FINE`]
-| `DEBUG`
+| http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#FINE[FINE]
+| link:../javadoc/log4j-api/org/apache/logging/log4j/Level#DEBUG[DEBUG]
-| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINER[`FINER`]
-| `TRACE`
+| http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#FINER[FINER]
+| link:../javadoc/log4j-api/org/apache/logging/log4j/Level#TRACE[TRACE]
-| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#FINEST[`FINEST`]
-| `FINEST`
+| http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#FINEST[FINEST]
+| custom `FINEST` level
-| http://docs.oracle.com/javase/6/docs/api/java/util/logging/Level.html#ALL[`ALL`]
-| `ALL`
+| http://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/Level.html#ALL[ALL]
+| link:../javadoc/log4j-api/org/apache/logging/log4j/Level#ALL[ALL]
|===
== Log4j JDK Logging Bridge Handler
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 dd4a3ed34b..c534a0847f 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,11 @@ Spring Boot applications initialize logging 3 times.
. SpringApplication declares a Logger.
This Logger will be initialized using Log4j's "normal" mechanisms.
-Thus a system property named log4j2.configurationFile will be checked to see if a specific configuration file has been provided, otherwise it will search for a configuration file on the classpath.
+Thus a system property named xref:manual/configuration.adoc#log4j2.configurationFile[log4j2.configurationFile] will be
+checked
+to see if a
+specific configuration
+file has been provided, otherwise it will search for a configuration file on the classpath.
The property may also be declare in log4j2.component.properties.
== Usage
@@ -122,67 +126,9 @@ logging:
Note that Log4j currently does not directly support encrypting the password.
However, Log4j does use Spring's standard APIs to access properties in the Spring configuration so any customizations made to Spring's property handling would apply to the properties Log4j uses as well.
-If more extensive authentication is required an `AuthorizationProvider` can be implemented and the fully qualified class name in the `log4j2.authorizationProvider` system property, in log4j2.component.properties or in Spring's bootstrap.yml using either the `log4j2.authorizationProvider` key or with the key `logging.auth.authorizationProvider`.
+If more extensive authentication is required an `AuthorizationProvider` can be implemented and the fully qualified class name in the xref:manual/configuration.adoc#log4j2.configurationAuthorizationProvider[log4j2.configurationAuthorizationProvider] system property, in `log4j2.component.properties` or in Spring's `bootstrap.yml` using either the `log4j2.authorizationProvider` key or with the key `logging.auth.authorizationProvider`.
-TLS can be enabled by adding the following system properties or defining them in log4j2.component.properties
-
-|===
-| Property | Optional or Default Value | Description
-
-| log4j2.trustStoreLocation
-| Optional
-| The location of the trust store.
-If not provided the default trust store will be used.
-
-| log4j2.trustStorePassword
-| Optional
-| Password needed to access the trust store.
-
-| log4j2.trustStorePasswordFile
-| Optional
-| The location of a file that contains the password for the trust store.
-
-| log4j2.trustStorePasswordEnvironmentVariable
-| Optional
-| The name of the environment variable that contains the trust store password.
-
-| log4j2.trustStoreKeyStoreType
-| Required if keystore location provided
-| The type of key store.
-
-| log4j2.trustStoreKeyManagerFactoryAlgorithm
-| Optional
-| Java cryptographic algorithm.
-
-| log4j2.keyStoreLocation
-| Optional
-| The location of the key store.
-If not provided the default key store will be used.
-
-| log4j2.keyStorePassword
-| Optional
-| Password needed to access the key store.
-
-| log4j2.keyStorePasswordFile
-| Optional
-| The location of a file that contains the password for the key store.
-
-| log4j2.keyStorePasswordEnvironmentVariable
-| Optional
-| The name of the environment variable that contains the key store password.
-
-| log4j2.keyStoreType
-| Required if trust store location provided.
-| The type of key store.
-
-| log4j2.keyStoreKeyManagerFactoryAlgorithm
-| Optional
-| Java cryptographic algorithm.
-
-| log4j2.sslVerifyHostName
-| false
-| true or false
-|===
+For the properties required by TLS configuration see xref:manual/configuration.adoc#transport-security[Transport Security].
== Requirements
diff --git a/src/site/antora/modules/ROOT/pages/manual/_properties.adoc b/src/site/antora/modules/ROOT/pages/manual/_properties.adoc
index 81f45d88cf..a4e40aecda 100644
--- a/src/site/antora/modules/ROOT/pages/manual/_properties.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/_properties.adoc
@@ -496,7 +496,7 @@ h| Default Value
h| Description
-| [[log4j2enableDirectEncoders]]`log4j2.enableDirectEncoders`
+| [[log4j2.enableDirectEncoders]]`log4j2.enableDirectEncoders`
(`LOG4J_ENABLE_DIRECT_ENCODERS`)
| `true`
@@ -910,7 +910,7 @@ The names specified must correspond to those returned by https://docs.oracle.com
== JUL-to-Log4j API bridge
-The JUL-to-Log4j API bridge provides a single configuration property:
+The JUL-to-Log4j API bridge provides the following configuration properties:
.JUL configuration properties
[cols="1,1,5"]
@@ -921,6 +921,15 @@ h| Java Property
h| Default Value
h| Description
+| [[log4j2.julLevelConverter]]`log4j2.julLevelConverter`
+
+(`LOG4J_JUL_LEVEL_CONVERTER`)
+|
+|
+Fully qualified name of an alternative `org.apache.logging.log4j.jul.LevelConverter` implementation.
+
+See xref:log4j-jul.adoc#default-level-conversions[Default Level Conversions] for the default implementation.
+
| [[log4j2.julLoggerAdapter]]`log4j2.julLoggerAdapter`
(`LOG4J_JUL_LOGGER_ADAPTER`)
diff --git a/src/site/antora/modules/ROOT/pages/manual/async.adoc b/src/site/antora/modules/ROOT/pages/manual/async.adoc
index 3b8efc401c..73bbf84279 100644
--- a/src/site/antora/modules/ROOT/pages/manual/async.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/async.adoc
@@ -116,11 +116,8 @@ NOTE: _Log4j-2.9 and higher require disruptor-3.3.4.jar or higher on the
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 `log4j2.contextSelector` to
-`org.apache.logging.log4j.core.async.AsyncLoggerContextSelector` or
-`org.apache.logging.log4j.core.async.BasicAsyncLoggerContextSelector`.
+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`.
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
@@ -177,10 +174,6 @@ The below properties can also be specified by creating a file named
`log4j2.component.properties` and including this file in the classpath
of the application.
-NOTE: System properties were renamed into a more consistent style in
-Log4j 2.10.0. All old property names are still supported which are
-documented xref:manual/configuration.adoc#SystemProperties[here].
-
[[SysPropsAllAsync]]
.System Properties to configure all asynchronous loggers
@@ -355,10 +348,6 @@ The below properties can also be specified by creating a file named
`log4j2.component.properties` and including this file in the classpath
of the application.
-NOTE: All system properties were renamed into a more consistent style in
-Log4j 2.10. All old property names are still supported which are
-documented xref:manual/configuration.adoc#SystemProperties[here].
-
[[SysPropsMixedSync-Async]]
.System Properties to configure mixed asynchronous and normal loggers
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
index ae14df44f8..66a6b51688 100644
--- a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
@@ -220,11 +220,8 @@ highest to lowest. As delivered, Log4j contains four
ConfigurationFactory implementations: one for JSON, one for YAML, one
for properties, and one for XML.
-1. Log4j will inspect the `"log4j2.configurationFile"` system property
-and, if set, will attempt to load the configuration using the
-`ConfigurationFactory` that matches the file extension. Note that this
-is not restricted to a location on the local file system and may contain
-a URL.
+1. Log4j will inspect the <<log4j2.configurationFile>> system property and, if set, will attempt to load the configuration using the `ConfigurationFactory` that matches the file extension.
+Note that this is not restricted to a location on the local file system and may contain a URL.
2. If no system property is set the properties ConfigurationFactory
will look for `log4j2-test.properties` in the classpath.
3. If no such file is found the YAML ConfigurationFactory will look for
@@ -362,7 +359,7 @@ used.
When `log4j2.configurationFile` references a URL, Log4j will first determine if the URL reference
a file using the file protocol. If it does Log4j will validate that the file URL is valid and continue
processing as previously described. If it contains a protocol other than file then Log4j will inspect
-the value of the `log4j2.Configuration.allowedProtocols` system property. If the provided list
+the value of the <<log4j2.configurationAllowedProtocols>> system property. If the provided list
contains the protocol specified then Log4j will use the URI to locate the specified configuration file. If
not an exception will be thrown and an error message will be logged. If no value is provided for the
system property it will default to "https". Use of any protocol other than "file" can be prevented by
@@ -373,9 +370,9 @@ Log4j supports access to remote URLs that require authentication. Log4j supports
out of the box. If the `log4j2.Configuration.username` and `log4j2.Configuration.password`
are specified those values will be used to perform the authentication. If the password is encrypted a custom
password decryptor may be supplied by specifying the fully qualified class name in the
-`log4j2.Configuration.passwordDecryptor` system property. A custom
+<<log4j2.configurationPasswordDecryptor>> system property. A custom
`AuthenticationProvider` may be used by setting the
-`log4j2.Configuration.authenticationProvider` system property to the fully qualified class name
+`<<log4j2.configurationAuthorizationProvider>> system property to the fully qualified class name
of the provider.
[#Additivity]
@@ -630,7 +627,7 @@ rollover and other internal actions to the status logger. Setting
`status="trace"` is one of the first tools available to you if you need
to troubleshoot log4j.
-(Alternatively, setting system property `log4j2.debug` will also print
+(Alternatively, setting system property <<log4j2.debug>> will also print
internal Log4j2 logging to the console, including internal logging that
took place before the configuration file was found.)
diff --git a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc
index ccc0e86472..220a49fc4e 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 `log4j2.isWebapp` is set to "true").
+property xref:manual/configuration.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,9 @@ 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:
-* 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.
-* `log4j2.enableDirectEncoders` - if "true" (the default) log events are
+* 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)
+log events are
converted to text and this text is converted to bytes without creating
temporary objects. Note: _synchronous_ logging performance may be worse
for multi-threaded applications in this mode due to synchronization on
@@ -121,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
-`log4j2.garbagefreeThreadContextMap` to "true".
+xref:manual/configuration.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 27ccc79197..a5439324f6 100644
--- a/src/site/antora/modules/ROOT/pages/manual/jmx.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/jmx.adoc
@@ -36,12 +36,12 @@ 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:
-`log4j2.disableJmx=false`
+`xref:manual/configuration.adoc#log4j2.disableJmx[log4j2.disableJmx]=false`
[#Local]
== Local Monitoring and Management
-To perform local monitoring you need to specify the `log4j2.disableJmx=false` system
+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
used to monitor your application. Start JConsole by typing
`$JAVA_HOME/bin/jconsole` in a command shell. For more details,
@@ -55,7 +55,7 @@ to use JConsole].
To enable monitoring and management from remote systems, set the
following two system properties when starting the Java VM:
-`log4j2.disableJmx=false`
+`xref:manual/configuration.adoc#log4j2.disableJmx[log4j2.disableJmx]=false`
and
diff --git a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
index 87ee914bea..dea36c18ce 100644
--- a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
@@ -17,25 +17,19 @@
= Layouts
Ralph Goers <rg...@apache.org>; Gary Gregory <gg...@apache.org>; Volkan Yazıcı <vy...@apache.org>
-An Appender uses a Layout to format a LogEvent into a form that meets
-the needs of whatever will be consuming the log event. In Log4j 1.x and
-Logback Layouts were expected to transform an event into a String. In
-Log4j 2 Layouts return a byte array. This allows the result of the
-Layout to be useful in many more types of Appenders. However, this means
-you need to configure most Layouts with a
+An Appender uses a Layout to format a LogEvent into a form that meets the needs of whatever will be consuming the log event.
+In Log4j 1.x and Logback Layouts were expected to transform an event into a String.
+In Log4j 2 Layouts return a byte array.
+This allows the result of the Layout to be useful in many more types of Appenders.
+However, this means you need to configure most Layouts with a
https://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html[`Charset`]
to ensure the byte array contains correct values.
The root class for layouts that use a Charset is
-`org.apache.logging.log4j.core.layout.AbstractStringLayout` where the
-default is UTF-8. Each layout that extends `AbstractStringLayout` can
-provide its own default. See each layout below.
+`org.apache.logging.log4j.core.layout.AbstractStringLayout` where the default is UTF-8. Each layout that extends `AbstractStringLayout` can provide its own default.
+See each layout below.
-A custom character encoder was added to Log4j 2.4.1 for the ISO-8859-1
-and US-ASCII charsets, to bring some of the performance improvements
-built-in to Java 8 to Log4j for use on Java 7. For applications that log
-only ISO-8859-1 characters, specifying this charset will improve
-performance significantly.
+A custom character encoder was added to Log4j 2.4.1 for the ISO-8859-1 and US-ASCII charsets, to bring some of the performance improvements built-in to Java 8 to Log4j for use on Java 7. For applications that log only ISO-8859-1 characters, specifying this charset will improve performance significantly.
[#CSVLayouts]
== CSV Layouts
@@ -49,15 +43,11 @@ Value (CSV)] records and requires
https://commons.apache.org/proper/commons-csv/[Apache Commons CSV] 1.4.
The CSV layout can be used in two ways: First, using
-`CsvParameterLayout` to log event parameters to create a custom
-database, usually to a logger and file appender uniquely configured for
-this purpose. Second, using `CsvLogEventLayout` to log events to create
-a database, as an alternative to using a full DBMS or using a JDBC
-driver that supports the CSV format.
+`CsvParameterLayout` to log event parameters to create a custom database, usually to a logger and file appender uniquely configured for this purpose.
+Second, using `CsvLogEventLayout` to log events to create a database, as an alternative to using a full DBMS or using a JDBC driver that supports the CSV format.
-The `CsvParameterLayout` converts an event's parameters into a CSV
-record, ignoring the message. To log CSV records, you can use the usual
-Logger methods `info()`, `debug()`, and so on:
+The `CsvParameterLayout` converts an event's parameters into a CSV record, ignoring the message.
+To log CSV records, you can use the usual Logger methods `info()`, `debug()`, and so on:
[source,java]
----
@@ -70,16 +60,14 @@ Which will create the CSV record:
value1, value2, value3
....
-Alternatively, you can use a `ObjectArrayMessage`, which only carries
-parameters:
+Alternatively, you can use a `ObjectArrayMessage`, which only carries parameters:
[source,java]
----
logger.info(new ObjectArrayMessage(value1, value2, value3));
----
-The layouts `CsvParameterLayout` and `CsvLogEventLayout` are configured
-with the following parameters:
+The layouts `CsvParameterLayout` and `CsvLogEventLayout` are configured with the following parameters:
.CsvParameterLayout and CsvLogEventLayout
[cols="1m,1,4"]
@@ -140,15 +128,15 @@ logger.debug("one={}, two={}, three={}", 1, 2, 3);
Produces a CSV record with the following fields:
-1. Time Nanos
-2. Time Millis
-3. Level
-4. Thread ID
-5. Thread Name
-6. Thread Priority
-7. Formatted Message
-8. Logger FQCN
-9. Logger Name
+1. Time Nanos
+2. Time Millis
+3. Level
+4. Thread ID
+5. Thread Name
+6. Thread Priority
+7. Formatted Message
+8. Logger FQCN
+9. Logger Name
10. Marker
11. Thrown Proxy
12. Source
@@ -159,15 +147,15 @@ Produces a CSV record with the following fields:
0,1441617184044,DEBUG,main,"one=1, two=2, three=3",org.apache.logging.log4j.spi.AbstractLogger,,,,org.apache.logging.log4j.core.layout.CsvLogEventLayoutTest.testLayout(CsvLogEventLayoutTest.java:98),{},[]
....
-Additional xref:runtime-dependencies.adoc[runtime dependencies] are
-required for using CSV layouts.
+Additional xref:runtime-dependencies.adoc[runtime dependencies] are required for using CSV layouts.
[#GELFLayout]
== GELF Layout
Lays out events in the Graylog Extended Log Format (GELF) 1.1.
-This layout compresses JSON to GZIP or ZLIB (`compressionType`) if log event data is larger than 1024 bytes (`compressionThreshold`). This layout does not implement chunking.
+This layout compresses JSON to GZIP or ZLIB (`compressionType`) if log event data is larger than 1024 bytes (`compressionThreshold`).
+This layout does not implement chunking.
Configure as follows to send to a Graylog 2.x server with UDP:
@@ -223,18 +211,17 @@ To include any custom field in the output, use following syntax:
</GelfLayout>
----
-Custom fields are included in the order they are declared. The values support xref:manual/lookups.adoc[lookups].
+Custom fields are included in the order they are declared.
+The values support xref:manual/lookups.adoc[lookups].
See also:
* The https://docs.graylog.org/en/latest/pages/gelf.html#gelf[GELF specification]
-
[#HTMLLayout]
== HTML Layout
-The HtmlLayout generates an HTML page and adds each LogEvent to a row in
-a table.
+The HtmlLayout generates an HTML page and adds each LogEvent to a row in a table.
.HtmlLayout Parameters
[cols="1m,1,4"]
@@ -287,6 +274,7 @@ https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getTimeZone(ja
|===
Configure as follows to use dataPattern and timezone in HtmlLayout:
+
[source,xml]
----
<Appenders>
@@ -299,13 +287,15 @@ Configure as follows to use dataPattern and timezone in HtmlLayout:
[[JSONLayout]]
== JSON Layout
-NOTE: JsonTemplate is considered deprecated. JsonTemplateLayout provides more capabilities and should be used instead.
+NOTE: JsonTemplate is considered deprecated.
+JsonTemplateLayout provides more capabilities and should be used instead.
Appends a series of JSON events as strings serialized as bytes.
=== Complete well-formed JSON vs. fragment JSON
-If you configure `complete="true"`, the appender outputs a well-formed JSON document. By default, with `complete="false"`, you should include the output as an _external file_ in a separate file to form a well-formed JSON document.
+If you configure `complete="true"`, the appender outputs a well-formed JSON document.
+By default, with `complete="false"`, you should include the output as an _external file_ in a separate file to form a well-formed JSON document.
If `complete="false"`, the appender does not write the JSON open array character "[" at the start of the document, "]" at the end, nor comma "," between records.
@@ -371,7 +361,10 @@ Log event follows this pattern:
=== Pretty vs. compact JSON
-The compact attribute determines whether the output will be "pretty" or not. The default value is "false", which means the appender uses end-of-line characters and indents lines to format the text. If `compact="true"`, then no end-of-line or indentation is used, which will cause the output to take less space. Of course, the message content may contain, escaped end-of-lines.
+The compact attribute determines whether the output will be "pretty" or not.
+The default value is "false", which means the appender uses end-of-line characters and indents lines to format the text.
+If `compact="true"`, then no end-of-line or indentation is used, which will cause the output to take less space.
+Of course, the message content may contain, escaped end-of-lines.
[options="header"]
|===
@@ -401,18 +394,17 @@ To include any custom field in the output, use following syntax:
</JsonLayout>
----
-Custom fields are always last, in the order they are declared. The values support xref:manual/lookups.adoc[lookups].
+Custom fields are always last, in the order they are declared.
+The values support xref:manual/lookups.adoc[lookups].
Additional xref:runtime-dependencies.adoc[runtime dependencies] are required for using JsonLayout.
-
[#JSONTemplateLayout]
== JSON Template Layout
-`JsonTemplateLayout` is a customizable, efficient, and garbage-free JSON
-emitting layout. It encodes ``LogEvent``s according to the structure described
-by the JSON template provided. For instance, given the following JSON template
-modelling https://github.com/logstash/log4j-jsonevent-layout[the official
+`JsonTemplateLayout` is a customizable, efficient, and garbage-free JSON emitting layout.
+It encodes ``LogEvent``s according to the structure described by the JSON template provided.
+For instance, given the following JSON template modelling https://github.com/logstash/log4j-jsonevent-layout[the official
Logstash `JSONEventLayoutV1`]
[source,json]
@@ -509,33 +501,28 @@ JSON Template Layout will render JSON documents as follows:
}
----
-See xref:manual/json-template-layout.adoc[JSON Template Layout] page for the complete
-documentation.
+See xref:manual/json-template-layout.adoc[JSON Template Layout] page for the complete documentation.
[#PatternLayout]
== Pattern Layout
-A flexible layout configurable with pattern string. The goal of this
-class is to format a LogEvent and return the results. The format of the
-result depends on the _conversion pattern_.
+A flexible layout configurable with pattern string.
+The goal of this class is to format a LogEvent and return the results.
+The format of the result depends on the _conversion pattern_.
-The conversion pattern is closely related to the conversion pattern of
-the printf function in C. A conversion pattern is composed of literal
-text and format control expressions called _conversion specifiers_.
+The conversion pattern is closely related to the conversion pattern of the printf function in C. A conversion pattern is composed of literal text and format control expressions called _conversion specifiers_.
-_Note that any literal text, including *Special Characters*, may be
-included in the conversion pattern._ Special Characters include *\t*,
-*\n*, *\r*, *\f*. Use *\\* to insert a single backslash into the output.
+_Note that any literal text, including *Special Characters*, may be included in the conversion pattern._ Special Characters include *\t*,
+*\n*, *\r*, *\f*.
+Use *\\* to insert a single backslash into the output.
-Each conversion specifier starts with a percent sign (%) and is followed
-by optional _format modifiers_ and a _conversion character_. The
-conversion character specifies the type of data, e.g. category,
-priority, date, thread name. The format modifiers control such things as
-field width, padding, left and right justification. The following is a
-simple example.
+Each conversion specifier starts with a percent sign (%) and is followed by optional _format modifiers_ and a _conversion character_.
+The conversion character specifies the type of data, e.g. category, priority, date, thread name.
+The format modifiers control such things as field width, padding, left and right justification.
+The following is a simple example.
-Let the conversion pattern be *"%-5p [%t]: %m%n"* and assume that the
-Log4j environment was set to use a PatternLayout. Then the statements
+Let the conversion pattern be *"%-5p [%t]: %m%n"* and assume that the Log4j environment was set to use a PatternLayout.
+Then the statements
....
Logger logger = LogManager.getLogger("MyLogger");
@@ -550,17 +537,12 @@ DEBUG [main]: Message 1
WARN [main]: Message 2
....
-Note that there is no explicit separator between text and conversion
-specifiers. The pattern parser knows when it has reached the end of a
-conversion specifier when it reads a conversion character. In the
-example above the conversion specifier `%-5p` means the priority of the
-logging event should be left justified to a width of five characters.
+Note that there is no explicit separator between text and conversion specifiers.
+The pattern parser knows when it has reached the end of a conversion specifier when it reads a conversion character.
+In the example above the conversion specifier `%-5p` means the priority of the logging event should be left justified to a width of five characters.
-If the pattern string does not contain a specifier to handle a Throwable
-being logged, parsing of the pattern will act as if the `%xEx` specifier
-had be added to the end of the string. To suppress formatting of the
-Throwable completely simply add `%ex\{0}` as a specifier in the pattern
-string.
+If the pattern string does not contain a specifier to handle a Throwable being logged, parsing of the pattern will act as if the `%xEx` specifier had be added to the end of the string.
+To suppress formatting of the Throwable completely simply add `%ex\{0}` as a specifier in the pattern string.
.PatternLayout Parameters
[cols="1m,1,4"]
@@ -839,8 +821,7 @@ formats are supported. Only timestamps in the formats mentioned in the
table above may use the "nano-of-second" pattern letter `n` instead of
the "fraction-of-second" pattern letter `S`.
-Users may revert back to a millisecond-precision clock when running on
-Java 9 by setting system property `log4j2.Clock` to `SystemMillisClock`.
+Users may revert back to a millisecond-precision clock when running on Java 9 by setting system property xref:manual/configuration.adoc#log4j2.clock[log4j2.clock]` to `SystemMillisClock`.
|*enc*\{pattern}{[HTML\|XML\|JSON\|CRLF]} +
*encode*\{pattern}{[HTML\|XML\|JSON\|CRLF]}
@@ -1568,41 +1549,31 @@ print.
|The sequence %% outputs a single percent sign.
|===
-By default the relevant information is output as is. However, with the
-aid of format modifiers it is possible to change the minimum field
-width, the maximum field width and justification.
+By default the relevant information is output as is.
+However, with the aid of format modifiers it is possible to change the minimum field width, the maximum field width and justification.
-The optional format modifier is placed between the percent sign and the
-conversion character.
+The optional format modifier is placed between the percent sign and the conversion character.
The first optional format modifier is the _left justification flag_
-which is just the minus (-) character. Then comes the optional _minimum
-field width_ modifier. This is a decimal constant that represents the
-minimum number of characters to output. If the data item requires fewer
-characters, it is padded on either the left or the right until the
-minimum width is reached. The default is to pad on the left (right
-justify) but you can specify right padding with the left justification
-flag. The padding character is space. If the data item is larger than
-the minimum field width, the field is expanded to accommodate the data.
-The value is never truncated. To use zeros as the padding character prepend
-the _minimum field width_ with a zero.
-
-This behavior can be changed using the _maximum field width_ modifier
-which is designated by a period followed by a decimal constant. If the
-data item is longer than the maximum field, then the extra characters
-are removed from the _beginning_ of the data item and not from the end.
-For example, it the maximum field width is eight and the data item is
-ten characters long, then the first two characters of the data item are
-dropped. This behavior deviates from the printf function in C where
-truncation is done from the end.
-
-Truncation from the end is possible by appending a minus character right
-after the period. In that case, if the maximum field width is eight and
-the data item is ten characters long, then the last two characters of
-the data item are dropped.
-
-Below are various format modifier examples for the category conversion
-specifier.
+which is just the minus (-) character.
+Then comes the optional _minimum field width_ modifier.
+This is a decimal constant that represents the minimum number of characters to output.
+If the data item requires fewer characters, it is padded on either the left or the right until the minimum width is reached.
+The default is to pad on the left (right justify) but you can specify right padding with the left justification flag.
+The padding character is space.
+If the data item is larger than the minimum field width, the field is expanded to accommodate the data.
+The value is never truncated.
+To use zeros as the padding character prepend the _minimum field width_ with a zero.
+
+This behavior can be changed using the _maximum field width_ modifier which is designated by a period followed by a decimal constant.
+If the data item is longer than the maximum field, then the extra characters are removed from the _beginning_ of the data item and not from the end.
+For example, it the maximum field width is eight and the data item is ten characters long, then the first two characters of the data item are dropped.
+This behavior deviates from the printf function in C where truncation is done from the end.
+
+Truncation from the end is possible by appending a minus character right after the period.
+In that case, if the maximum field width is eight and the data item is ten characters long, then the last two characters of the data item are dropped.
+
+Below are various format modifier examples for the category conversion specifier.
.Pattern Converters
|===
@@ -1657,25 +1628,21 @@ characters, then truncate from the end.
[#enable-jansi]
=== ANSI Styling on Windows
-ANSI escape sequences are supported natively on many platforms but are
-not by default on Windows. To enable ANSI support add the
-http://jansi.fusesource.org/[Jansi] jar to your application and set
-property `log4j.skipJansi` to `false`. This allows Log4j to use Jansi to
-add ANSI escape codes when writing to the console.
+ANSI escape sequences are supported natively on many platforms but are not by default on Windows.
+To enable ANSI support add the
+http://jansi.fusesource.org/[Jansi] jar to your application and set property `log4j.skipJansi` to `false`.
+This allows Log4j to use Jansi to add ANSI escape codes when writing to the console.
-NOTE: Prior to Log4j 2.10, Jansi was enabled by default. The fact that
-Jansi requires native code means that Jansi can only be loaded by a
-single class loader. For web applications this means the Jansi jar has
-to be in the web container's classpath. To avoid causing problems for
-web applications, Log4j will no longer automatically try to load Jansi
-without explicit configuration from Log4j 2.10 onward.
+NOTE: Prior to Log4j 2.10, Jansi was enabled by default.
+The fact that Jansi requires native code means that Jansi can only be loaded by a single class loader.
+For web applications this means the Jansi jar has to be in the web container's classpath.
+To avoid causing problems for web applications, Log4j will no longer automatically try to load Jansi without explicit configuration from Log4j 2.10 onward.
=== Example Patterns
==== Filtered Throwables
-This example shows how to filter out classes from unimportant packages
-in stack traces.
+This example shows how to filter out classes from unimportant packages in stack traces.
[source,xml]
----
@@ -1716,20 +1683,14 @@ All the content that follows the level will be bright green.
[#PatternSelectors]
=== Pattern Selectors
-The PatternLayout can be configured with a PatternSelector to allow it
-to choose a pattern to use based on attributes of the log event or other
-factors. A PatternSelector will normally be configured with a
-defaultPattern attribute, which is used when other criteria don't match,
-and a set of PatternMatch elements that identify the various patterns
-that can be selected.
+The PatternLayout can be configured with a PatternSelector to allow it to choose a pattern to use based on attributes of the log event or other factors.
+A PatternSelector will normally be configured with a defaultPattern attribute, which is used when other criteria don't match, and a set of PatternMatch elements that identify the various patterns that can be selected.
[#LevelPatternSelector]
==== LevelPatternSelector
-The LevelPatternSelector selects patterns based on the log level of
-the log event. If the Level in the log event is equal to (ignoring case)
- the name specified on the PatternMatch key attribute, then
-the pattern specified on that PatternMatch element will be used.
+The LevelPatternSelector selects patterns based on the log level of the log event.
+If the Level in the log event is equal to (ignoring case) the name specified on the PatternMatch key attribute, then the pattern specified on that PatternMatch element will be used.
[source,xml]
----
@@ -1743,10 +1704,8 @@ the pattern specified on that PatternMatch element will be used.
[#MarkerPatternSelector]
==== MarkerPatternSelector
-The MarkerPatternSelector selects patterns based on the Marker included
-in the log event. If the Marker in the log event is equal to or is an
-ancestor of the name specified on the PatternMatch key attribute, then
-the pattern specified on that PatternMatch element will be used.
+The MarkerPatternSelector selects patterns based on the Marker included in the log event.
+If the Marker in the log event is equal to or is an ancestor of the name specified on the PatternMatch key attribute, then the pattern specified on that PatternMatch element will be used.
[source,xml]
----
@@ -1761,13 +1720,8 @@ the pattern specified on that PatternMatch element will be used.
==== ScriptPatternSelector
The ScriptPatternSelector executes a script as descibed in the
-xref:manual/configuration.adoc#Scripts[Scripts] section of the Configuration
-chapter. The script is passed all the properties configured in the
-Properties section of the configuration, the StrSubstitutor used by the
-Confguration in the "substitutor" variables, and the log event in the
-"logEvent" variable, and is expected to return the value of the
-PatternMatch key that should be used, or null if the default pattern
-should be used.
+xref:manual/configuration.adoc#Scripts[Scripts] section of the Configuration chapter.
+The script is passed all the properties configured in the Properties section of the configuration, the StrSubstitutor used by the Confguration in the "substitutor" variables, and the log event in the "logEvent" variable, and is expected to return the value of the PatternMatch key that should be used, or null if the default pattern should be used.
[source,xml]
----
@@ -1791,12 +1745,8 @@ should be used.
[#RFC5424Layout]
== RFC5424 Layout
-As the name implies, the Rfc5424Layout formats LogEvents in accordance
-with http://tools.ietf.org/html/rfc5424[RFC 5424], the enhanced Syslog
-specification. Although the specification is primarily directed at
-sending messages via Syslog, this format is quite useful for other
-purposes since items are passed in the message as self-describing
-key/value pairs.
+As the name implies, the Rfc5424Layout formats LogEvents in accordance with http://tools.ietf.org/html/rfc5424[RFC 5424], the enhanced Syslog specification.
+Although the specification is primarily directed at sending messages via Syslog, this format is quite useful for other purposes since items are passed in the message as self-describing key/value pairs.
.Rfc5424Layout Parameters
[cols="1m,1,4"]
@@ -1914,18 +1864,15 @@ order to distinguish it from event attributes. The default string is
[#SerializedLayout]
== Serialized Layout
-The SerializedLayout simply serializes the LogEvent into a byte array
-using Java Serialization. The SerializedLayout accepts no parameters.
+The SerializedLayout simply serializes the LogEvent into a byte array using Java Serialization.
+The SerializedLayout accepts no parameters.
-This layout is deprecated since version 2.9. Java Serialization has
-inherent security weaknesses, using this layout is no longer
-recommended.
+This layout is deprecated since version 2.9. Java Serialization has inherent security weaknesses, using this layout is no longer recommended.
[#SyslogLayout]
== Syslog Layout
-The SyslogLayout formats the LogEvent as BSD Syslog records matching the
-same format used by Log4j 1.2.
+The SyslogLayout formats the LogEvent as BSD Syslog records matching the same format used by Log4j 1.2.
.SyslogLayout Parameters
[cols="1m,1,4"]
@@ -1964,7 +1911,8 @@ within the message text.
=== Complete well-formed XML vs. fragment XML
-If you configure `complete="true"`, the appender outputs a well-formed XML document where the default namespace is the Log4j namespace `https://logging.apache.org/log4j/2.0/events`. By default, with `complete="false"`, you should include the output as an _external entity_ in a separate file to form a well-formed XML document, in which case the appender uses `namespacePrefix` with a default of `log4j`.
+If you configure `complete="true"`, the appender outputs a well-formed XML document where the default namespace is the Log4j namespace `https://logging.apache.org/log4j/2.0/events`.
+By default, with `complete="false"`, you should include the output as an _external entity_ in a separate file to form a well-formed XML document, in which case the appender uses `namespacePrefix` with a default of `log4j`.
A well-formed XML document follows this pattern:
@@ -2021,11 +1969,15 @@ If `complete="false"`, the appender does not write the XML processing instructio
=== Marker
-Markers are represented by a `Marker` element within the `Event` element. The `Marker` element appears only when a marker is used in the log message. The name of the marker's parent will be provided in the `parent` attribute of the `Marker` element.
+Markers are represented by a `Marker` element within the `Event` element.
+The `Marker` element appears only when a marker is used in the log message.
+The name of the marker's parent will be provided in the `parent` attribute of the `Marker` element.
=== Pretty vs. compact XML
-By default, the XML layout is not compact (a.k.a. not "pretty") with `compact="false"`, which means the appender uses end-of-line characters and indents lines to format the XML. If `compact="true"`, then no end-of-line or indentation is used. Message content may contain, of course, end-of-lines.
+By default, the XML layout is not compact (a.k.a. not "pretty") with `compact="false"`, which means the appender uses end-of-line characters and indents lines to format the XML.
+If `compact="true"`, then no end-of-line or indentation is used.
+Message content may contain, of course, end-of-lines.
[options="header"]
|===
@@ -2050,7 +2002,8 @@ To include any custom field in the output, use the following syntax:
</XmlLayout>
----
-Custom fields are always last, in the order they are declared. The values support xref:manual/lookups.adoc[lookups].
+Custom fields are always last, in the order they are declared.
+The values support xref:manual/lookups.adoc[lookups].
NOTE: Additional xref:runtime-dependencies.adoc[runtime dependencies] are required for using XmlLayout.
@@ -2126,34 +2079,27 @@ To include any custom field in the output, use the following syntax:
</YamlLayout>
----
-Custom fields are always last, in the order they are declared. The values support xref:manual/lookups.adoc[lookups].
+Custom fields are always last, in the order they are declared.
+The values support xref:manual/lookups.adoc[lookups].
NOTE: Additional xref:runtime-dependencies.adoc[runtime dependencies] are required for using YamlLayout.
-
[#LocationInformation]
== Location Information
-If one of the layouts is configured with a location-related attribute
-like HTML link:#HtmlLocationInfo[locationInfo], or one of the patterns
+If one of the layouts is configured with a location-related attribute like HTML link:#HtmlLocationInfo[locationInfo], or one of the patterns
link:#PatternClass[%C or %class], link:#PatternFile[%F or %file],
link:#PatternLocation[%l or %location], link:#PatternLine[%L or %line],
-link:#PatternMethod[%M or %method], Log4j will take a snapshot of the
-stack, and walk the stack trace to find the location information.
-
-This is an expensive operation: 1.3 - 5 times slower for synchronous
-loggers. Synchronous loggers wait as long as possible before they take
-this stack snapshot. If no location is required, the snapshot will never
-be taken.
-
-However, asynchronous loggers need to make this decision before passing
-the log message to another thread; the location information will be lost
-after that point. The
-xref:manual/performance.adoc#asyncLoggingWithLocation[performance impact] of
-taking a stack trace snapshot is even higher for asynchronous loggers:
-logging with location is 30-100 times slower than without location. For
-this reason, asynchronous loggers and asynchronous appenders do not
-include location information by default.
-
-You can override the default behaviour in your logger or asynchronous
-appender configuration by specifying `includeLocation="true"`.
+link:#PatternMethod[%M or %method], Log4j will take a snapshot of the stack, and walk the stack trace to find the location information.
+
+This is an expensive operation: 1.3 - 5 times slower for synchronous loggers.
+Synchronous loggers wait as long as possible before they take this stack snapshot.
+If no location is required, the snapshot will never be taken.
+
+However, asynchronous loggers need to make this decision before passing the log message to another thread; the location information will be lost after that point.
+The
+xref:manual/performance.adoc#asyncLoggingWithLocation[performance impact] of taking a stack trace snapshot is even higher for asynchronous loggers:
+logging with location is 30-100 times slower than without location.
+For this reason, asynchronous loggers and asynchronous appenders do not include location information by default.
+
+You can override the default behaviour in your logger or asynchronous appender configuration by specifying `includeLocation="true"`.