You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by vy...@apache.org on 2024/05/01 14:47:24 UTC
(logging-log4j2) branch doc/2.x/5min updated (fe1fddf272 -> 3c280ca41a)
This is an automated email from the ASF dual-hosted git repository.
vy pushed a change to branch doc/2.x/5min
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
discard fe1fddf272 Add `Learn Log4j under 5 minutes!` page
new 3c280ca41a Add `Learn Log4j in 5 minutes!` page
This update added new revisions after undoing existing revisions.
That is to say, some revisions that were in the old version of the
branch are not in the new version. This situation occurs
when a user --force pushes a change and generates a repository
containing something like this:
* -- * -- B -- O -- O -- O (fe1fddf272)
\
N -- N -- N refs/heads/doc/2.x/5min (3c280ca41a)
You should already have received notification emails for all of the O
revisions, and so the following emails describe only the N revisions
from the common base, B.
Any revisions marked "omit" are not gone; other references still
refer to them. Any revisions marked "discard" are gone forever.
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
src/site/antora/modules/ROOT/pages/5min.adoc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
(logging-log4j2) 01/01: Add `Learn Log4j in 5 minutes!` page
Posted by vy...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
vy pushed a commit to branch doc/2.x/5min
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit 3c280ca41a6ee823ff13315babab7655050aab0a
Author: Volkan Yazıcı <vo...@yazi.ci>
AuthorDate: Wed May 1 16:43:09 2024 +0200
Add `Learn Log4j in 5 minutes!` page
---
src/site/antora/modules/ROOT/nav.adoc | 71 ++--
src/site/antora/modules/ROOT/pages/5min.adoc | 453 +++++++++++++++++++++
src/site/antora/modules/ROOT/pages/download.adoc | 10 +
src/site/antora/modules/ROOT/pages/index.adoc | 30 +-
.../modules/ROOT/pages/manual/installation.adoc | 21 +-
5 files changed, 521 insertions(+), 64 deletions(-)
diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc
index abcc645e4e..b7789787fd 100644
--- a/src/site/antora/modules/ROOT/nav.adoc
+++ b/src/site/antora/modules/ROOT/nav.adoc
@@ -22,43 +22,46 @@
** link:{logging-services-url}/security[Security]
** xref:thanks.adoc[Thanks]
-.Learn
-* xref:manual/index.adoc[]
-** xref:manual/installation.adoc[]
-** xref:manual/architecture.adoc[]
-** xref:manual/migration.adoc[]
-** xref:manual/api.adoc[]
-*** xref:manual/logbuilder.adoc[]
-*** xref:manual/flowtracing.adoc[]
-*** xref:manual/markers.adoc[]
-*** xref:manual/eventlogging.adoc[]
-*** xref:manual/messages.adoc[]
-*** xref:manual/thread-context.adoc[]
-*** xref:manual/scoped-context.adoc[]
-*** xref:manual/resource-logger.adoc[]
-** xref:manual/configuration.adoc[]
-** xref:manual/usage.adoc[]
-** xref:manual/cloud.adoc[]
-** xref:manual/lookups.adoc[]
-** xref:manual/appenders.adoc[]
-** xref:manual/layouts.adoc[]
-*** xref:manual/json-template-layout.adoc[]
-** xref:manual/filters.adoc[]
-** xref:manual/async.adoc[]
-** xref:manual/garbagefree.adoc[]
-** xref:manual/extending.adoc[]
-** xref:manual/plugins.adoc[]
-** xref:manual/customconfig.adoc[]
-** xref:manual/customloglevels.adoc[]
-** xref:manual/jmx.adoc[]
-** xref:manual/logsep.adoc[]
-** xref:manual/performance.adoc[]
-* xref:plugin-reference.adoc[Plugin reference]
-* xref:javadoc.adoc[Java API reference]
-* xref:articles.adoc[Articles]
+.Resources
* xref:faq.adoc[F.A.Q.]
+* xref:5min.adoc[]
* xref:development.adoc[]
+.xref:manual/index.adoc[]
+* xref:manual/installation.adoc[]
+* xref:manual/architecture.adoc[]
+* xref:manual/migration.adoc[]
+* xref:manual/api.adoc[]
+** xref:manual/logbuilder.adoc[]
+** xref:manual/flowtracing.adoc[]
+** xref:manual/markers.adoc[]
+** xref:manual/eventlogging.adoc[]
+** xref:manual/messages.adoc[]
+** xref:manual/thread-context.adoc[]
+** xref:manual/scoped-context.adoc[]
+** xref:manual/resource-logger.adoc[]
+* xref:manual/configuration.adoc[]
+* xref:manual/usage.adoc[]
+* xref:manual/cloud.adoc[]
+* xref:manual/lookups.adoc[]
+* xref:manual/appenders.adoc[]
+* xref:manual/layouts.adoc[]
+** xref:manual/json-template-layout.adoc[]
+* xref:manual/filters.adoc[]
+* xref:manual/async.adoc[]
+* xref:manual/garbagefree.adoc[]
+* xref:manual/extending.adoc[]
+* xref:manual/plugins.adoc[]
+* xref:manual/customconfig.adoc[]
+* xref:manual/customloglevels.adoc[]
+* xref:manual/jmx.adoc[]
+* xref:manual/logsep.adoc[]
+* xref:manual/performance.adoc[]
+
+.References
+* xref:plugin-reference.adoc[Plugin reference]
+* xref:javadoc.adoc[Java API reference]
+
.Components
* xref:log4j-api.adoc[]
* xref:log4j-1.2-api.adoc[]
diff --git a/src/site/antora/modules/ROOT/pages/5min.adoc b/src/site/antora/modules/ROOT/pages/5min.adoc
new file mode 100644
index 0000000000..6f1d532ddc
--- /dev/null
+++ b/src/site/antora/modules/ROOT/pages/5min.adoc
@@ -0,0 +1,453 @@
+////
+ 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.
+////
+
+= Learn Log4j in 5 minutes!
+
+You need a crash course on Log4j?
+You are at the right place!
+
+[#what]
+== What is logging and Log4j?
+
+Logging is the action of publishing diagnostics information at certain points of a program execution:
+
+[source,java]
+----
+private void truncateTable(String tableName) {
+ System.out.format("[WARN] Truncating table `%s`!%n", tableName);
+ db.truncate(tableName);
+}
+----
+
+This provides observability into an application's runtime. (See {logging-services-url}/what-is-logging.html[What is logging?] page for a longer read.)
+
+But we can do way better than a `printf()` statement!
+
+* Enhance the output with additional information (timestamp, class & method name, line number, host, severity, etc.)
+* Use different **layouts** (CSV, JSON, etc.)
+* Forward to different **appenders** (file, socket, database, queue, etc.)
+* **Filter** on demand (e.g., increase verbosity dynamically for troubleshooting purposes)
+
+Log4j is versatile, industrial-grade Java logging framework delivering all these and more in one product.
+It is essentially composed of a **logging API** and its **implementation**:
+
+Log4j API::
+The logging API your code (programmatically) logs through.
+This needs to be available at compile-time and no configuration is needed.
+
+Log4j Core::
+The logging implementation which is responsible for filtering, routing, encoding, and appending log events.
+This needs to be available at runtime and configured by the user.
+
+[#logging]
+== How do I log using Log4j?
+
+Add the `log4j-api` dependency to your application:
+
+[tabs]
+====
+Maven::
++
+[source,xml,subs="+attributes"]
+----
+<project>
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-bom</artifactId>
+ <version>{log4j-core-version}</version>
+ <scope>import</scope>
+ <type>pom</type>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+
+ <dependency>
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-api</artifactId>
+ </dependency>
+ </dependency>
+
+</project>
+----
+
+Gradle::
++
+[source,groovy,subs="+attributes"]
+----
+dependencies {
+ implementation platform('org.apache.logging.log4j:log4j-bom:{log4j-core-version}')
+ implementation 'org.apache.logging.log4j:log4j-api'
+}
+----
+====
+
+And start logging:
+
+[source,java]
+----
+import org.apache.logging.log4j.Logger;
+import org.apache.logging.log4j.LogManager;
+
+public class DbTableService {
+
+ private static final Logger LOGGER = LogManager.getLogger(); // <1>
+
+ public void truncateTable(String tableName) throws IOException {
+ LOGGER.warn("truncating table `{}`", tableName); // <2>
+ db.truncate(tableName);
+ }
+
+}
+----
+<1> This is a thread-safe, reusable `Logger` instance.
+The associated class will be captured at initialization – no need for a `getLogger(DbTableService.class)`.
+<2> The generated **log event** will be automatically parameter formatted (note the parameter placeholder, i.e., `{}`) and enriched with **level** (i.e., `WARN`), timestamp, class & method name, line number, and several other information.
+
+Make sure to log exceptions that have diagnostics value:
+
+[source,java]
+----
+LOGGER.warn("truncating table `{}`", tableName);
+try {
+ db.truncate(tableName);
+} catch (IOException exception) {
+ LOGGER.error("failed truncating table `{}`", tableName, exception); // <1>
+ throw new IOException("failed truncating table: " + tableName, exception);
+}
+----
+<1> Notice the `error()` method?
+Yup, the level is set to `ERROR`.
++
+What about the `exception` in the last argument?
+Wait a second!
+There is one placeholder in the format (i.e., `{}`), but there are two parameters passed in arguments: `tableName` and `exception`!
+What the heck?
+Yep, you guessed it right!
+Log4j API will attach the last extra argument of type `Throwable` in a separate field to the generated log event.
+
+[#pitfalls]
+=== Common pitfalls
+
+There are several widespread bad practices.
+Let's try to walk through the most common ones.
+
+[#pitfal-toString]
+==== Don't use `toString()`
+
+[source,java]
+----
+// [✗] `Object#toString()` is redundant in arguments
+LOGGER.info("userId: {}", userId.toString());
+
+// [✓] Underlying message type and layout will deal with arguments
+LOGGER.info("userId: {}", userId);
+----
+
+[#pitfall-exception]
+==== Pass exception as the last extra argument
+
+Using `Throwable#printStackTrace()` or `Throwable#getMessage()` while logging?
+Please, don't!
+
+[source,java]
+----
+// [✗] Don't call `Throwable#printStackTrace()`.
+// This not only circumvents the logging, but can also leak sensitive information!
+exception.printStackTrace();
+
+// [✗] Don't use `Throwable#getMessage()`.
+// This prevents the log event from getting enriched with the exception.
+LOGGER.info("failed", exception.getMessage());
+LOGGER.info("failed for user ID `{}`: {}", userId, exception.getMessage());
+
+// [✗] This bloats the log message with duplicate exception message
+LOGGER.info("failed for user ID `{}`: {}", userId, exception.getMessage(), exception);
+
+// [✓] Pass exception as the last extra argument
+LOGGER.error("failed", exception);
+LOGGER.error("failed for user ID `{}`", userId, exception);
+----
+
+[#pitfal-concat]
+==== Don't use string concatenation
+
+If you are using `String` concatenation while logging, you are doing something very wrong and dangerous!
+
+[source,java]
+----
+// [✗] Circumvents the handling of arguments by message type and layout.
+// More importantly, this code is prone to attacks!
+// Imagine `userId` being provided by user with the following content:
+// `placeholders for non-existing args to trigger failure: {} {} {dangerousLookup}`
+LOGGER.info("failed for user ID: " + userId);
+
+// [✓] Use message parameters
+LOGGER.info("failed for user ID `{}`", userId);
+----
+
+[#config-app]
+== How do I configure Log4j to run my **application**?
+
+Your code logs through a logging API.
+So your dependencies and their dependencies too.
+While deploying your application, you need to provide a **logging implementation** along with its configuration to consume all generated log events.
+
+[IMPORTANT]
+====
+Are you implementing not an **application**, but a **library**?
+Please skip to the xref:#config-lib[] instead.
+====
+
+Add the `log4j-core` **runtime** dependency to your application:
+
+[tabs]
+====
+Maven::
++
+[source,xml,subs="+attributes"]
+----
+<project>
+
+ <!-- Assuming you already have the `dependencyManagement > dependencies > dependency` entry for `log4j-bom` -->
+
+ <dependency>
+
+ <!-- The logging implementation (i.e., Log4j Core) -->
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-core</artifactId>
+ <scope>runtime</scope><!--1-->
+ </dependency>
+
+ <!-- Log4j JSON-encoding support -->
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-layout-template-json</artifactId>
+ <scope>runtime</scope><!--1-->
+ </dependency>
+
+ <!-- SLF4J-to-Log4j bridge --><!--2-->
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-slf4j2-impl</artifactId>
+ <scope>runtime</scope><!--1-->
+ </dependency>
+
+ </dependency>
+
+</project>
+----
+
+Gradle::
++
+[source,groovy,subs="+attributes"]
+----
+dependencies {
+
+ // Assuming you already have the `implementation platform(...)` entry for `log4j-bom`
+
+ // The logging implementation (i.e., Log4j Core)
+ runtimeOnly 'org.apache.logging.log4j:log4j-core' // <1>
+
+ // Log4j JSON-encoding support
+ runtimeOnly 'org.apache.logging.log4j:log4j-layout-template-json' // <1>
+
+ // SLF4J-to-Log4j bridge // <2>
+ runtimeOnly 'org.apache.logging.log4j:log4j-slf4j2-impl' // <1>
+
+}
+----
+====
+<1> Note that the logging implementation and bridges are only needed at runtime!
+<2> SLF4J is another widely used logging API.
+`log4j-slf4j2-impl` forwards SLF4J calls to Log4j API, which effectively gets processed by Log4j Core too.
+
+Now it is time to configure Log4j and instruct how the log events should be routed.
+Save the following XML document to `src/**main**/resources/log4j2.xml`:
+
+.An example `src/**main**/resources/log4j2.xml`
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns="https://logging.apache.org/xml/ns"
+ xsi:schemaLocation="
+ https://logging.apache.org/xml/ns
+ https://logging.apache.org/xml/ns/log4j-config-2.xsd">
+
+ <appenders><!--1-->
+ <Console name="console"><!--2-->
+ <JsonTemplateLayout/><!--3-->
+ </Console>
+ </appenders>
+
+ <loggers>
+ <logger name="com.mycompany" level="INFO"/><!--4-->
+ <root level="WARN"><!--5-->
+ <AppenderRef ref="console"/><!--6-->
+ </root>
+ </loggers>
+
+</Configuration>
+----
+<1> xref:manual/appenders.adoc[Appenders] are responsible for writing log events to console, file, socket, database, etc.
+<2> xref:manual/appenders.adoc#ConsoleAppender[Console Appender] is used to write logs to the console.
+<3> xref:manual/json-template-layout.adoc[JSON Template Layout] is used to encode log events in JSON.
+<4> Log events generated by classes in the `com.mycompany` package (incl. its subpackages) and that are of level `INFO` and higher (i.e., `WARN`, `ERROR`, `FATAL`) will be consumed.
+<5> Unless specified otherwise, log events of level `WARN` and and higher will be consumed.
+<6> Unless specified otherwise, log events will be forwarded to the `console` appender defined earlier.
+
+You are strongly advised to use a different Log4j configuration for tests.
+Continue to xref:#config-test[]
+
+[#config-lib]
+== How do I configure Log4j for my **library**?
+
+Unlike applications, libraries should be logging implementation agnostic.
+That is, **libraries should log through a logging API, but leave the decision of the logging implementation to the application**.
+That said, libraries need a logging implementation while running their tests.
+
+[IMPORTANT]
+====
+Are you implementing not a **library**, but an **application**?
+Please skip to the xref:#config-app[] instead.
+====
+
+Add the `log4j-core` **test** dependency to your library:
+
+[tabs]
+====
+Maven::
++
+[source,xml,subs="+attributes"]
+----
+<project>
+
+ <!-- Assuming you already have the `dependencyManagement > dependencies > dependency` entry for `log4j-bom` -->
+
+ <dependency>
+
+ <!-- The logging implementation (i.e., Log4j Core) -->
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-core</artifactId>
+ <scope>test</scope><!--1-->
+ </dependency>
+
+ <!-- SLF4J-to-Log4j bridge --><!--2-->
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-slf4j2-impl</artifactId>
+ <scope>test</scope><!--1-->
+ </dependency>
+
+ </dependency>
+
+</project>
+----
+
+Gradle::
++
+[source,groovy,subs="+attributes"]
+----
+dependencies {
+
+ // Assuming you already have the `implementation platform(...)` entry for `log4j-bom`
+
+ // The logging implementation (i.e., Log4j Core)
+ testOnly 'org.apache.logging.log4j:log4j-core' // <1>
+
+ // SLF4J-to-Log4j bridge // <2>
+ testOnly 'org.apache.logging.log4j:log4j-slf4j2-impl' // <1>
+
+}
+----
+====
+<1> Note that the logging implementation and bridges are only needed for tests!
+<2> SLF4J is another widely used logging API.
+`log4j-slf4j2-impl` forwards SLF4J calls to Log4j API, which effectively gets processed by Log4j Core too.
+
+Next, you need a `src/**test**/resources/log4j2.xml`.
+See xref:#config-test[]
+
+[#config-test]
+== How do I configure Log4j for tests?
+
+For tests, prefer a human-readable layout with increased verbosity.
+Save the following XML document to `src/**test**/resources/log4j2.xml`:
+
+.An example `src/**test**/resources/log4j2.xml`
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns="https://logging.apache.org/xml/ns"
+ 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>
+ <logger name="com.mycompany" level="DEBUG"/><!--2-->
+ <root level="WARN">
+ <AppenderRef ref="console"/>
+ </root>
+ </loggers>
+
+</Configuration>
+----
+<1> xref:manual/layouts.adoc#PatternLayout[Pattern Layout] is used for a human-readable layout.
+<2> Increased logging verbosity for the `com.mycompany` package.
+
+[#next]
+== What is next?
+
+Installation::
+While shared dependency management snippets should get you going, it can also be challenging depending on your use case.
+Are you dealing with a Spring Boot application?
+Is it running in a Java EE container?
+Do you need to take into account other logging APIs such as JUL, JPL, JCL, etc.?
+See xref:manual/installation.adoc[] for the complete installation guide.
+
+Configuration::
+Log4j can be configured in several ways in various file formats (XML, JSON, Properties, and YAML).
+See the xref:manual/configuration.adoc[] page for details.
+
+Appenders & Layouts::
+Log4j contains several xref:manual/appenders.adoc[appenders] and xref:manual/layouts.adoc[layouts] to compose a configuration that best suit your needs.
+
+Performance::
+Do you want to get the best performance out of your logging system?
+Make sure to check out the xref:manual/performance.adoc[] page.
+
+Architecture::
+Want to learn more about loggers, contexts, and how these are all wired together?
+See the xref:manual/architecture.adoc[] page.
+
+Support::
+Confused?
+Having problem while setting up Log4j?
+See the {logging-services-url}/support.html[Support] page.
diff --git a/src/site/antora/modules/ROOT/pages/download.adoc b/src/site/antora/modules/ROOT/pages/download.adoc
index 0666d48ac9..27dbfa8442 100644
--- a/src/site/antora/modules/ROOT/pages/download.adoc
+++ b/src/site/antora/modules/ROOT/pages/download.adoc
@@ -21,3 +21,13 @@ You can manually download all published Log4j distributions, verify them, and se
* Are you looking for **the Log4j installation instructions**? Proceed to xref:manual/installation.adoc[].
* Are you looking for the list of changes associated with a particular release? Proceed to xref:release-notes.adoc[].
+
+[#older]
+== Older releases
+
+Are you looking for old versions of Log4j?
+While we recommend to always use the latest version, you can find the older versions here:
+
+* {logging-services-url}/1.x/[Log4j 1.x (End of Life, Java 1.4)]
+* {logging-services-url}/2.3.x/[Log4j 2.3.x (Java 6)]
+* {logging-services-url}/2.12.x/[Log4j 2.12.x (Java 7)]
diff --git a/src/site/antora/modules/ROOT/pages/index.adoc b/src/site/antora/modules/ROOT/pages/index.adoc
index 879c5ab4cc..2ccc92b10c 100644
--- a/src/site/antora/modules/ROOT/pages/index.adoc
+++ b/src/site/antora/modules/ROOT/pages/index.adoc
@@ -23,11 +23,12 @@ The project is actively maintained by a {logging-services-url}/team-list.html[te
[#shortcuts]
== Shortcuts
-- xref:manual/installation.adoc[How can I add Log4j artifacts to my Maven/Ivy/Gradle project?]
-- xref:manual/usage.adoc[How can I use the Log4j API?]
+
+- xref:5min.adoc[]
+- xref:manual/installation.adoc[How can I install Log4j? Which dependencies are needed?]
- xref:manual/configuration.adoc[How can I configure my `log4j2.xml`?]
- xref:release-notes.adoc[Where are the release notes?]
-- {logging-services-url}/support[**I need help!**]
+- {logging-services-url}/support.html[**I need help!**]
[#features]
== Features
@@ -60,26 +61,3 @@ Extensibility::
Log4j contains a fully-fledged xref:manual/plugins.adoc[plugin support] that users can leverage to extend its functionality.
You can easily add your own components (layouts, appenders, filters, etc.) or customizing existing ones (e.g., adding new directives to the xref:manual/layouts.adoc#PatternLayout[Pattern] or xref:manual/json-template-layout.adoc#extending[JSON Template Layout]).
Check out the xref:manual/extending.adoc[Extending Log4j] page.
-
-[#requirements]
-== Requirements
-
-Log4j 2 runtime requires a minimum of Java 8.
-Older versions of Java are supported by previous releases.
-
-[#older-releases]
-== Older releases
-
-Are you looking for old versions of Log4j?
-While we recommend to always use the latest version, you can find the older versions here:
-
-* {logging-services-url}/1.x/[Log4j 1.x (End of Life, Java 1.4)]
-* {logging-services-url}/2.3.x/[Log4j 2.3.x (Java 6)]
-* {logging-services-url}/2.12.x/[Log4j 2.12.x (Java 7)]
-
-[#compat]
-== Compatibility
-
-The `log4j-1.2-api` module provides compatibility for applications using the Log4j 1 logging methods.
-Log4j 2 also provides support for Log4j 1 configuration files.
-See xref:manual/migration.adoc#ConfigurationCompatibility[Log4j 2 compatibility with Log4j 1] for more information.
diff --git a/src/site/antora/modules/ROOT/pages/manual/installation.adoc b/src/site/antora/modules/ROOT/pages/manual/installation.adoc
index c2ac9f13c9..1e027bb745 100644
--- a/src/site/antora/modules/ROOT/pages/manual/installation.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/installation.adoc
@@ -391,6 +391,8 @@ Since version `1.3.0` https://commons.apache.org/proper/commons-logging/[Apache
You can enforce the version of a transitive dependency using the dependency management mechanism appropriate to your
build tool:
+[tabs]
+====
Maven::
Maven users should add an entry to the `<dependencyManagement>` section of their POM file:
+
@@ -408,6 +410,7 @@ Maven users should add an entry to the `<dependencyManagement>` section of their
Gradle::
+
Gradle users should refer to the https://docs.gradle.org/current/userguide/platforms.html#sub:using-platform-to-control-transitive-deps[Using a platform to control transitive versions] of the Gradle documentation.
+====
[#impl-core-bridge-jboss-logging]
===== Installing JBoss Logging-to-Log4j bridge
@@ -484,13 +487,15 @@ log4j2.xml::
<Configuration xmlns="https://logging.apache.org/xml/ns"
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-3.xsd">
+ https://logging.apache.org/xml/ns/log4j-config-2.xsd">
<appenders>
- <Console name="CONSOLE"/>
+ <Console name="CONSOLE">
+ <PatternLayout pattern="%d [%t] %5p %c{1.} - %m%n"/><!--1-->
+ </Console>
</appenders>
<loggers>
<root level="INFO">
- <AppenderRef ref="Console"/>
+ <AppenderRef ref="CONSOLE"/>
</root>
</Loggers>
</Configuration>
@@ -504,7 +509,10 @@ log4j2.json::
"Configuration": {
"Appenders": {
"Console": {
- "name": "CONSOLE"
+ "name": "CONSOLE",
+ "PatternLayout": {
+ "pattern": "%d [%t] %5p %c{1.} - %m%n" // <1>
+ }
}
},
"Loggers": {
@@ -527,6 +535,8 @@ Configuration:
Appenders:
Console:
name: CONSOLE
+ PatternLayout:
+ pattern: "%d [%t] %5p %c{1.} - %m%n" # <1>
Loggers:
Root:
level: INFO
@@ -540,11 +550,14 @@ log4j2.properties::
----
appender.0.type = Console
appender.0.name = CONSOLE
+appender.0.layout = PatternLayout # <1>
+appender.0.layout.pattern = %d [%t] %5p %c{1.} - %m%n
rootLogger.level = INFO
rootLogger.appenderRef.0.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.
In order to use these formats, the following additional dependencies are required: