This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch 2.x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
The following commit(s) were added to refs/heads/2.x by this push:
new 91c2923d31 Revamp the `Concepts` in the `Installation` (#2561)
91c2923d31 is described below
commit 91c2923d31841df870319f20542a1391f374f24f
Author: Volkan Yazıcı <[email protected]>
AuthorDate: Thu May 2 21:03:26 2024 +0200
Revamp the `Concepts` in the `Installation` (#2561)
---
antora-playbook.yaml | 3 +
package.json | 1 +
.../modules/ROOT/pages/manual/installation.adoc | 233 ++++++++++++++-------
3 files changed, 161 insertions(+), 76 deletions(-)
diff --git a/antora-playbook.yaml b/antora-playbook.yaml
index 6bafbcabee..52f1d254bc 100644
--- a/antora-playbook.yaml
+++ b/antora-playbook.yaml
@@ -38,8 +38,11 @@ asciidoc:
log4j-docgen-type-filter-exclude-pattern: ^java\..+
log4j-docgen-type-target-template: |
#{{{replaceAll sourcedType.groupId "." "-"}}}_{{{replaceAll
sourcedType.artifactId "." "-"}}}_{{{replaceAll sourcedType.type.className "."
"-"}}}
+ # Force Kroki to download images at build time
+ kroki-fetch-diagram: true
extensions:
- "@asciidoctor/tabs"
+ - asciidoctor-kroki
- src/docgen/apiref-macro.js
ui:
diff --git a/package.json b/package.json
index 8de82aed5b..df223e24ef 100644
--- a/package.json
+++ b/package.json
@@ -3,6 +3,7 @@
"@antora/cli": "^3.2.0-alpha.4",
"@antora/site-generator-default": "^3.2.0-alpha.4",
"@asciidoctor/tabs": "^1.0.0-beta.6",
+ "asciidoctor-kroki": "^0.18.1",
"fast-xml-parser": "^4.3.6",
"handlebars": "^4.7.8"
}
diff --git a/src/site/antora/modules/ROOT/pages/manual/installation.adoc
b/src/site/antora/modules/ROOT/pages/manual/installation.adoc
index 1e027bb745..5ced130c91 100644
--- a/src/site/antora/modules/ROOT/pages/manual/installation.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/installation.adoc
@@ -72,27 +72,78 @@ In the case of Log4j, the API is called _Log4j API_, and
its reference implement
[#logging-bridge]
Logging bridge::
Logging implementations accept input from a single logging API of their
preference; Log4j Core from Log4j API, Logback from SLF4J, etc.
-A logging bridge is a simple logging implementation of a logging API that
forward all messages to a foreign logging API.
+A logging bridge is a simple logging implementation of a logging API that
forwards all messages to a foreign logging API.
Logging bridges allow a logging implementation to accept input from other
logging APIs that are not their primary logging API.
For instance, `log4j-slf4j2-impl` _bridges_ SLF4J calls to Log4 API and
effectively enables Log4j Core to accept input from SLF4J.
With this in mind, the type of software you are writing determines whether you
should be installing a logging API, implementation, or bridge:
Libraries::
-only require a logging API and delegate the choice of the implementation to
applications.
+They only require a logging API and delegate the choice of the implementation
to applications.
If a logging implementation is required by tests of the library, it should be
in the appropriate test scope.
Applications::
-need a logging implementation, but also bridges of each of the major logging
APIs to support log statements from the libraries they use.
+They need a logging implementation, but also bridges of each of the major
logging APIs to support log statements from the libraries they use.
For instance, your application might be logging against Log4j API and one of
its dependencies against SLF4J.
In this case, you need to install `log4j-core` and `log4j-slf4j2-impl`.
(This is an example, we will elaborate on this case more in <<impl-core>>.)
+To make things a little bit more tangible, consider the following
visualization of a typical Log4j Core installation with bridges for an
application:
+
+.Visualization of a typical Log4j Core installation with SLF4J, JUL, and JPL
bridges.
+[ditaa]
+....
+/-----------------------------------------------------------------------------------\
+|
|
+| +------------+ +----------+
+----------+ |
+| | | | | |
| |
+| | v | v |
v |
+| +-----+-----+ +---------+ +---------+ +----+----+ +-------+ +----+----+
+-------+ |
+| | | |{d}c1FF | | | | | |{d}c1FF| | |
|{d}c1FF| |
+| |Application| |Log4j API| |Library 1| |Library 2| | SLF4J | |Library 3| |
JUL | |
+| | | | | | | | | | | | | |
| |
+| +-----------+ +--+------+ +----+----+ +---------+ +---+---+ +---------+
+---+---+ |
+| : ^ | :
: |
+| | | | |
| |
+| Compile time | | | |
| |
+\------------------|---|---------|----------------------|---------------------|-----/
+ | | | | |
+ | | | /-----/ /-----------/
+ | | | | |
+ /----------/ \------+--|----------+-----|---------\ |
+ | | | | | | |
+/-------|---------------------|--|----------|-----|---------|-----|-----------------\
+| | | | | | | |
Runtime |
+| v : | : v : v
|
+| +----------+ +-----+------+ +----+---------+ +---+--------+
|
+| |cGRE | |cYEL | |cYEL | |cYEL |
|
+| |Log4j Core| |JPL to Log4j| |SLF4J to Log4j| |JUL to Log4j|
|
+| | | | | | | | |
|
+| +----------+ +------------+ +--------------+ +------------+
|
+| |log4j2.xml| ^ |
|
+| +----------+ | |
|
+| | |
|
+| | |
|
+| /-------------+--|--/
|
+| | | |
|
+|
+----------+-------------|--|---------------------------------------------------+
|
+| |JRE v :
| |
+| | +----+--+
| |
+| | |{d}c1FF|
| |
+| | | JPL |
| |
+| | | |
| |
+| | +-------+
| |
+| |
| |
+|
+-------------------------------------------------------------------------------+
|
+|
|
+\-----------------------------------------------------------------------------------/
+....
+
[#requirements]
== Requirements
The Log4j 2 runtime requires a minimum of Java {java-target-version}.
-See xref:index.adoc#older-releases[older releases] for the latest releases
supporting Java 6 and 7.
+See xref:download.adoc#older[the Download page] for older releases supporting
Java 6 and 7.
[#build-tool]
== Configuring the build tool
@@ -195,8 +246,8 @@ Maven::
[source,xml]
----
<dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-api</artifactId>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-api</artifactId>
</dependency>
----
@@ -215,6 +266,7 @@ Log4j provides several modules to facilitate deployment of
different logging imp
`log4j-core`::
The reference implementation.
+Log4 Core primarily accepts input from Log4j API.
Refer to <<impl-core>> for the installation instructions.
`log4j-to-jul`::
@@ -269,12 +321,16 @@ Maven::
[source,xml]
----
<dependencies>
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-core</artifactId>
- <scope>runtime</scope>
- </dependency>
- <!-- Logging bridges will follow... -->
+
+ <!-- Logging implementation (Log4j Core) -->
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-core</artifactId>
+ <scope>runtime</scope>
+ </dependency>
+
+ <!-- Logging bridges will follow... -->
+
</dependencies>
----
@@ -291,6 +347,17 @@ runtimeOnly 'org.apache.logging.log4j:log4j-core'
==== Installing bridges
If either your application or one if its dependencies logs against a logging
API that is different from Log4j API, you need to xref:#logging-bridge[bridge]
that API to Log4j API.
+
+[TIP]
+====
+**Do you need bridges?
+And if so, which ones?**
+
+* If you have any direct or transitive dependency on `org.slf4j:slf4j-api`,
you need xref:#impl-core-bridge-slf4j[the SLF4J-to-Log4j bridge].
+* If you have any direct or transitive dependency on
`commons-logging:commons-logging`, you need xref:#impl-core-bridge-jcl[the
JCL-to-Log4j bridge].
+* If it is a standalone application (i.e., not running in a Java EE
container), you will probably need xref:#impl-core-bridge-jul[JUL-to-Log4j] and
xref:#impl-core-bridge-jpl[JPL-to-Log4j] bridges.
+====
+
Following sections explain installation of Log4j-provided bridges.
[#impl-core-bridge-slf4j]
@@ -306,9 +373,9 @@ Maven::
----
<!-- SLF4J-to-Log4j bridge -->
<dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-slf4j2-impl</artifactId>
- <scope>runtime</scope>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-slf4j2-impl</artifactId>
+ <scope>runtime</scope>
</dependency>
----
@@ -333,9 +400,9 @@ Maven::
----
<!-- JUL-to-Log4j bridge -->
<dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-jul</artifactId>
- <scope>runtime</scope>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-jul</artifactId>
+ <scope>runtime</scope>
</dependency>
----
@@ -369,9 +436,9 @@ Maven::
----
<!-- JPL-to-Log4j bridge -->
<dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-jpl</artifactId>
- <scope>runtime</scope>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-jpl</artifactId>
+ <scope>runtime</scope>
</dependency>
----
@@ -399,11 +466,11 @@ Maven users should add an entry to the
`<dependencyManagement>` section of their
[source,xml,subs="+attributes"]
----
<dependencyManagement>
- <dependency>
- <groupId>commons-logging</groupId>
- <artifactId>commons-logging</artifactId>
- <version>{commons-logging-version}</version>
- </dependency>
+ <dependency>
+ <groupId>commons-logging</groupId>
+ <artifactId>commons-logging</artifactId>
+ <version>{commons-logging-version}</version>
+ </dependency>
</dependencyManagement>
----
@@ -431,21 +498,24 @@ Maven::
[source,xml]
----
<dependencies>
- <dependency>
- <groupId>org.springframework.boot</groupId>
- <artifactId>spring-boot-starter</artifactId>
- <exclusions>
- <exclusion>
- <groupId>org.springframework.boot</groupId>
- <artifactId>spring-boot-starter-logging</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- <dependency>
+
+ <dependency>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-starter</artifactId>
+ <exclusions>
+ <exclusion>
<groupId>org.springframework.boot</groupId>
- <artifactId>spring-boot-starter-log4j2</artifactId>
- <scope>runtime</scope>
- </dependency>
+ <artifactId>spring-boot-starter-logging</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+
+ <dependency>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-starter-log4j2</artifactId>
+ <scope>runtime</scope>
+ </dependency>
+
</dependencies>
----
@@ -454,11 +524,11 @@ Gradle::
[source,groovy]
----
configurations {
- all.exclude group: 'org.springframework.boot', module:
'spring-boot-starter-logging'
+ all.exclude group: 'org.springframework.boot', module:
'spring-boot-starter-logging'
}
dependencies {
- runtimeOnly group: 'org.springframework.boot', module:
'spring-boot-starter-log4j2'
+ runtimeOnly group: 'org.springframework.boot', module:
'spring-boot-starter-log4j2'
}
----
@@ -488,16 +558,19 @@ log4j2.xml::
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xsi:schemaLocation="https://logging.apache.org/xml/ns
https://logging.apache.org/xml/ns/log4j-config-2.xsd";>
+
<appenders>
<Console name="CONSOLE">
<PatternLayout pattern="%d [%t] %5p %c{1.} - %m%n"/><!--1-->
</Console>
</appenders>
+
<loggers>
<root level="INFO">
<AppenderRef ref="CONSOLE"/>
</root>
- </Loggers>
+ </loggers>
+
</Configuration>
----
@@ -578,10 +651,10 @@ log4j2.json::
[source,xml,subs="+attributes"]
----
<dependency>
- <groupId>com.fasterxml.jackson.core</groupId>
- <artifactId>jackson-databind</artifactId>
- <version>{jackson-version}</version>
- <scope>runtime</scope>
+ <groupId>com.fasterxml.jackson.core</groupId>
+ <artifactId>jackson-databind</artifactId>
+ <version>{jackson-version}</version>
+ <scope>runtime</scope>
</dependency>
----
@@ -590,10 +663,10 @@ log4j2.yaml::
[source,xml,subs="+attributes"]
----
<dependency>
- <groupId>com.fasterxml.jackson.dataformat</groupId>
- <artifactId>jackson-dataformat-yaml</artifactId>
- <version>{jackson-version}</version>
- <scope>runtime</scope>
+ <groupId>com.fasterxml.jackson.dataformat</groupId>
+ <artifactId>jackson-dataformat-yaml</artifactId>
+ <version>{jackson-version}</version>
+ <scope>runtime</scope>
</dependency>
----
@@ -653,20 +726,24 @@ Maven::
[source,xml,subs="+attributes"]
----
<dependencies>
+
<!-- Log4j-to-JUL bridge -->
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-to-jul</artifactId>
- <scope>runtime</scope>
- </dependency>
- <!-- SLF4J-to-JUL bridge -->
- <dependency>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-jdk14</artifactId>
- <version>{slf4j-version}</version>
- <scope>runtime</scope>
- </dependency>
- <!-- ... -->
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-to-jul</artifactId>
+ <scope>runtime</scope>
+ </dependency>
+
+ <!-- SLF4J-to-JUL bridge -->
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-jdk14</artifactId>
+ <version>{slf4j-version}</version>
+ <scope>runtime</scope>
+ </dependency>
+
+ <!-- ... -->
+
</dependencies>
----
@@ -695,18 +772,22 @@ Maven::
[source,xml]
----
<dependencies>
- <dependency>
- <groupId>ch.qos.logback</groupId>
- <artifactId>logback-classic</artifactId>
- <version>{logback-version}</version>
- <scope>runtime</scope>
- </dependency>
- <!-- Log4j-to-SLF4J bridge -->
- <dependency>
- <groupId>org.apache.logging.log4j</groupId>
- <artifactId>log4j-to-slf4j</artifactId>
- <scope>runtime</scope>
- </dependency>
+
+ <!-- Logging implementation (Logback) -->
+ <dependency>
+ <groupId>ch.qos.logback</groupId>
+ <artifactId>logback-classic</artifactId>
+ <version>{logback-version}</version>
+ <scope>runtime</scope>
+ </dependency>
+
+ <!-- Log4j-to-SLF4J bridge -->
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-to-slf4j</artifactId>
+ <scope>runtime</scope>
+ </dependency>
+
</dependencies>
----
