diff --git a/antora-playbook.yaml b/antora-playbook.yaml index 2c9ebdd5057..4c8abbdaf20 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: @@ -88,10 +91,10 @@ ui: .doc pre { font-size: 0.7rem; } .doc .colist { font-size: 0.75rem; } /* Tab header fonts aren't rendered good, adjusting the font weight: */ - .tablist > ul li { font-weight: 500; } + .tablist > ul li { font-weight: 500; } /* `page-toclevels` greater than 4 are not supported by Antora UI, patching it: */ .toc .toc-menu li[data-level="4"] a { - padding-left: 2.75rem + padding-left: 2.75rem; } /* Replace the default highlight.js color for strings from red (unnecessarily signaling something negative) to green: */ .hljs-string { diff --git a/log4j-parent/pom.xml b/log4j-parent/pom.xml index bf115d758ed..3243c41b63f 100644 --- a/log4j-parent/pom.xml +++ b/log4j-parent/pom.xml @@ -98,14 +98,14 @@ 2.0b6 1.17.0 1.26.1 - 1.10.0 + 1.11.0 2.12.0 2.16.1 3.14.0 1.3.1 1.2.21 4.0.0 - 7.17.20 + 7.17.21 0.9.0 7.0.5 4.8.1 @@ -113,7 +113,7 @@ 1.11.0 24.0.1 4.0.21 - 33.1.0-jre + 33.2.0-jre 2.2.222 1.2.1 2.2 diff --git a/package.json b/package.json index 8de82aed5be..df223e24ef1 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/changelog/.3.x.x/update_com_google_guava_guava.xml b/src/changelog/.3.x.x/update_com_google_guava_guava.xml index 21766583c78..66569c07fcd 100644 --- a/src/changelog/.3.x.x/update_com_google_guava_guava.xml +++ b/src/changelog/.3.x.x/update_com_google_guava_guava.xml @@ -3,6 +3,6 @@ xmlns="https://logging.apache.org/xml/ns" xsi:schemaLocation="https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-changelog-0.xsd" type="updated"> - - Update `com.google.guava:guava` to version `33.1.0-jre` + + Update `com.google.guava:guava` to version `33.2.0-jre` diff --git a/src/changelog/.3.x.x/update_org_apache_commons_commons_csv.xml b/src/changelog/.3.x.x/update_org_apache_commons_commons_csv.xml new file mode 100644 index 00000000000..b71cbc11abb --- /dev/null +++ b/src/changelog/.3.x.x/update_org_apache_commons_commons_csv.xml @@ -0,0 +1,8 @@ + + + + Update `org.apache.commons:commons-csv` to version `1.11.0` + diff --git a/src/changelog/.3.x.x/update_org_elasticsearch_client_elasticsearch_rest_high_level_client.xml b/src/changelog/.3.x.x/update_org_elasticsearch_client_elasticsearch_rest_high_level_client.xml index 40c2cc7dced..0254e7e13dc 100644 --- a/src/changelog/.3.x.x/update_org_elasticsearch_client_elasticsearch_rest_high_level_client.xml +++ b/src/changelog/.3.x.x/update_org_elasticsearch_client_elasticsearch_rest_high_level_client.xml @@ -3,6 +3,6 @@ xmlns="https://logging.apache.org/xml/ns" xsi:schemaLocation="https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-changelog-0.xsd" type="updated"> - - Update `org.elasticsearch.client:elasticsearch-rest-high-level-client` to version `7.17.20` + + Update `org.elasticsearch.client:elasticsearch-rest-high-level-client` to version `7.17.21` diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc index efb53b3a014..ec81d8cc052 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.html[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 00000000000..ad3f761ef7c --- /dev/null +++ b/src/site/antora/modules/ROOT/pages/5min.adoc @@ -0,0 +1,476 @@ +//// + 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 message with additional information (timestamp, class & method name, line number, host, severity, etc.) +* Write the message in a different way, using a different **layout** (CSV, JSON, etc.) +* Write the message to a different medium, using a different **appender** (file, socket, database, queue, etc.) +* Write only some of the messages, using a **filter** (e.g. filter by severity, content, etc.) + +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"] +---- + + + + + + org.apache.logging.log4j + log4j-bom + {log4j-core-version} + import + pom + + + + + + + org.apache.logging.log4j + log4j-api + + + + +---- + +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 parameter placeholders `{}` in the message will be automatically replaced with the value of `tableName` and the generated **log event** will be 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()` + +* [ ] `Object#toString()` is redundant in arguments ++ +[source,java] +---- +/* BAD! */ LOGGER.info("userId: {}", userId.toString()); +---- + +* [x] Underlying message type and layout will deal with arguments ++ +[source,java] +---- +/* GOOD */ LOGGER.info("userId: {}", userId); +---- + +[#pitfall-exception] +==== Pass exception as the last extra argument + +Using `Throwable#printStackTrace()` or `Throwable#getMessage()` while logging? +Please, don't! + +* [ ] Don't call `Throwable#printStackTrace()`. +This not only circumvents the logging, but can also leak sensitive information! ++ +[source,java] +---- +/* BAD! */ exception.printStackTrace(); +---- + +* [ ] Don't use `Throwable#getMessage()`. +This prevents the log event from getting enriched with the exception. ++ +[source,java] +---- +/* BAD! */ LOGGER.info("failed", exception.getMessage()); +/* BAD! */ LOGGER.info("failed for user ID `{}`: {}", userId, exception.getMessage()); +---- + +* [ ] This bloats the log message with duplicate exception message ++ +[source,java] +---- +/* BAD! */ LOGGER.info("failed for user ID `{}`: {}", userId, exception.getMessage(), exception); +---- + +* [x] Pass exception as the last extra argument ++ +[source,java] +---- +/* GOOD */ LOGGER.error("failed", exception); +/* GOOD */ 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! + +* [ ] 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}` ++ +[source,java] +---- +/* BAD! */ LOGGER.info("failed for user ID: " + userId); +---- + +* [x] Use message parameters ++ +[source,java] +---- +/* GOOD */ 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"] +---- + + + + + + + + + org.apache.logging.log4j + log4j-core + runtime + + + + + org.apache.logging.log4j + log4j-layout-template-json + runtime + + + + + org.apache.logging.log4j + log4j-slf4j2-impl + runtime + + + + + +---- + +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] +---- + + + + + + + + + + + + + + + + + +---- +<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"] +---- + + + + + + + + + org.apache.logging.log4j + log4j-core + test + + + + + org.apache.logging.log4j + log4j-slf4j2-impl + test + + + + + +---- + +Gradle:: ++ +[source,groovy,subs="+attributes"] +---- +dependencies { + + // Assuming you already have the `implementation platform(...)` entry for `log4j-bom` + + // The logging implementation (i.e., Log4j Core) + testRuntimeOnly 'org.apache.logging.log4j:log4j-core' // <1> + + // SLF4J-to-Log4j bridge // <2> + testRuntimeOnly '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-test.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-test.xml`: + +.An example `src/**test**/resources/log4j2-test.xml` +[source,xml] +---- + + + + + + + + + + + + + + + + + +---- +<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 0666d48ac91..ccd7b08b3e1 100644 --- a/src/site/antora/modules/ROOT/pages/download.adoc +++ b/src/site/antora/modules/ROOT/pages/download.adoc @@ -21,3 +21,14 @@ 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)] +* {logging-services-url}/2.x/[Log4j 2.x (Java 8)] diff --git a/src/site/antora/modules/ROOT/pages/index.adoc b/src/site/antora/modules/ROOT/pages/index.adoc index 996d2a2f9a5..5c92b57d439 100644 --- a/src/site/antora/modules/ROOT/pages/index.adoc +++ b/src/site/antora/modules/ROOT/pages/index.adoc @@ -19,38 +19,16 @@ Apache Log4j is a versatile, industrial-grade Java logging framework composed of an API, its implementation, and components to assist the deployment for various use cases. Log4j is https://security.googleblog.com/2021/12/apache-log4j-vulnerability.html[used by 8% of the Maven ecosystem] and listed as one of https://docs.google.com/spreadsheets/d/1ONZ4qeMq8xmeCHX03lIgIYE4MEXVfVL6oj05lbuXTDM/edit#gid=1024997528[the top 100 critical open source software projects]. -The project is actively maintained by a {logging-services-url}/team-list.html[team] of several volunteers and xref:support.adoc[support]ed by a big community. +The project is actively maintained by a {logging-services-url}/team-list.html[team] of several volunteers and {logging-services-url}/support.html[support]ed by a big community. [#shortcuts] == Shortcuts -- xref:download.adoc#using-a-build-system[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?] -- xref:support.adoc[**I need help!**] - -[#simple-to-use] -== Simple to use - -Apache Log4j is easy to use. The example below shows you how to create a Logger instance, that -you can use to log messages to the console. As soon as you can understand this little bit of code, you can start using -Log4j in your applications. - -[source,java] ----- -import java.util.logging.LogManager; -import java.util.logging.Logger; - -class Application { - private static final Logger LOGGER = LogManager.getLogger(); <1> - - public void action() { - LOGGER.info("Hello, World!"); <2> - } -} ----- -<1> Get a Logger instance -<2> Log a message on info level +- {logging-services-url}/support.html[**I need help!**] [#features] == Features @@ -84,28 +62,8 @@ Log4j contains a fully-fledged xref:manual/plugins.adoc[plugin support] that use 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 3 runtime requires a minimum of Java 17. -For support for older versions of Java see the {logging-services-url}/log4j/2.x[Log4j 2 site]. - -[#older-releases] -== Older releases - -Are looking for old versions of Log4j? While we recommend ot always use the latest versions, you can find the older versions here: - -* {logging-services-url}/1.2/[Log4j 1.2 (End of Life)] -* {logging-services-url}/log4j-2.3/[Log4j 2.3 (Java 6)] -* {logging-services-url}/log4j-2.12.1/[Log4j 2.12.1 (Java 7)] -* {logging-services-url}/2.x/[Log4j 2 (Java 8)] - [#compat] == Compatibility Application code written using the Log4j 2 API should be binary compatible with Log4j 3. Custom plugins written for Log4j 2 may need minor changes when compiling with Log4j 3 as some package names have changed. - -The `log4j-1.2-api` module provides compatibility for applications using the Log4j 1 logging methods. -Log4j 3, just like Log4j 2, also provides experimental support for Log4j 1 configuration files. -See xref:manual/log4j1-compat.adoc[Log4j 3 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 6c544b67870..45242d866f3 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 <>.) +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 3 runtime requires a minimum of Java {java-target-version}. -See {logging-services-url}/log4j/2.x[the Log4j 2 website] for the latest releases supporting Java 6, 7, and 8. +See xref:download.adoc#older[the Download page] for older releases supporting Java 6, 7, and 8. [#build-tool] == Configuring the build tool @@ -195,8 +246,8 @@ Maven:: [source,xml] ---- - org.apache.logging.log4j - log4j-api + org.apache.logging.log4j + log4j-api ---- @@ -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 <> for the installation instructions. `log4j-to-jul`:: @@ -269,12 +321,16 @@ Maven:: [source,xml] ---- - - org.apache.logging.log4j - log4j-core - runtime - - + + + + org.apache.logging.log4j + log4j-core + runtime + + + + ---- @@ -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:: ---- - org.apache.logging.log4j - log4j-slf4j2-impl - runtime + org.apache.logging.log4j + log4j-slf4j2-impl + runtime ---- @@ -333,9 +400,9 @@ Maven:: ---- - org.apache.logging.log4j - log4j-jul - runtime + org.apache.logging.log4j + log4j-jul + runtime ---- @@ -369,9 +436,9 @@ Maven:: ---- - org.apache.logging.log4j - log4j-jpl - runtime + org.apache.logging.log4j + log4j-jpl + runtime ---- @@ -391,23 +458,26 @@ 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 `` section of their POM file: + [source,xml,subs="+attributes"] ---- - - commons-logging - commons-logging - {commons-logging-version} - + + commons-logging + commons-logging + {commons-logging-version} + ---- 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 @@ -428,21 +498,24 @@ Maven:: [source,xml] ---- - - org.springframework.boot - spring-boot-starter - - - org.springframework.boot - spring-boot-starter-logging - - - - + + + org.springframework.boot + spring-boot-starter + + org.springframework.boot - spring-boot-starter-log4j2 - runtime - + spring-boot-starter-logging + + + + + + org.springframework.boot + spring-boot-starter-log4j2 + runtime + + ---- @@ -451,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' } ---- @@ -485,14 +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-3.xsd"> + - + + + + - + - + + ---- @@ -504,7 +582,10 @@ log4j2.json:: "Configuration": { "Appenders": { "Console": { - "name": "CONSOLE" + "name": "CONSOLE", + "PatternLayout": { + "pattern": "%d [%t] %5p %c{1.} - %m%n" // <1> + } } }, "Loggers": { @@ -527,6 +608,8 @@ Configuration: Appenders: Console: name: CONSOLE + PatternLayout: + pattern: "%d [%t] %5p %c{1.} - %m%n" # <1> Loggers: Root: level: INFO @@ -538,12 +621,16 @@ log4j2.properties:: + [source,properties] ---- -Configuration.Appenders.Console.name = CONSOLE -Configuration.Loggers.Root.level = INFO -Configuration.Loggers.Root.AppenderRef.ref = CONSOLE +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: @@ -653,20 +740,24 @@ Maven:: [source,xml,subs="+attributes"] ---- + - - org.apache.logging.log4j - log4j-to-jul - runtime - - - - org.slf4j - slf4j-jdk14 - {slf4j-version} - runtime - - + + org.apache.logging.log4j + log4j-to-jul + runtime + + + + + org.slf4j + slf4j-jdk14 + {slf4j-version} + runtime + + + + ---- @@ -695,18 +786,22 @@ Maven:: [source,xml] ---- - - ch.qos.logback - logback-classic - {logback-version} - runtime - - - - org.apache.logging.log4j - log4j-to-slf4j - runtime - + + + + ch.qos.logback + logback-classic + {logback-version} + runtime + + + + + org.apache.logging.log4j + log4j-to-slf4j + runtime + + ----