This is an automated email from the ASF dual-hosted git repository. vy pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit d130aa1611f91a803ce24cb604dfcf3453ff3e12 Author: Volkan Yazıcı <[email protected]> AuthorDate: Thu May 30 12:55:48 2024 +0200 Add migrating from Logback/SLF4J pages (#2625) Co-authored-by: Piotr P. Karwasz <[email protected]> --- src/site/antora/modules/ROOT/nav.adoc | 16 +- src/site/antora/modules/ROOT/pages/index.adoc | 2 +- src/site/antora/modules/ROOT/pages/manual/api.adoc | 18 +- .../ROOT/pages/{ => manual}/getting-started.adoc | 342 +++++++++++---------- .../antora/modules/ROOT/pages/manual/index.adoc | 4 +- .../modules/ROOT/pages/manual/installation.adoc | 122 +------- .../modules/ROOT/pages/migrate-from-logback.adoc | 111 +++++++ .../modules/ROOT/pages/migrate-from-slf4j.adoc | 84 +++++ .../antora/modules/ROOT/partials/concepts.adoc | 133 ++++++++ .../modules/ROOT/partials/manual/api-intro.adoc | 40 ++- 10 files changed, 581 insertions(+), 291 deletions(-) diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc index f44851d5cc..0f893a52b9 100644 --- a/src/site/antora/modules/ROOT/nav.adoc +++ b/src/site/antora/modules/ROOT/nav.adoc @@ -21,14 +21,8 @@ ** link:{logging-services-url}/security.html[Security] ** xref:thanks.adoc[Thanks] -.Resources -* xref:faq.adoc[F.A.Q.] -* xref:getting-started.adoc[] -* xref:manual/migration.adoc[] -* xref:manual/cloud.adoc[] -* xref:development.adoc[] - .xref:manual/index.adoc[] +* xref:manual/getting-started.adoc[] * xref:manual/installation.adoc[] * xref:manual/architecture.adoc[] * xref:manual/api.adoc[API] @@ -53,6 +47,14 @@ * xref:plugin-reference.adoc[Plugin reference] * xref:javadoc.adoc[Java API reference] +.Resources +* xref:faq.adoc[F.A.Q.] +* xref:manual/migration.adoc[] +* xref:migrate-from-logback.adoc[] +* xref:migrate-from-slf4j.adoc[] +* xref:manual/cloud.adoc[] +* xref:development.adoc[] + .Components * xref:log4j-flume-ng.adoc[] * xref:log4j-iostreams.adoc[] diff --git a/src/site/antora/modules/ROOT/pages/index.adoc b/src/site/antora/modules/ROOT/pages/index.adoc index 128c273469..9f32cf9dfc 100644 --- a/src/site/antora/modules/ROOT/pages/index.adoc +++ b/src/site/antora/modules/ROOT/pages/index.adoc @@ -23,7 +23,7 @@ The project is actively maintained by a {logging-services-url}/team-list.html[te [#shortcuts] == Shortcuts -- xref:getting-started.adoc[] +- xref:manual/getting-started.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?] diff --git a/src/site/antora/modules/ROOT/pages/manual/api.adoc b/src/site/antora/modules/ROOT/pages/manual/api.adoc index 8adac0d449..edefd3412f 100644 --- a/src/site/antora/modules/ROOT/pages/manual/api.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/api.adoc @@ -15,13 +15,6 @@ limitations under the License. //// -:jboss-logging-link: https://github.com/jboss-logging/jboss-logging[JBoss Logging] -:jcl-link: https://commons.apache.org/proper/commons-logging/[JCL (Apache Commons Logging)] -:jpl-link: https://openjdk.org/jeps/264[JPL (Java Platform Logging)] -:jul-link: https://docs.oracle.com/en/java/javase/{java-target-version}/core/java-logging-overview.html[JUL (Java Logging)] -:logback-link: https://logback.qos.ch/[Logback] -:slf4j-link: https://www.slf4j.org/[SLF4J] - = Log4j API Log4j is essentially composed of a logging API called *Log4j API*, and its reference implementation called *Log4j Core*. @@ -29,20 +22,13 @@ Log4j is essentially composed of a logging API called *Log4j API*, and its refer .What is a logging API and a logging implementation? [%collapsible] ==== -Logging APIs:: -A logging API is an interface your code or your dependencies directly logs against. -It is implementation agnostic. -Log4j API, {slf4j-link}, {jul-link}, {jcl-link}, {jpl-link} and {jboss-logging-link} are major logging APIs. - -Logging implementation:: -A logging implementation is only required at runtime and can be changed without the need to recompile your software. -Log4j Core, {jul-link}, {logback-link} are the most well-known logging implementations. +include::partial$concepts.adoc[tags=inc;api;impl] ==== [TIP] ==== Are you looking for a crash course on how to use Log4j in your application or library? -See xref:getting-started.adoc[]. +See xref:manual/getting-started.adoc[]. You can also check out xref:manual/installation.adoc[] for the complete installation instructions. ==== diff --git a/src/site/antora/modules/ROOT/pages/getting-started.adoc b/src/site/antora/modules/ROOT/pages/manual/getting-started.adoc similarity index 53% rename from src/site/antora/modules/ROOT/pages/getting-started.adoc rename to src/site/antora/modules/ROOT/pages/manual/getting-started.adoc index e04a714033..8e858a27eb 100644 --- a/src/site/antora/modules/ROOT/pages/getting-started.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/getting-started.adoc @@ -23,7 +23,7 @@ It is not a comprehensive guide, but it should give you a good starting point. [#what] == What is logging? -Logging is the action of publishing diagnostics information at certain points of a program execution. +Logging is the act of publishing diagnostics information at certain points of a program execution. It means you can write messages to a log file or console to help you understand what your application is doing. The simplest way to log in Java is to use `System.out.println()`, like this: @@ -31,37 +31,35 @@ The simplest way to log in Java is to use `System.out.println()`, like this: [source, java] ---- private void truncateTable(String tableName) { - System.out.println("Truncating table"); <1> + System.out.println("truncating table"); <1> db.truncate(tableName); } ---- <1> The information that a table is being truncated is written to the console. This is already useful, but the reader of this message does not know what table is being truncated. -Usually, we would like to include the table name in the message, which quickly leads -developers to use the `System.out.format` (or similar) methods. +Usually, we would like to include the table name in the message, which quickly leads developers to use `System.out.format()` or similar methods. Log4j helps with formatting strings as we will see later, but for now, let's see how to work without it. -The following code shows how this method could be used to provide more context information. -`%s` will be replaced with the value of `tableName`, and `%n` will be replaced with a new line. +The following code shows how this method can be improved to provide more context about its action. [source, java] ---- private void truncateTable(String tableName) { - System.out.format("[WARN] Truncating table `%s`%n", tableName); <1> + System.out.format("[WARN] truncating table `%s`%n", tableName); <1> db.truncate(tableName); } ---- -<1> `format` writes the message to the console, replacing `%s` with the value of `tableName`. +<1> `format()` writes the message to the console, replacing `%s` with the value of `tableName`, and `%n` with a new line. -If the developer decides the truncate the table "fruits", the output of this code will look like this: +If the developer decides the truncate the table `fruits`, the output of this code will look like this: -[source] +[source,text] ---- [WARN] Truncating table `fruits` ---- -This provides observability into an application's runtime and we can follow the execution flow. +This provides observability into an application's runtime, and we can follow the execution flow. However, there are several drawbacks with the above approach and this is where Log4j comes in. Log4j will help you to write logs in a more structured way, with more information, and with more flexibility. @@ -72,18 +70,27 @@ Log4j will help you to write logs in a more structured way, with more informatio Log4j is a versatile, industrial-grade Java logging framework, maintained by many contributors. It can help us with common logging tasks and lets us focus on the application logic. -It will: +It helps with: -* Enhance the message with additional information (timestamp, class & method name, line number, host, severity, etc.) -* Write the message differently, 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.) +* Enhancing the message with additional information (timestamp, file, class, and method name, line number, host, severity, etc.) +* Formatting the message according to a given **layout** (CSV, JSON, etc.) +* Writing the message to various targets using an **appender** (console, file, socket, database, queue, etc.) +* **Filter**ing messages to be written (e.g. filter by severity, content, etc.) -[#install] -== Prerequisites +[#architecture] +== What is Log4j composed of? + +Log4j is essentially composed of a logging API called *Log4j API*, and its reference implementation called *Log4j Core*. +Log4j also bundles several logging bridges to enable Log4j Core consume from foreign logging APIs. +Let's briefly explain these concepts: + +include::partial$concepts.adoc[tags=inc;api;impl;bridge] + +[#prerequisites] +== What are the installation prerequisites? -We will need a **BOM** (Bill of Materials) to manage the versions of the dependencies. -In addition, we will need the `log4j-api` dependency itself. +We will need a BOM (Bill of Materials) to manage the versions of the dependencies. +This way we won't need to provide the version for each Log4j module explicitly. [tabs] ==== @@ -105,13 +112,6 @@ Maven:: </dependencies> </dependencyManagement> - <dependency> - <dependency> - <groupId>org.apache.logging.log4j</groupId> - <artifactId>log4j-api</artifactId> - </dependency> - </dependency> - </project> ---- @@ -121,13 +121,12 @@ Gradle:: ---- dependencies { implementation platform('org.apache.logging.log4j:log4j-bom:{log4j-core-version}') - implementation 'org.apache.logging.log4j:log4j-api' } ---- ==== -[#logging] -== How do I write logs using Log4j? +[#using-api] +== How do I log using Log4j API? include::partial$manual/api-intro.adoc[] @@ -153,48 +152,20 @@ include::partial$manual/api-best-practice-exception-as-last-argument.adoc[] include::partial$manual/api-best-practice-dont-use-string-concat.adoc[] -[#architecture] -== Architecture - -In a nutshell, Log4j operates with two main parts: the API and the Core. -With this structure, Log4j allows you to log events using the API and route them through the Core. - -Optionally you can also route the log events through other logging frameworks -like SLF4J or JUL (Java Util Logging) by adding a bridge. - -[#log4j-api] -Log4j API:: -This is the interface that you use in your application to log events. -It needs to be available at compile-time and no configuration is needed. -By using it, you ensure that your application can write logs but is not tied to a specific logging implementation. +[#install-app] +== How do I install Log4j Core to run my **application**? -[#log4j-core] -Log4j Core:: -The Log4j Core is a logging implementation that processes log events. -It is responsible for filtering, routing, encoding, and appending log events. -This needs to be available at runtime and requires configuration by the user. -When you deploy your application, you must also deploy the Log4j Core or any -other logging implementation along with its configuration to consume all generated log events - -The following sections show you examples of how you can get started quickly with Log4j. - -[#config-app] -== How do I configure Log4j to run my **application**? - -The following section describes, how an application can be configured to use Log4j. -It will add a configuration and some other artifacts to your application. -The configuration shown here enhances the security and usability of your application. +This section explains how to install Log4j Core to run an application. [IMPORTANT] ==== Are you implementing not an **application**, but a **library**? -Please skip to the xref:#config-lib[] instead. +Please refer to the xref:#install-lib[] instead. ==== -As mentioned, Log4j is using a logging API. -First of all, add the `log4j-core` **runtime** dependency to our application. +First, add the `log4j-core` **runtime** dependency to your application. Second, it is highly recommended to add the `log4j-layout-template-json` **runtime** dependency to encode log events in JSON. -This is the most secure way to format log events and should preferred over the default `PatternLayout`, at least for production deployments. +This is the most secure way to format log events and should be preferred over the default `PatternLayout`, at least for production deployments. [tabs] ==== @@ -203,7 +174,8 @@ Maven:: [source,xml,subs="+attributes"] ---- <project> - <!-- Assuming `log4j-bom` is already added --> + + <!-- Assuming `log4j-bom` is added --> <dependency> @@ -220,6 +192,7 @@ Maven:: <artifactId>log4j-layout-template-json</artifactId> <scope>runtime</scope><!--1--> </dependency> + </dependency> </project> @@ -231,7 +204,7 @@ Gradle:: ---- dependencies { - // Assuming `log4j-bom` is already added + // Assuming `log4j-bom` is added // The logging implementation (i.e., Log4j Core) runtimeOnly 'org.apache.logging.log4j:log4j-core' // <1> @@ -241,19 +214,70 @@ dependencies { } ---- ==== -<1> Note that the logging implementation and bridges are only needed at runtime. +<1> For applications, the logging implementation need to be runtime dependencies. + +If your application has (direct or transitive!) dependencies that use another logging API, you need to xref:#logging-bridge[bridge] that to Log4j. +This way the foreign logging API calls will effectively be consumed by Log4j too. +{slf4j-link} is another logging API used pretty common in the wild. +(xref:manual/installation.adoc[] covers all supported foreign APIs.) +Let's see how you can use the `log4j-slf4j2-impl` bridge to support SLF4J: + +[tabs] +==== +Maven:: ++ +[source,xml,subs="+attributes"] +---- +<project> + + <!-- Assuming `log4j-bom` is added --> + + <dependency> + + <!-- Assuming `log4j-core` and `log4j-layout-template-json` is added --> + + <!-- 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 `log4j-bom`, `log4j-core`, and `log4j-layout-template-json` is added + + // SLF4J-to-Log4j bridge // <2> + runtimeOnly 'org.apache.logging.log4j:log4j-slf4j2-impl' // <1> + +} +---- +==== +<1> For applications, bridges need to be runtime dependencies. +<2> Log4j module bridging SLF4J to Log4j -Now it is time to configure Log4j and instruct how the log events should be routed. +To complete the installation, Log4j needs to be configured. +Please continue with xref:#config-app[] -The xref:manual/json-template-layout.adoc[JSON Template Layout] is used to encode log events in JSON. -Once encoded xref:manual/appenders.adoc[Appenders] are responsible for writing log events to the console, file, socket, database, etc. +[#config-app] +== How do I configure Log4j Core to run my application? -The `<logger>` defines, that log events generated by classes in the `com.mycompany` package (incl. its sub-packages) and that are of level `INFO` and higher (i.e., `WARN`, `ERROR`, `FATAL`) will be consumed. -Finally, the `<root>` logger defines that log events of level `WARN` and higher will be consumed unless specified otherwise. It serves as a default configuration. +This section explains configuring Log4j on how log events should be processed. -Save the following XML document to `src/**main**/resources/log4j2.xml`. +xref:manual/configuration.adoc[Log4j supports several configuration inputs and file formats.] +Let's start with a basic and robust configuration where the logs are encoded in JSON and written to the console. +Save the following XML-formatted Log4j **configuration file** to `src/**main**/resources/**log4j2.xml**` in your application. -.An example `src/**main**/resources/log4j2.xml` +.An example `src/**main**/resources/**log4j2.xml**` [source,xml] ---- <?xml version="1.0" encoding="UTF-8"?> @@ -263,39 +287,50 @@ Save the following XML document to `src/**main**/resources/log4j2.xml`. https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-config-3.xsd";> - <appenders><!--1--> + <Appenders><!--1--> <Console name="CONSOLE"><!--2--> <JsonTemplateLayout/><!--3--> </Console> - </appenders> + </Appenders> - <loggers> - <logger name="com.mycompany" level="INFO"/><!--4--> - <root level="WARN"><!--5--> + <Loggers> + <Logger name="com.mycompany" level="INFO"/><!--4--> + <Root level="WARN"><!--5--> <AppenderRef ref="CONSOLE"/><!--6--> - </root> - </loggers> + </Root> + </Loggers> </Configuration> ---- -<1> xref:manual/appenders.adoc[Appenders] are responsible for writing log events to their target +<1> xref:manual/appenders.adoc[Appenders] are responsible for writing log events to a particular target; console, file, socket, database, queue, etc. <2> xref:manual/appenders.adoc#ConsoleAppender[Console Appender] writes logs to the console. -<3> xref:manual/json-template-layout.adoc[JSON Template Layout] encodes log events in JSON. -<4> Log events from `com.mycompany` and its sub-packages, at `INFO` level or higher, are consumed. -<5> Unless specified otherwise, log events of level `WARN` and higher will be consumed. -<6> Unless specified otherwise, log events will be forwarded to the `console` appender defined earlier. +<3> xref:manual/layouts.adoc[Layouts] are responsible for encoding log events before appenders writing them. +xref:manual/json-template-layout.adoc[JSON Template Layout] encodes log events in JSON. +<4> Log events generated by classes in the `com.mycompany` package (incl. its sub-packages) and that are of level `INFO` or higher (i.e., `WARN`, `ERROR`, `FATAL`) will be accepted. +<5> Unless specified otherwise, log events of level `WARN` and higher will be accepted. +It serves as the default `<logger>` configuration. +<6> Unless specified otherwise, accepted log events will be forwarded to the `console` appender defined earlier. + +Next, you need to you need to configure Log4j for the tests of your application. +Please proceed to xref:#config-test[] + +[#install-lib] +== How do I install Log4j Core for my **library**? -If you want to configure Log4j for tests, you are strongly advised to use a different Log4j configuration. -Continue to xref:#config-test[] +This section explains how to install Log4j Core for libraries. -[#integrating-log4j] -== Integrating Log4j with SLF4J +[IMPORTANT] +==== +Are you implementing not a **library**, but an **application**? +Please refer to xref:#install-app[] instead. +==== -In many cases, you might have a library that logs through SLF4J. -Due to the separation of Log4js API and Core, you can add a bridge to forward SLF4J calls to the Log4j API. -This way, SLF4J calls will be processed by Log4j Core too. +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. -It is similarly easy: just add the new dependency `log4j-slf4j2-impl to your application. +Let's see how you can install Log4j Core for your tests. +Start with adding the `log4j-core` dependency in **test** scope to your library: [tabs] ==== @@ -304,14 +339,16 @@ Maven:: [source,xml,subs="+attributes"] ---- <project> - <!-- Other dependencies --> + + <!-- Assuming `log4j-bom` is added --> <dependency> - <!-- SLF4J-to-Log4j bridge --><!--2--> + + <!-- Logging implementation (Log4j Core) --> <dependency> - <groupId>org.apache.logging.log4j</groupId> - <artifactId>log4j-slf4j2-impl</artifactId> - <scope>runtime</scope><!--1--> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-core</artifactId> + <scope>test</scope><!--1--> </dependency> </dependency> @@ -324,35 +361,22 @@ Gradle:: [source,groovy,subs="+attributes"] ---- dependencies { - // Other dependencies - // SLF4J-to-Log4j bridge // <2> - runtimeOnly 'org.apache.logging.log4j:log4j-slf4j2-impl' // <1> + // Assuming `log4j-bom` is already added + + // The logging implementation (i.e., Log4j Core) + testRuntimeOnly 'org.apache.logging.log4j:log4j-core' // <1> } ---- ==== -<1> Again, we only need a runtime dependency. -<2> This dependency will forward SLF4J calls to the Log4j API. - -`log4j-slf4j2-impl` forwards SLF4J calls to Log4j API, which effectively gets processed by Log4j Core too. - -[#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. -==== +<1> For tests of libraries, the logging implementation is only needed in test scope. -Add the `log4j-core` dependency in **test** scope to your library. -Very similar to the previous section, in most cases it is useful to also add the `log4j-slf4j2-impl` dependency. -SLF4J is a widely used logging API and this way, SLF4J calls will be processed by Log4j Core too. +If your library has (direct or transitive!) dependencies that use another logging API, you need to xref:#logging-bridge[bridge] that to Log4j. +This way the foreign logging API calls will effectively be consumed by Log4j too. +{slf4j-link} is another logging API used pretty common in the wild. +(xref:manual/installation.adoc[] covers all supported foreign APIs.) +Let's see how you can use the `log4j-slf4j2-impl` bridge to support SLF4J: [tabs] ==== @@ -361,16 +385,12 @@ Maven:: [source,xml,subs="+attributes"] ---- <project> - <!-- Assuming `log4j-bom` is already added --> + + <!-- Assuming `log4j-bom` is added --> <dependency> - <!-- The logging implementation (i.e., Log4j Core) --> - <dependency> - <groupId>org.apache.logging.log4j</groupId> - <artifactId>log4j-core</artifactId> - <scope>test</scope><!--1--> - </dependency> + <!-- Assuming `log4j-core` and `log4j-layout-template-json` is added --> <!-- SLF4J-to-Log4j bridge --><!--2--> <dependency> @@ -390,38 +410,40 @@ Gradle:: ---- dependencies { - // Assuming `log4j-bom` is already added - - // The logging implementation (i.e., Log4j Core) - testRuntimeOnly 'org.apache.logging.log4j:log4j-core' // <1> + // Assuming `log4j-bom`, `log4j-core`, and `log4j-layout-template-json` is added // SLF4J-to-Log4j bridge // <2> - testRuntimeOnly 'org.apache.logging.log4j:log4j-slf4j2-impl' // <1> + runtimeOnly 'org.apache.logging.log4j:log4j-slf4j2-impl' // <1> } ---- ==== -<1> Note that the logging implementation and bridges are only needed for tests. -<2> `log4j-slf4j2-impl` forwards SLF4J calls to the Log4j API. +<1> For tests of libraries, logging bridges are only needed in test scope. +<2> Log4j module bridging SLF4J to Log4j -Next, you need a `src/**test**/resources/log4j2-test.xml`. -See xref:#config-test[] +Next, you need to you need to configure Log4j. +Please proceed to xref:#config-test[] [#config-test] -== How do I configure Log4j for tests? +== How do I configure Log4j Core for tests? + +This section explains configuring Log4j on how log events should be processed for tests. + +xref:manual/configuration.adoc[Log4j supports several configuration inputs and file formats.] +Let's start with a basic and developer-friendly configuration where the logs are pretty-printed in a human-readable way and written to the console. -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. +Contrast to xref:#config-app[an application's more conservative Log4j setup], for tests, we will go with a more developer-friendly Log4j configuration where -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 -which level and the `<root>` logger serves as a default configuration. +. the logs are pretty-printed to the console, and +. logging verbosity is increased. -Save the following XML document to `src/**test**/resources/log4j2-test.xml`. +While it is not recommended to use xref:manual/layouts.adoc#pattern-layout[Pattern Layout] in production for security reasons, it is a good choice for tests to encode log events. +We will use it to pretty-print the log event to the console with extra fields: timestamp, thread name, log level, class name, etc. +The rest of the configuration should look familiar from earlier sections. -.An example `src/**test**/resources/log4j2-test.xml` +Save the following XML-formatted Log4j configuration file to `src/**test**/resources/**log4j2-test.xml**`. + +.An example `src/**test**/resources/**log4j2-test.xml**` [source,xml] ---- <?xml version="1.0" encoding="UTF-8"?> @@ -431,29 +453,33 @@ Save the following XML document to `src/**test**/resources/log4j2-test.xml`. https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-config-3.xsd";> - <appenders> + <Appenders> <Console name="CONSOLE"> <PatternLayout pattern="%d [%t] %5p %c{1.} - %m%n"/><!--1--> </Console> - </appenders> + </Appenders> - <loggers> - <logger name="com.mycompany" level="DEBUG"/><!--2--> - <root level="WARN"> + <Loggers> + <Logger name="com.mycompany" level="DEBUG"/><!--2--> + <Root level="WARN"> <AppenderRef ref="CONSOLE"/> - </root> - </loggers> + </Root> + </Loggers> </Configuration> ---- -<1> xref:manual/layouts.adoc#pattern-layout[Pattern Layout] is used for a human-readable layout. +<1> xref:manual/layouts.adoc#pattern-layout[Pattern Layout] is used for encoding the log event in a human-readable way. <2> Increased logging verbosity for the `com.mycompany` package. [#next] == What is next? -More details:: -If you are looking for a more detailed read, please see {logging-services-url}/what-is-logging.html[What is logging?]. +At this stage, you know + +. How to install Log4j API and log using it +. How to install and configure Log4j Core in your application/library + +You can use following pointers to further customize your Log4j setup. Installation:: While shared dependency management snippets should get you going, your case might necessitate a more intricate setup. diff --git a/src/site/antora/modules/ROOT/pages/manual/index.adoc b/src/site/antora/modules/ROOT/pages/manual/index.adoc index 490c4f968c..07d1199783 100644 --- a/src/site/antora/modules/ROOT/pages/manual/index.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/index.adoc @@ -16,8 +16,6 @@ //// = Manual -== Welcome to Apache Log4j! - 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. The project is actively maintained by a {logging-services-url}/team-list.html[team] of volunteers and {logging-services-url}/support[support]ed by a big community. @@ -38,6 +36,7 @@ Log4j is an excellent choice for any Java application that needs logging capabil It is user-friendly, fast, and flexible. You can use it to log messages at different levels of severity, from debug to fatal, and you can configure it to log messages to various destinations, such as files, databases, or the console. +See xref:manual/getting-started.adoc[] for an introduction. == When not to use Log4j? @@ -58,6 +57,7 @@ include::partial$log4j-features.adoc[] == How to learn more? +* xref:manual/getting-started.adoc[How can I get started with Log4j?] * xref:manual/installation.adoc[How can I install Log4j?] * xref:manual/configuration.adoc[How can I configure Log4j?] * xref:manual/api.adoc[How can I use Log4j API?] diff --git a/src/site/antora/modules/ROOT/pages/manual/installation.adoc b/src/site/antora/modules/ROOT/pages/manual/installation.adoc index bc538a066a..96d2d28342 100644 --- a/src/site/antora/modules/ROOT/pages/manual/installation.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/installation.adoc @@ -15,19 +15,16 @@ limitations under the License. //// -:jcl-link: https://commons.apache.org/proper/commons-logging/[JCL (Apache Commons Logging)] :jpl-link: https://openjdk.org/jeps/264[JPL (Java Platform Logging)] :jul-link: https://docs.oracle.com/en/java/javase/{java-target-version}/core/java-logging-overview.html[JUL (Java Logging)] -:logback-link: https://logback.qos.ch/[Logback] :slf4j-link: https://www.slf4j.org/[SLF4J] -:jboss-logging-link: https://github.com/jboss-logging/jboss-logging[JBoss Logging] = Installation In this page we will elaborate on various ways to install Log4j in your library or application. -[#impatient] -== For the impatient +[#shortcuts] +== Shortcuts Below we share some shortcuts for the impatient. @@ -52,92 +49,7 @@ See <<impl-core-spring-boot>>. It is crucial to understand certain concepts in logging to be able to talk about the installation of them. -[#logging-api] -Logging API:: -A logging API is an interface your code or your dependencies directly logs against. -It is implementation agnostic. -Log4j API, {slf4j-link}, {jul-link}, {jcl-link}, {jpl-link} and {jboss-logging-link} are major logging APIs. - -[#logging-impl] -Logging implementation:: -A logging implementation is only required at runtime and can be changed without the need to recompile your software. -Log4j Core, {jul-link}, {logback-link} are the most well-known logging implementations. -+ -[TIP] -==== -Note that JUL and Log4j provide both an API and its implementation. -In the case of Log4j, the API is called _Log4j API_, and its reference implementation is called _Log4j Core_. -==== - -[#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 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:: -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:: -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 | | | -| | | | | | -| | +-------+ | | -| | | | -| +-------------------------------------------------------------------------------+ | -| | -\-----------------------------------------------------------------------------------/ -.... +include::partial$concepts.adoc[] [#requirements] == Requirements @@ -157,7 +69,7 @@ The rest of the instructions in this page assume you use one of these. To keep your Log4j module versions in sync with each other, a BOM (Bill of Material) file is provided for your convenience. You can import the BOM in your build tool of preference: -[tabs] +[tabs,opts=sync] ==== Maven:: + @@ -204,7 +116,7 @@ You can access the latest development snapshots by using the `https://repository Snapshots are published for development and testing purposes; **they should not be used at production!** ===== -[tabs] +[tabs,opts=sync] ===== Maven:: + @@ -239,7 +151,7 @@ repositories { The easiest way to install Log4j API is through a dependency management tool such as Maven or Gradle, by adding the following dependency: -[tabs] +[tabs,opts=sync] ==== Maven:: + @@ -314,7 +226,7 @@ You can directly skip to xref:#impl-core-spring-boot[]. To install Log4j Core as your logging implementation, you need to add the following dependency to your application: -[tabs] +[tabs,opts=sync] ==== Maven:: + @@ -365,7 +277,7 @@ The following sections explain the installation of Log4j-provided bridges. You can translate {slf4j-link} calls to Log4j API using the `log4j-slf4j2-impl` artifact: -[tabs] +[tabs,opts=sync] ==== Maven:: + @@ -392,7 +304,7 @@ runtimeOnly 'org.apache.logging.log4j:log4j-slf4j2-impl' // SLF4J-to-Log4j bridg You can translate {jul-link} calls to Log4j API using the `log4j-jul` artifact: -[tabs] +[tabs,opts=sync] ==== Maven:: + @@ -428,7 +340,7 @@ to the JVM parameters in your application launcher. You can translate {jpl-link} calls to Log4j API using the `log4j-jpl` artifact: -[tabs] +[tabs,opts=sync] ==== Maven:: + @@ -458,7 +370,7 @@ 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] +[tabs,opts=sync] ==== Maven:: Maven users should add an entry to the `<dependencyManagement>` section of their POM file: @@ -482,15 +394,15 @@ Gradle users should refer to the https://docs.gradle.org/current/userguide/platf [#impl-core-bridge-jboss-logging] ===== Installing JBoss Logging-to-Log4j bridge -The JBoss Logging API is shipped with an integrated bridge to Log4j API and requires no steps on your part. See -https://github.com/jboss-logging/jboss-logging?tab=readme-ov-file#supported-log-managers[Supported Log Managers] for more information. +The JBoss Logging API is shipped with an integrated bridge to Log4j API and requires no steps on your part. +See https://github.com/jboss-logging/jboss-logging?tab=readme-ov-file#supported-log-managers[Supported Log Managers] for more information. [#impl-core-spring-boot] ==== Installing Log4j Core for Spring Boot applications Spring Boot users should replace the `spring-boot-starter-logging` dependency with `spring-boot-starter-log4j2`: -[tabs] +[tabs,opts=sync] ==== Maven:: @@ -546,7 +458,7 @@ Log4j Core supports many different configuration formats: JSON, XML, YAML, and J To configure Log4j Core, see xref:manual/configuration.adoc[]. A basic configuration can be obtained by adding one of these files to your application's classpath: -[tabs] +[tabs,opts=sync] ==== log4j2.xml:: @@ -647,7 +559,7 @@ You can skip this section and use the https://github.com/jboss-logging/log4j2-jb Java Platform contains a very simple logging API and its implementation called {jul-link}. Since it is embedded in the platform, it only requires the addition of bridges from Log4j API and SLF4J: -[tabs] +[tabs,opts=sync] ==== Maven:: @@ -693,7 +605,7 @@ To configure JUL, see https://docs.oracle.com/en/java/javase/{java-target-versio To install https://logback.qos.ch/[Logback] as the logging implementation, you only need to add a Log4j-to-SLF4J bridge: -[tabs] +[tabs,opts=sync] ==== Maven:: diff --git a/src/site/antora/modules/ROOT/pages/migrate-from-logback.adoc b/src/site/antora/modules/ROOT/pages/migrate-from-logback.adoc new file mode 100644 index 0000000000..a9662347d9 --- /dev/null +++ b/src/site/antora/modules/ROOT/pages/migrate-from-logback.adoc @@ -0,0 +1,111 @@ +//// +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. +//// + +:logback-link: https://logback.qos.ch/[Logback] +:slf4j-link: https://www.slf4j.org/[SLF4J] + += Migrating from Logback + +{logback-link} is a logging implementation for the {slf4j-link} logging API, just like Log4j Core is a logging implementation for the xref:manual/api.adoc[Log4j API]. +In this page we will guide you through migrating from Logback to Log4j Core as your logging implementation. + +[TIP] +==== +Instead of migrating your logging implementation, Logback, are you looking for migrating your logging API, SLF4J? +Please refer to xref:migrate-from-slf4j.adoc[]. +==== + +.Struggling with the logging API, implementation, and bridge concepts? Click for an introduction. +[%collapsible] +==== +include::partial$concepts.adoc[tag=!software-type] +==== + +[#migrating] +== Migrating + +You either have an application using Logback at runtime, or have a library using Logback for tests. +In either case, you can replace Logback with Log4j Core as follows: + +. Remove `ch.qos.logback:logback-classic` dependency + +. Remove `logback.xml` and `logback-test.xml` files + +. Follow the instructions shared in the _"Getting started"_ page +** xref:manual/getting-started.adoc#install-app[for applications] +** xref:manual/getting-started.adoc#install-lib[for libraries] + +Next you need to re-organize your logging API bridges such that all foreign APIs are bridged to Log4j API, the logging API implemented by Log4j Core. +This is explained in the next section. + +[#bridges] +=== Bridges + +It is highly likely that you were bridging all logging APIs (including Log4j API!) to SLF4J, the logging API implemented by Logback. +There are two particular approaches you can take here to ensure all logging APIs are instead bridged to Log4j API, the logging API implemented by Log4j Core: + +[#bridge-to-log4j] +==== Bridge all logging APIs to Log4j API + +We strongly advise you to bridge all foreign logging APIs *directly* to Log4j API. +You can use the cheat sheet shared below to implement that. + +.Dependency migration cheat sheet +[cols="1,1"] +|=== +| If dependency present | replace with + +| `org.apache.logging.log4j:log4j-to-slf4j` +| `org.apache.logging.log4j:log4j-slf4j2-impl` + +| `org.slf4j:jcl-over-slf4j` +| `commons-logging:commons-logging` version `>=1.3.0` + +| `org.slf4j:jul-to-slf4j` +| `org.apache.logging.log4j:log4j-jul` + +| `org.slf4j:log4j-over-slf4j` +| `org.apache.logging.log4j:log4j-1.2-api` + +| `org.springframework:spring-boot-starter-logging` +| `org.springframework:spring-boot-starter-log4j2` +|=== + +[#bridge-to-sfl4j] +==== Bridge all logging APIs to SLF4J, and bridge SLF4J to Log4j API + +You can implement this by replacing `org.apache.logging.log4j:log4j-to-slf4j` dependency with `org.apache.logging.log4j:log4j-slf4j2-impl`. + +[WARNING] +==== +*This approach is not recommended!* +It incurs certain drawbacks since some logging API calls will need to cross multiple bridges. +For instance, a call to JUL will first be bridged to SLF4J, and then from there to Log4j API. +==== + +[#config] +=== Configuration + +It might not always be trivial to match the contents of the newly created `log4j2.xml` and `log4j2-test.xml` files with your old `logback.xml` and `logback-test.xml` files. +While all Logback components have corresponding equivalents in Log4j Core, they might not be sharing the same name or configuration. +To assist with migrating Logback configuration components to Log4j Core, see the following pages: + +* xref:manual/appenders.adoc[] +* xref:manual/layouts.adoc[] +* xref:manual/filters.adoc[] + +For the complete list of all Log4j configuration knobs, see xref:manual/configuration.adoc[the Configuration page]. diff --git a/src/site/antora/modules/ROOT/pages/migrate-from-slf4j.adoc b/src/site/antora/modules/ROOT/pages/migrate-from-slf4j.adoc new file mode 100644 index 0000000000..ab0f9e0572 --- /dev/null +++ b/src/site/antora/modules/ROOT/pages/migrate-from-slf4j.adoc @@ -0,0 +1,84 @@ +//// +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. +//// + +:logback-link: https://logback.qos.ch/[Logback] +:slf4j-link: https://www.slf4j.org/[SLF4J] +:slf4j-javadoc-url: https://www.slf4j.org/api + += Migrating from SLF4J + +{slf4j-link} is a logging API whose reference implementation is {logback-link}, just like xref:manual/api.adoc[Log4j API] is a logging API whose reference implementation is Log4j Core. +In this page we will guide you through migrating from SLF4J to Log4j API as your logging API. + +[TIP] +==== +Instead of migrating your logging API, SLF4J, are you looking for migrating your logging implementation, Logback? +Please refer to xref:migrate-from-logback.adoc[]. +==== + +.Struggling with the logging API, implementation, and bridge concepts? Click for an introduction. +[%collapsible] +==== +include::partial$concepts.adoc[tag=!software-type] +==== + +[#migrating] +== Migrating + +If your application or library logs using SLF4J, you can migrate it to Log4j API as follows: + +. Remove `org.slf4j:slf4j-api` dependency + +. Follow the instructions shared in the _"Getting started"_ page for xref:manual/getting-started.adoc#using-api[installing `log4j-api` and using it] + +. Search for `org.slf4j` usages in your project and replace them with Log4j API equivalents ++ +[IMPORTANT] +==== +For an exhaustive list of code changes that need to be carried out, refer to https://docs.openrewrite.org/recipes/java/logging/log4j/slf4jtolog4j[the SLF4J to Log4j API migration OpenRewrite recipe]. +This you can use to + +. either manually follow the described migrations, +. or run OpenRewrite to automatically migrate the code. +==== ++ +{slf4j-javadoc-url}/org/slf4j/LoggerFactory.html[`org.slf4j.LoggerFactory`]:: +Replace its usages with link:javadoc/log4j-api/org/apache/logging/log4j/LogManager.html[`org.apache.logging.log4j.LogManager`]. +Note that `LogManager.getLogger(Foo.class)` can be simplified as `LogManager.getLogger()`, if `Foo` is the enclosing class of the field. ++ +{slf4j-javadoc-url}/org/slf4j/Logger.html[`org.slf4j.Logger`]:: +Replace its usages with link:javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`org.apache.logging.log4j.Logger`]. +Since SLF4J's `Logger` is almost a parent of Log4j's `Logger`, most methods should work without any changes. ++ +{slf4j-javadoc-url}/org/slf4j/MDC.html[`org.slf4j.MDC`]:: +Replace its usages with link:javadoc/log4j-api/org/apache/logging/log4j/ThreadContext.html[`org.apache.logging.log4j.ThreadContext`]. + +. If you use https://projectlombok.org/features/log[`@Slf4j` from Lombok], you need to replace them with `@Log4j2` instead. + +At this stage, you should have your application or library logging using Log4j API. + +If it is a library that you migrated,:: +then you don't need to take any extra steps. +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. + +If it is an application that you migrated, and you are not using Log4j Core as your logging implementation,:: +then you can consider doing so. +Certain xref:manual/api.adoc[Log4j API features] (e.g., xref:manual/garbagefree.adoc[garbage-free logging]) require an end-to-end setup which is mostly possible using Log4j API in combination with Log4j Core. ++ +See xref:manual/installation.adoc[] for installing Log4j Core. + +If you are using Logback, refer to xref:migrate-from-logback.adoc[]. diff --git a/src/site/antora/modules/ROOT/partials/concepts.adoc b/src/site/antora/modules/ROOT/partials/concepts.adoc new file mode 100644 index 0000000000..883b2e5f21 --- /dev/null +++ b/src/site/antora/modules/ROOT/partials/concepts.adoc @@ -0,0 +1,133 @@ +//// + 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. +//// + +//// + Don't use block markers (i.e., `====`) in this page! + It is breaking the formatting elsewhere, e.g., `api.adoc`. +//// + +// tag::inc[] + +:jcl-link: https://commons.apache.org/proper/commons-logging/[JCL (Apache Commons Logging)] +:jpl-link: https://openjdk.org/jeps/264[JPL (Java Platform Logging)] +:jul-link: https://docs.oracle.com/en/java/javase/{java-target-version}/core/java-logging-overview.html[JUL (Java Logging)] +:logback-link: https://logback.qos.ch/[Logback] +:slf4j-link: https://www.slf4j.org/[SLF4J] +:jboss-logging-link: https://github.com/jboss-logging/jboss-logging[JBoss Logging] + +// end::inc[] + +// tag::api[] + +[#logging-api] +Logging API:: +A logging API is an interface your code or your dependencies directly logs against. +It is required at compile-time. +It is implementation agnostic to ensure that your application can write logs, but is not tied to a specific logging implementation. +Log4j API, {slf4j-link}, {jul-link}, {jcl-link}, {jpl-link} and {jboss-logging-link} are major logging APIs. + +// end::api[] + +// tag::impl[] + +[#logging-impl] +Logging implementation:: +A logging implementation is only required at runtime and can be changed without the need to recompile your software. +Log4j Core, {jul-link}, {logback-link} are the most well-known logging implementations. + +// end::impl[] + +// tag::bridge[] + +[#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 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. + +// end::bridge[] + +// tag::software-type[] + +With this in mind, the type of software you are writing determines whether you should be installing a logging API, implementation, or bridge: + +Libraries:: +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:: +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 example, 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`. + +// end::software-type[] + +// tag::visual[] + +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 | | | +| | | | | | +| | +-------+ | | +| | | | +| +-------------------------------------------------------------------------------+ | +| | +\-----------------------------------------------------------------------------------/ +.... + +// end::visual[] diff --git a/src/site/antora/modules/ROOT/partials/manual/api-intro.adoc b/src/site/antora/modules/ROOT/partials/manual/api-intro.adoc index 79262e0fcd..25beb43d0e 100644 --- a/src/site/antora/modules/ROOT/partials/manual/api-intro.adoc +++ b/src/site/antora/modules/ROOT/partials/manual/api-intro.adoc @@ -15,8 +15,44 @@ limitations under the License. //// -To write logs, you need a {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`] instance which you will retrieve from the {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/LogManager.html[`LogManager`]. -You can use the `Logger` instance to write logs by using methods like `info()`, `warn()`, `error()`, etc. +To log, you need a {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`] instance which you will retrieve from the {log4j2-url}/javadoc/log4j-api/org/apache/logging/log4j/LogManager.html[`LogManager`]. +These are all part of the `log4j-api` module, which you can install as follows: + +[tabs] +==== +Maven:: ++ +[source,xml] +---- +<project> + + <!-- Assuming `log4j-bom` is added --> + + <dependencies> + <dependency> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-api</artifactId> + </dependency> + </dependencies> + +</project> +---- + +Gradle:: ++ +[source,groovy] +---- +dependencies { + + // Assuming `log4j-bom` is added + + implementation 'org.apache.logging.log4j:log4j-api' + +} +---- +==== + +You can use the `Logger` instance to log by using methods like `info()`, `warn()`, `error()`, etc. These methods are named after the _log levels_ they represent, a way to categorize log events by severity. The log message can also contain placeholders written as `{}` that will be replaced by the arguments passed to the method.
