This is an automated email from the ASF dual-hosted git repository.
pkarwasz pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
The following commit(s) were added to refs/heads/main by this push:
new 1d43edce19 Fix broken internal links
1d43edce19 is described below
commit 1d43edce19e4ff0075272c2f84f070452251c41b
Author: Piotr P. Karwasz <[email protected]>
AuthorDate: Tue May 28 09:56:55 2024 +0200
Fix broken internal links
Fix links to `runtime-dependencies.adoc` and similar by inlining the
content into the page.
---
pom.xml | 7 ++++
src/site/antora/antora.tmpl.yml | 1 +
src/site/antora/antora.yml | 1 +
src/site/antora/modules/ROOT/pages/faq.adoc | 3 +-
.../antora/modules/ROOT/pages/getting-started.adoc | 4 +--
.../antora/modules/ROOT/pages/log4j-1.2-api.adoc | 11 ++++++-
.../antora/modules/ROOT/pages/log4j-docker.adoc | 5 +--
.../antora/modules/ROOT/pages/log4j-flume-ng.adoc | 5 +--
.../antora/modules/ROOT/pages/log4j-iostreams.adoc | 9 +++--
src/site/antora/modules/ROOT/pages/log4j-jul.adoc | 1 -
.../modules/ROOT/pages/log4j-slf4j-impl.adoc | 1 -
.../modules/ROOT/pages/log4j-slf4j2-impl.adoc | 1 -
.../pages/log4j-spring-cloud-config-client.adoc | 9 ++---
.../antora/modules/ROOT/pages/log4j-to-jul.adoc | 1 -
.../antora/modules/ROOT/pages/log4j-to-slf4j.adoc | 1 -
.../modules/ROOT/pages/manual/appenders.adoc | 26 ++++++++-------
.../modules/ROOT/pages/manual/configuration.adoc | 18 ++++------
.../modules/ROOT/pages/manual/garbagefree.adoc | 23 ++++++++-----
.../modules/ROOT/pages/manual/installation.adoc | 3 +-
.../ROOT/pages/manual/json-template-layout.adoc | 2 +-
.../antora/modules/ROOT/pages/manual/layouts.adoc | 29 ++++++++++++++---
.../antora/modules/ROOT/pages/manual/logsep.adoc | 2 --
.../antora/modules/ROOT/pages/manual/lookups.adoc | 7 ++--
.../modules/ROOT/pages/manual/performance.adoc | 8 +++--
.../manual/dependencies-log4j-1.2-api.adoc | 38 ++++++++++++++++++++++
.../partials/manual/dependencies-log4j-csv.adoc | 37 +++++++++++++++++++++
.../dependencies-log4j-layout-template-json.adoc | 38 ++++++++++++++++++++++
.../properties-logger-context.adoc | 4 ++-
28 files changed, 230 insertions(+), 65 deletions(-)
diff --git a/pom.xml b/pom.xml
index c9b8408093..8b0a7134c9 100644
--- a/pom.xml
+++ b/pom.xml
@@ -338,6 +338,7 @@
<!-- Skipping `maven-site-plugin` globally. -->
<maven.site.skip>true</maven.site.skip>
<maven.site.deploy.skip>true</maven.site.deploy.skip>
+ <site-commons-csv.version>1.11.0</site-commons-csv.version>
<site-commons-logging.version>1.3.2</site-commons-logging.version>
<site-log4j-core.version>3.0.0-beta2</site-log4j-core.version>
<site-log4j-layout-template-json.version>3.0.0-beta2</site-log4j-layout-template-json.version>
@@ -743,6 +744,12 @@
<!-- Other dependencies -->
+ <dependency>
+ <groupId>org.apache.commons</groupId>
+ <artifactId>commons-csv</artifactId>
+ <version>${site-commons-csv.version}</version>
+ </dependency>
+
<dependency>
<groupId>commons-logging</groupId>
<artifactId>commons-logging</artifactId>
diff --git a/src/site/antora/antora.tmpl.yml b/src/site/antora/antora.tmpl.yml
index 670fc7c616..72403b4312 100644
--- a/src/site/antora/antora.tmpl.yml
+++ b/src/site/antora/antora.tmpl.yml
@@ -49,6 +49,7 @@ asciidoc:
log4j2-url: "https://logging.apache.org/log4j/2.x";
lmax-disruptor-url: "https://lmax-exchange.github.io/disruptor";
# Dependency versions
+ commons-csv-version: "${site-commons-csv.version}"
commons-logging-version: "${site-commons-logging.version}"
disruptor-version: "${site-disruptor.version}"
jackson-version: "${site-jackson.version}"
diff --git a/src/site/antora/antora.yml b/src/site/antora/antora.yml
index f8f8cae304..c0dcabf4e5 100644
--- a/src/site/antora/antora.yml
+++ b/src/site/antora/antora.yml
@@ -49,6 +49,7 @@ asciidoc:
log4j2-url: "https://logging.apache.org/log4j/2.x";
lmax-disruptor-url: "https://lmax-exchange.github.io/disruptor";
# Dependency versions
+ commons-csv-version: "1.2.3-commons-csv"
commons-logging-version: "1.2.3-commons-logging"
disruptor-version: "1.2.3-disruptor"
jackson-version: "1.2.3-jackson"
diff --git a/src/site/antora/modules/ROOT/pages/faq.adoc
b/src/site/antora/modules/ROOT/pages/faq.adoc
index dcbdf2bfb0..02b738e738 100644
--- a/src/site/antora/modules/ROOT/pages/faq.adoc
+++ b/src/site/antora/modules/ROOT/pages/faq.adoc
@@ -201,7 +201,8 @@ The problem with custom logger wrappers is that they have a
different FQCN than
The solution is to provide the correct FQCN.
The easiest way to do this is to let Log4j generate the logger wrapper for you.
Log4j comes with a Logger wrapper generator tool.
-This tool was originally meant to support custom log levels and is documented
{log4j2-url}/manual/customloglevels.adoc#CustomLoggers[here].
+This tool was originally meant to support custom log levels and was moved to
the
+link:/log4j/transform/latest/index.html[Log4j Transform subproject].
The generated logger code will take care of the FQCN.
[#proguard-rules]
diff --git a/src/site/antora/modules/ROOT/pages/getting-started.adoc
b/src/site/antora/modules/ROOT/pages/getting-started.adoc
index 6e779dc5c2..e04a714033 100644
--- a/src/site/antora/modules/ROOT/pages/getting-started.adoc
+++ b/src/site/antora/modules/ROOT/pages/getting-started.adoc
@@ -413,7 +413,7 @@ See xref:#config-test[]
For tests, prefer a human-readable layout with increased verbosity.
While it is not recommended to use the `PatternLayout` in production for
security reasons, it is a good choice for tests.
-The xref:manual/layouts.adoc#PatternLayout[Pattern Layout] is used for
formatting strings in a specific way.
+The xref:manual/layouts.adoc#pattern-layout[Pattern Layout] is used for
formatting strings in a specific way.
In the below case, it will include the timestamp, thread name, log level,
class name, and the message and
print it to the Console.
Very similar to the earlier configuration, the `<logger>` defines what should
be logged on
@@ -446,7 +446,7 @@ Save the following XML document to
`src/**test**/resources/log4j2-test.xml`.
</Configuration>
----
-<1> xref:manual/layouts.adoc#PatternLayout[Pattern Layout] is used for a
human-readable layout.
+<1> xref:manual/layouts.adoc#pattern-layout[Pattern Layout] is used for a
human-readable layout.
<2> Increased logging verbosity for the `com.mycompany` package.
[#next]
diff --git a/src/site/antora/modules/ROOT/pages/log4j-1.2-api.adoc
b/src/site/antora/modules/ROOT/pages/log4j-1.2-api.adoc
index edc33ee147..7ec6131be4 100644
--- a/src/site/antora/modules/ROOT/pages/log4j-1.2-api.adoc
+++ b/src/site/antora/modules/ROOT/pages/log4j-1.2-api.adoc
@@ -58,7 +58,16 @@ The following Log4j 1.x methods will behave differently when
the Log4j 2 Core mo
If log4j-core is not present location information will not be accurate in
calls using the Log4j 1.2 API.
The config package which attempts to convert Log4j 1.x configurations to Log4j
2 is not supported without Log4j 2.
-For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies].
+[NOTE]
+======
+In order to use the Log4j 1.2 Bridge, additional dependencies are required:
+
+.Runtime dependencies
+[%collapsible,id=log4j-1.2-api-deps]
+=====
+include::partial$manual/dependencies-log4j-1.2-api.adoc[]
+=====
+======
== Usage
diff --git a/src/site/antora/modules/ROOT/pages/log4j-docker.adoc
b/src/site/antora/modules/ROOT/pages/log4j-docker.adoc
index c4eb104814..669d0bf63c 100644
--- a/src/site/antora/modules/ROOT/pages/log4j-docker.adoc
+++ b/src/site/antora/modules/ROOT/pages/log4j-docker.adoc
@@ -40,5 +40,6 @@ Log4j Docker provides access to the following container
attributes:
Attributes may be accessed by adding `${docker:containerId}` to the
configuration.
Note that docker variables are only resolved once during logging
initialization so they shouldn't be referenced with more than one `$` character.
-== Requirements Log4j Docker requires Log4j Core, Log4j API and a minimum of
Java 8.
-For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies].
+== Requirements
+
+Log4j Docker requires Log4j Core, Log4j API and a minimum of Java 8.
diff --git a/src/site/antora/modules/ROOT/pages/log4j-flume-ng.adoc
b/src/site/antora/modules/ROOT/pages/log4j-flume-ng.adoc
index f612c78a80..3c6302c220 100644
--- a/src/site/antora/modules/ROOT/pages/log4j-flume-ng.adoc
+++ b/src/site/antora/modules/ROOT/pages/log4j-flume-ng.adoc
@@ -220,5 +220,6 @@ The following is a sample pom file for Maven that can be
used as a template for
</project>
----
-== Requirements The Flume Appender requires the Log4J 2 API.
-For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies].
+== Requirements
+
+The Flume Appender requires the Log4J 2 API and implementation.
diff --git a/src/site/antora/modules/ROOT/pages/log4j-iostreams.adoc
b/src/site/antora/modules/ROOT/pages/log4j-iostreams.adoc
index 66e1f90170..3edabf279a 100644
--- a/src/site/antora/modules/ROOT/pages/log4j-iostreams.adoc
+++ b/src/site/antora/modules/ROOT/pages/log4j-iostreams.adoc
@@ -18,13 +18,18 @@ Licensed to the Apache Software Foundation (ASF) under one
or more
== Log4j IOStreams
-The IOStreams component is a link:javadoc/log4j-api/index.html[Log4j API]
extension that provides numerous classes from
http://docs.oracle.com/javase/6/docs/api/java/io/package-summary.html[`java.io`]
that can either write to a
link:javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`] while
writing to another `OutputStream` or `Writer`, or the contents read by an
`InputStream` or `Reader` can be
http://www.eaipatterns.com/WireTap.html[wiretapped] by a `Logger`.
+The IOStreams component is a
+xref:manual/api.adoc[]
+extension that provides numerous classes from
+http://docs.oracle.com/javase/{java-target-version}/docs/api/java/io/package-summary.html[`java.io`]
+that can either write to a
+link:javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`]
+while writing to another `OutputStream` or `Writer`, or the contents read by
an `InputStream` or `Reader` can be
http://www.eaipatterns.com/WireTap.html[wiretapped] by a `Logger`.
== Requirements
The Log4j IOStreams API extension requires the Log4j 2 API.
This component was introduced in Log4j 2.1.
-For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies].
== Usage
diff --git a/src/site/antora/modules/ROOT/pages/log4j-jul.adoc
b/src/site/antora/modules/ROOT/pages/log4j-jul.adoc
index 70db576014..96fcce0abd 100644
--- a/src/site/antora/modules/ROOT/pages/log4j-jul.adoc
+++ b/src/site/antora/modules/ROOT/pages/log4j-jul.adoc
@@ -25,7 +25,6 @@ However, this does allow any other Log4j Provider besides the
Core provider to b
== Requirements
The JDK Logging Adapter is dependent on the Log4j API and optionally Log4j
Core.
-For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies].
== Usage
diff --git a/src/site/antora/modules/ROOT/pages/log4j-slf4j-impl.adoc
b/src/site/antora/modules/ROOT/pages/log4j-slf4j-impl.adoc
index ad4cc58d6f..36a85d33a6 100644
--- a/src/site/antora/modules/ROOT/pages/log4j-slf4j-impl.adoc
+++ b/src/site/antora/modules/ROOT/pages/log4j-slf4j-impl.adoc
@@ -30,7 +30,6 @@ As of release 2.19.0 the `log4j-slf4j18-impl` module
targetting the unreleased S
== Requirements
The Log4j 2 SLF4J Binding has a dependency on the Log4j 2 API as well as the
SLF4J API.
-For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies].
== Usage
diff --git a/src/site/antora/modules/ROOT/pages/log4j-slf4j2-impl.adoc
b/src/site/antora/modules/ROOT/pages/log4j-slf4j2-impl.adoc
index ad4cc58d6f..36a85d33a6 100644
--- a/src/site/antora/modules/ROOT/pages/log4j-slf4j2-impl.adoc
+++ b/src/site/antora/modules/ROOT/pages/log4j-slf4j2-impl.adoc
@@ -30,7 +30,6 @@ As of release 2.19.0 the `log4j-slf4j18-impl` module
targetting the unreleased S
== Requirements
The Log4j 2 SLF4J Binding has a dependency on the Log4j 2 API as well as the
SLF4J API.
-For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies].
== Usage
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 ce8e4b31ca..832bb19ad1 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
@@ -25,7 +25,7 @@ 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/systemproperties.adoc#log4j2.configurationFile[`log4j2.configurationFile`]
+xref:manual/systemproperties.adoc#log4j.configuration.location[`log4j.configuration.location`]
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.
@@ -125,12 +125,13 @@ 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/systemproperties.adoc#log4j2.configurationAuthorizationProvider[log4j2.configurationAuthorizationProvider]
+xref:manual/systemproperties.adoc#log4j.auth.provider[`log4j.auth.provider`]
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].
+For the properties required by TLS configuration see
+xref:manual/systemproperties
+.adoc#properties-transport-security[the Transport Security configuration].
== Requirements
The Log4j 2 Spring Cloud Configuration integration has a dependency on Log4j 2
API, Log4j 2 Core, and Spring Cloud Configuration versions 2.0.3.RELEASE or
2.1.1.RELEASE or later versions it either release series.
-For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies].
diff --git a/src/site/antora/modules/ROOT/pages/log4j-to-jul.adoc
b/src/site/antora/modules/ROOT/pages/log4j-to-jul.adoc
index 695a41c8d8..c3e2c4a788 100644
--- a/src/site/antora/modules/ROOT/pages/log4j-to-jul.adoc
+++ b/src/site/antora/modules/ROOT/pages/log4j-to-jul.adoc
@@ -24,7 +24,6 @@ With Log4j 2 as the implementation these would normally be
formatted only when t
== Requirements
The Log4j 2 to JUL adapter is dependent on the Log4j 2 API.
-For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies].
== Usage
diff --git a/src/site/antora/modules/ROOT/pages/log4j-to-slf4j.adoc
b/src/site/antora/modules/ROOT/pages/log4j-to-slf4j.adoc
index 45a090ffcf..3996e4ea0e 100644
--- a/src/site/antora/modules/ROOT/pages/log4j-to-slf4j.adoc
+++ b/src/site/antora/modules/ROOT/pages/log4j-to-slf4j.adoc
@@ -23,7 +23,6 @@ With Log4j 2 as the implementation these would normally be
formatted only when t
== Requirements
The Log4j 2 to SLF4J adapter is dependent on the Log4j 2 API and the SLF4J API.
-For more information, see xref:runtime-dependencies.adoc[Runtime Dependencies].
== Usage
diff --git a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc
b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc
index bffb31d569..7e6c8a87c7 100644
--- a/src/site/antora/modules/ROOT/pages/manual/appenders.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/appenders.adoc
@@ -59,7 +59,9 @@ If set to `true`, Log4j will flush all Java buffers at the
end of each event:
* for appenders based on Java's
https://docs.oracle.com/javase/{java-target-version}/docs/api/java/io/OutputStream.html[OutputStream]
a call to the `OutputStream.flush()` method is performed.
-* if
xref:manual/systemproperties.adoc#log4j2.enableDirectEncoders[log4j2.enableDirectEncoders]
is set to `true`, many Log4j appenders use a
+* if
+xref:manual/systemproperties.adoc#log4j.gc.enableDirectEncoders[log4j.gc.enableDirectEncoders]
+is set to `true`, many Log4j appenders use a
https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html[ByteBuffer]
to format log events before sending them to the underlying resource.
Setting `immediateFlush` to `true` flushes these buffers at each event.
@@ -81,7 +83,7 @@ By default, AsyncAppender uses
https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ArrayBlockingQueue.html[`java.util.concurrent.ArrayBlockingQueue`]
which does not require any external libraries.
Note that multi-threaded applications should exercise care when using this
appender as such: the blocking queue is susceptible to lock contention and our
-xref:manual/performance.adoc#asyncLogging[tests showed] performance may become
worse when more threads are logging concurrently.
+xref:manual/performance.adoc#async[tests showed] performance may become worse
when more threads are logging concurrently.
Consider using
xref:manual/async.adoc[lock-free Async Loggers] for optimal performance.
@@ -723,10 +725,8 @@ A sample FlumeAppender configuration that is configured
with a primary and a sec
As of Log4j 2.11.0, JDBC support has moved from the existing module
`log4j-core` to the new module `log4j-jdbc`.
-The JDBC Appender configured with a `DataSource` requires JNDI support so as
of release 2.17.1
-this appender will not function unless `log4j.jndi.enableJdbc=true` is
configured as a system property
-or environment variable. See the
xref:manual/systemproperties.adoc#log4j.jndi.enableJdbc[log4j.jndi.enableJdbc]
system
-property.
+The JDBC Appender configured with a `DataSource` requires JNDI support so as
of release 2.17.1 this appender will not function unless
`log4j2.enableJndiJdbc=true` is configured as a system property or environment
variable.
+See the
xref:manual/systemproperties.adoc#log4j.jndi.enableJdbc[log4j.jndi.enableJdbc]
system property.
The JDBCAppender writes log events to a relational database table using
standard JDBC.
It can be configured to obtain JDBC connections using a JNDI `DataSource` or a
custom factory method.
@@ -1078,7 +1078,8 @@ public class ConnectionFactory {
}
----
-This appender is xref:manual/messages.adoc#MapMessage[`MapMessage`]-aware.
+This appender is
+link:../../2.x/manual/messages.html#MapMessage[`MapMessage`]-aware.
The following configuration uses no layout to indicate that the appender
should match the keys of a `MapMessage` to the names of
`ColumnMapping`s when setting the values of the Appender's SQL INSERT
@@ -1867,7 +1868,8 @@ be increased to the nearest integer multiple of 256. See
the capped
collection documentation linked above for more information.
|=======================================================================
-This appender is xref:manual/messages.adoc#MapMessage[MapMessage]-aware.
+This appender is
+link:../../manual/messages.html#MapMessage[`MapMessage`]-aware.
Here are a few sample configurations for the NoSQLAppender and MongoDB4
provider:
@@ -1946,7 +1948,7 @@ The RandomAccessFileAppender is similar to the standard
link:#FileAppender[FileAppender] except it is always buffered (this cannot be
switched off) and internally it uses a
`ByteBuffer + RandomAccessFile` instead of a `BufferedOutputStream`.
We saw a 20-200% performance improvement compared to FileAppender with
"bufferedIO=true" in our
-xref:manual/performance.adoc#whichAppender[measurements].
+measurements.
Similar to the FileAppender, RandomAccessFileAppender uses a
RandomAccessFileManager to perform the file I/O. While RandomAccessFileAppender
from different Configurations cannot be shared, the RandomAccessFileManagers
can be if the Manager is accessible.
For example, two web applications in a servlet container can have their
configuration and safely write to the same file if Log4j is in a ClassLoader
that is common to both of them.
@@ -2697,7 +2699,8 @@ default is 1, meaning only the files in the specified
base directory.
false.
|testMode |boolean |If true, files are not deleted but instead a message
-is printed to the xref:manual/configuration.adoc#StatusMessages[status logger]
+is printed to the
+{log4j2-url}/manual/status-logger.html[status logger]
at INFO level. Use this to do a dry run to test if the configuration
works as expected. The default is false.
@@ -3115,8 +3118,7 @@ Below is a sample configuration that uses a
RollingFileAppender and defines diff
The RollingRandomAccessFileAppender is similar to the standard
link:#RollingFileAppender[RollingFileAppender] except it is always buffered
(this cannot be switched off) and internally it uses a
`ByteBuffer + RandomAccessFile` instead of a `BufferedOutputStream`.
-We saw a 20-200% performance improvement compared to RollingFileAppender with
"bufferedIO=true" in our
-xref:manual/performance.adoc#whichAppender[measurements].
+We saw a 20-200% performance improvement compared to RollingFileAppender with
"bufferedIO=true" in our measurements.
The
`RollingRandomAccessFileAppender` writes to the file named in the fileName
parameter and rolls the file over according to the TriggeringPolicy and the
RolloverPolicy.
Similar to the RollingFileAppender, RollingRandomAccessFileAppender uses a
RollingRandomAccessFileManager to perform the file I/O and perform the rollover.
diff --git a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
index 345dccea1c..675573b77e 100644
--- a/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/configuration.adoc
@@ -42,14 +42,6 @@ As detailed in the table below, some configuration formats
require additional de
include::partial$configuration-file-format-deps.adoc[]
-[WARNING]
-====
-The format of the configuration file changed between Log4j{nbsp}1 and
Log4j{nbsp}2.
-Files in the Log4j{nbsp}1 format are ignored by default.
-
-To enable partial support for old configuration formats, see
xref:manual/migration.adoc#enabling-the-log4j-1-x-bridge[Enabling the
Log4j{nbsp}1 bridge].
-====
-
[id=automatic-configuration]
=== [[AutomaticConfiguration]] Configuration file location
@@ -358,7 +350,8 @@ CustomLevels::
+
Log4j allows the configuration of custom log-level names.
+
-See xref:manual/customloglevels.adoc[Custom log level configuration] for
details.
+See
+{log4j2-url}/manual/customloglevels.html#DefiningLevelsInConfiguration[Defining
custom log levels in configuration] for details.
Filters::
+
@@ -502,7 +495,7 @@
include::example$manual/configuration/loggers.properties[tags=loggers]
In the example above, we have four logger configurations.
They differ from each other regarding the level of log messages that they
allow, whether
-xref:manual/layouts.adoc#location-information[location information]
+xref:manual/layouts.adoc#LocationInformation[location information]
will be printed, and which appenders will be used.
The table below summarizes the effects of each logger configuration:
@@ -628,7 +621,7 @@
https://logging.apache.org/log4j/2.x/javadoc/log4j-api/org/apache/logging/log4j/
.withLocation()]
methods.
-See xref:manual/layouts.adoc#location-information[Location information] for
more details.
+See xref:manual/layouts.adoc#LocationInformation[Location information] for
more details.
[id=logger-elements-appenderrefs]
==== Appender references
@@ -640,7 +633,8 @@ See <<configuring-appenderrefs>> below for more details.
[id=logger-elements-properties]
==== Additional context properties
-Loggers can emit additional context data that will be integrated with other
context data sources such as xref:manual/thread-context.adoc[ThreadContext].
+Loggers can emit additional context data that will be integrated with other
context data sources such as
+{log4j2-url}/manual/thread-context.html[ThreadContext].
[CAUTION]
====
diff --git a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc
b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc
index 15b8d6d93d..0bdb24bef7 100644
--- a/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/garbagefree.adoc
@@ -41,8 +41,8 @@ If you use another setup (e.g., a different logging API or
implementation) this
If you want to have a garbage-free Log4j setup, but don't want to spend time
with the associated details, you can quickly get started with the following
instructions:
. Set the following system properties to `true`:
-** xref:#log4j2.enableThreadlocals[`log4j2.enableThreadlocals`]
-**
xref:#log4j2.garbagefreeThreadContextMap[`log4j2.garbagefreeThreadContextMap`]
+** xref:#log4j.enableThreadlocals[`log4j.enableThreadlocals`]
+**
xref:#log4j.threadContext.map.garbageFree[`log4j.threadContext.map.garbageFree`]
. Use garbage-free
** xref:#Layouts[]
** xref:#Appenders[]
@@ -78,7 +78,6 @@ The following xref:manual/layouts.adoc[layouts] can be
configured to run garbage
To understand which configuration knobs exhibit what kind of allocation
behaviour, see their dedicated pages.
// Maintain the alphabetical ordering while making changes, please!
-* xref:manual/layouts.adoc#GELFLayout[`GelfLayout`]
* xref:manual/json-template-layout.adoc#faq-garbage-free[`JsonTemplateLayout`]
* xref:manual/layouts.adoc#PatternLayout-gcfree[`PatternLayout`]
@@ -120,7 +119,8 @@ Garbage-free xref:manual/appenders.adoc[appenders] need to
provide their xref:ma
An effort has been made to minimize impact on custom appenders that extend
`AbstractOutputStreamAppender`, but it is impossible to guarantee that changing
the superclass will not impact any and all subclasses.
Custom appenders that extend `AbstractOutputStreamAppender` should verify that
they still function correctly.
-In case there is a problem, xref:#log4j2.enableDirectEncoders[the
`log4j2.enableDirectEncoders` system property] can be set to `false` to revert
to the pre-Log4j 2.6 behaviour.
+In case there is a problem, the
+xref:#log4j.gc.enableDirectEncoders[`log4j.gc.enableDirectEncoders`]
configuration property can be set to `false` to revert to the pre-Log4j 2.6
behaviour.
=====
====
@@ -242,13 +242,16 @@ There are certain caveats associated with the
configuration of garbage-free logg
[#core-limitation-properties]
`<Properties>` section::
-A configuration containing
xref:manual/configuration.adoc#PropertySubstitution[a `<Properties>` section]
will result in temporary objects being created during steady-state logging.
+A configuration containing
xref:manual/configuration.adoc#property-substitution[a `<Properties>` section]
will result in temporary
+objects being created during steady-state logging.
[#core-limitation-async-logger-wait-strategy]
Asynchronous logger wait strategies::
As of version `2.18.0`, the default xref:manual/async.adoc[asynchronous
logger] wait strategy (i.e., `Timeout`) is garbage-free while running against
both LMAX Disruptor 3 and 4.
-See
xref:manual/async.adoc#log4j2.asyncLoggerWaitStrategy[`log4j2.asyncLoggerWaitStrategy`]
for details on predefined wait strategies.
+See
+xref:manual/async.adoc#log4j.async.logger.waitStrategy.type[`log4j.async.logger.waitStrategy.type`]
+for details on predefined wait strategies.
[#api]
== Log4j API usage
@@ -299,10 +302,14 @@ The `Unbox.box(primitive)` methods write directly into a
`StringBuilder`, and th
Not all Log4j API feature set is garbage-free, specifically:
-* The `ThreadContext` map (aka. MDC) is not garbage-free by default, but can
be configured to be garbage-free by setting
xref:#log4j2.garbagefreeThreadContextMap[the
`log4j2.garbagefreeThreadContextMap` system property] to `true`.
+* The `ThreadContext` map (aka. MDC) is not garbage-free by default, but can
be configured to be garbage-free by setting the
+xref:#log4j.threadContext.map.garbageFree[`log4j.threadContext.map.garbageFree`]
+configuration property to `true`.
* The `ThreadContext` stack (aka. NDC) is not garbage-free.
* {log4j2-url}/manual/scoped-context.adoc[] is not garbage-free.
-* Logging very large messages (i.e., more than
xref:#log4j2.maxReusableMsgSize[`log4j2.maxReusableMsgSize`] characters, which
defaults to 518), when all loggers are xref:manual/async.adoc[asynchronous
loggers], will cause the internal `StringBuilder` in the
+* Logging very large messages (i.e., more than
+xref:#log4j.gc.maxReusableMsgSize[`log4j.gc.maxReusableMsgSize`]
+characters, which defaults to 518), when all loggers are
xref:manual/async.adoc[asynchronous loggers], will cause the internal
`StringBuilder` in the
`RingBuffer` to be trimmed back to their configured maximum size.
* Logging messages containing `$\{variable}` substitutions creates temporary
objects.
* Logging a lambda as a parameter:
diff --git a/src/site/antora/modules/ROOT/pages/manual/installation.adoc
b/src/site/antora/modules/ROOT/pages/manual/installation.adoc
index ba3f9d7f88..bc538a066a 100644
--- a/src/site/antora/modules/ROOT/pages/manual/installation.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/installation.adoc
@@ -628,7 +628,8 @@ Loggers.Root.AppenderRef.ref = CONSOLE
----
====
-<1> While xref:manual/layouts.adoc#PatternLayout[Pattern Layout] is a good
first choice and preferable for tests, we recommend using a structured format
such as xref:manual/json-template-layout.adoc[] for production deployments.
+<1> While xref:manual/layouts.adoc#pattern-layout[Pattern Layout] is a good
first choice and preferable for tests, we recommend
+using a structured format such as xref:manual/json-template-layout.adoc[] for
production deployments.
To use these formats, the following additional dependencies are required:
diff --git
a/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc
b/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc
index 933afd5790..b07e482433 100644
--- a/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/json-template-layout.adoc
@@ -1121,7 +1121,7 @@ pattern = "pattern" -> string
stackTraceEnabled = "stackTraceEnabled" -> boolean
----
-Resolver delegating to xref:manual/layouts.adoc#PatternLayout[`PatternLayout`].
+Resolver delegating to
xref:manual/layouts.adoc#pattern-layout[`PatternLayout`].
The default value of `stackTraceEnabled` is inherited from the parent
`JsonTemplateLayout`.
diff --git a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
index 0cb3fe1fef..53c7fdac86 100644
--- a/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/layouts.adoc
@@ -154,8 +154,16 @@ 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.
+[NOTE]
+======
+Additional runtime dependencies are required for using CSV layouts:
+
+.Runtime dependencies
+[%collapsible,id=log4j-csv-deps]
+=====
+include::partial$manual/dependencies-log4j-csv.adoc[]
+=====
+======
[#HTMLLayout]
== HTML Layout
@@ -325,6 +333,17 @@ JSON Template Layout will render JSON documents as follows:
}
----
+[NOTE]
+======
+Additional runtime dependencies are required for using JSON Template Layout:
+
+.Runtime dependencies
+[%collapsible,id=log4j-layout-template-json-deps]
+=====
+include::partial$manual/dependencies-log4j-layout-template-json.adoc[]
+=====
+======
+
See xref:manual/json-template-layout.adoc[JSON Template Layout] page for the
complete documentation.
[id=pattern-layout]
@@ -1539,7 +1558,7 @@ If the Marker in the log event is equal to or is an
ancestor of the name specifi
==== ScriptPatternSelector
The ScriptPatternSelector executes a script as described in the
-xref:manual/configuration.adoc#Scripts[Scripts] section of the Configuration
chapter.
+xref:manual/scripts.adoc[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 Configuration 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]
@@ -1751,7 +1770,9 @@ To get the most out of it, mind the following checklist:
* Enable xref:manual/garbagefree.adoc[garbage-free logging]
* Mind xref:#PatternLayout-gcfree[the garbage footprint of features you use]
-* Don't give too much slack to
xref:manual/configuration.adoc#log4j2.layoutStringBuilderMaxSize[`log4j2.layoutStringBuilderMaxSize`]
and try to keep it relatively tight
+* Don't give too much slack to
+xref:manual/systemproperties.adoc#log4j.gc.layoutStringBuilderMaxSize[`log4j.gc.layoutStringBuilderMaxSize`]
+and try to keep it relatively tight
[#RFC5424Layout]
== RFC5424 Layout
diff --git a/src/site/antora/modules/ROOT/pages/manual/logsep.adoc
b/src/site/antora/modules/ROOT/pages/manual/logsep.adoc
index 12772221b8..8e96a645a7 100644
--- a/src/site/antora/modules/ROOT/pages/manual/logsep.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/logsep.adoc
@@ -111,8 +111,6 @@ or environment variable. See the
xref:manual/systemproperties.adoc#log4j.jndi.enableContextSelector[log4j.jndi.enableContextSelector]
configuration property.
-xref:manual/systemproperties.adoc#log4j2
-
The exact method for setting system properties depends on the container.
For Tomcat, edit `$CATALINA_HOME/conf/catalina.properties`. Consult the
documentation for other web containers.
diff --git a/src/site/antora/modules/ROOT/pages/manual/lookups.adoc
b/src/site/antora/modules/ROOT/pages/manual/lookups.adoc
index 4f5bdb64c3..d586519c41 100644
--- a/src/site/antora/modules/ROOT/pages/manual/lookups.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/lookups.adoc
@@ -21,7 +21,7 @@ arbitrary places. They are a particular type of Plugin that
implements
the
link:../javadoc/log4j-core/org/apache/logging/log4j/core/lookup/StrLookup.html[`StrLookup`]
interface. Information on how to use Lookups in configuration files can
-be found in the xref:manual/configuration.adoc#PropertySubstitution[Property
+be found in the xref:manual/configuration.adoc#property-substitution[Property
Substitution] section of the xref:manual/configuration.adoc[Configuration]
page.
@@ -269,7 +269,8 @@ For example:
As of Log4j 2.15.1 JNDI operations require that `log4j2.enableJndi=true` be
set as a system property or the
corresponding environment variable for this lookup to function. See the
-xref:manual/configuration.adoc#enableJndiLookup[log4j2.enableJndiLookup]
system property.
+xref:manual/systemproperties.adoc#log4j.jndi.enableLookup[log4j.jndi.enableLookup]
+system property.
The JndiLookup allows variables to be retrieved via JNDI. By default the
key will be prefixed with java:comp/env/, however if the key contains a
@@ -448,7 +449,7 @@ RollingFileAppender for each unique value of the key named
"type" in the
MapMessage. Note that when used this way a value for "type" should be
declared in the properties declaration to provide a default value in
case the message is not a MapMessage or the MapMessage does not contain
-the key. See the xref:manual/configuration.adoc#PropertySubstitution[Property
+the key. See the xref:manual/configuration.adoc#property-substitution[Property
Substitution] section of the xref:manual/configuration.adoc[Configuration]
page for information on how to set the default values.
diff --git a/src/site/antora/modules/ROOT/pages/manual/performance.adoc
b/src/site/antora/modules/ROOT/pages/manual/performance.adoc
index c9234574d5..0a188929f5 100644
--- a/src/site/antora/modules/ROOT/pages/manual/performance.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/performance.adoc
@@ -75,7 +75,9 @@ Consider the following example:
/* BAD! */ LOGGER.info("failed for user ID `{}` and role `{}`", userId,
db.findUserRoleById(userId));
----
-The database query (i.e., `db.findUserNameById(userId)`) can be a significant
bottleneck if the created the log event will be discarded anyway – maybe the
`INFO` level or the associated xref:manual/markers.adoc[marker] is not accepted
for this package, or due to some other filtering.
+The database query (i.e., `db.findUserNameById(userId)`) can be a significant
bottleneck if the created the log event will be discarded anyway – maybe the
`INFO` level or the associated
+{log4j2-url}/manual/markers.html[marker]
+is not accepted for this package, or due to some other filtering.
* [ ] The old-school way of solving this problem is to level-guard the log
statement:
+
@@ -84,7 +86,9 @@ The database query (i.e., `db.findUserNameById(userId)`) can
be a significant bo
/* BAD! */ if (LOGGER.isInfoEnabled()) { LOGGER.info(...); }
----
+
-While this would work for cases where the message can be dropped due to
insufficient level, this approach is still prone to other filtering cases;
e.g., maybe the associated xref:manual/markers.adoc[marker] is not accepted.
+While this would work for cases where the message can be dropped due to
insufficient level, this approach is still prone to other filtering cases;
e.g., maybe the associated
+{log4j2-url}/manual/markers.html[marker]
+is not accepted.
* [x] Use ``Supplier``s to pass arguments containing computationally expensive
items:
+
diff --git
a/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-1.2-api.adoc
b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-1.2-api.adoc
new file mode 100644
index 0000000000..349feafc4c
--- /dev/null
+++
b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-1.2-api.adoc
@@ -0,0 +1,38 @@
+////
+ 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.
+////
+
+[tabs]
+====
+Maven::
++
+[source,xml,subs="+attributes"]
+----
+<dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-1.2-api</artifactId>
+ <version>{log4j-core-version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
+
+Gradle::
++
+[source,groovy,subs="+attributes"]
+----
+runtimeOnly 'org.apache.logging.log4j:log4j-1.2-api:{log4j-core-version}'
+----
+====
\ No newline at end of file
diff --git
a/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-csv.adoc
b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-csv.adoc
new file mode 100644
index 0000000000..98b59624fb
--- /dev/null
+++ b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-csv.adoc
@@ -0,0 +1,37 @@
+////
+ 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.
+////
+
+[tabs]
+====
+Maven::
++
+[source,xml,subs="+attributes"]
+----
+<dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-csv</artifactId>
+ <scope>runtime</scope>
+</dependency>
+----
+
+Gradle::
++
+[source,groovy,subs="+attributes"]
+----
+runtimeOnly 'org.apache.logging.log4j:log4j-csv'
+----
+====
\ No newline at end of file
diff --git
a/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-template-json.adoc
b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-template-json.adoc
new file mode 100644
index 0000000000..644d2c5115
--- /dev/null
+++
b/src/site/antora/modules/ROOT/partials/manual/dependencies-log4j-layout-template-json.adoc
@@ -0,0 +1,38 @@
+////
+ 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.
+////
+
+[tabs]
+====
+Maven::
++
+[source,xml,subs="+attributes"]
+----
+<dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-layout-template-json</artifactId>
+ <version>{log4j-layout-template-json-version}</version>
+ <scope>runtime</scope>
+</dependency>
+----
+
+Gradle::
++
+[source,groovy,subs="+attributes"]
+----
+runtimeOnly
'org.apache.logging.log4j:log4j-layout-template-json:{log4j-layout-template-json-version}'
+----
+====
\ No newline at end of file
diff --git
a/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-logger-context.adoc
b/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-logger-context.adoc
index 15045d638b..33ec0fa811 100644
---
a/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-logger-context.adoc
+++
b/src/site/antora/modules/ROOT/partials/manual/systemproperties/properties-logger-context.adoc
@@ -95,6 +95,8 @@ The default implementation executes all shutdown actions in a
separate `Thread`
| Default value | `false`
|===
-Prints a stacktrace to the
xref:manual/configuration.adoc#StatusMessages[status logger] at `DEBUG` level
when the LoggerContext is started.
+Prints a stacktrace to the
+{log4j2-url}/manual/status-logger.html[status logger]
+at `DEBUG` level when the LoggerContext is started.
For debug purposes only.
