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 9bf606d96eb323deba26d3960aba15aa3716a370 Author: Piotr P. Karwasz <[email protected]> AuthorDate: Tue Jul 2 13:14:43 2024 +0200 Add documentation for `ThrowableConsumingMessageFactory` --- .../migrate-from-logback/MigrateFromLogback.java | 28 ++++++++++ .../modules/ROOT/pages/migrate-from-logback.adoc | 59 ++++++++++++++++++++++ 2 files changed, 87 insertions(+) diff --git a/src/site/antora/modules/ROOT/examples/migrate-from-logback/MigrateFromLogback.java b/src/site/antora/modules/ROOT/examples/migrate-from-logback/MigrateFromLogback.java new file mode 100644 index 0000000000..295133b005 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/migrate-from-logback/MigrateFromLogback.java @@ -0,0 +1,28 @@ +package example; + +import org.apache.logging.log4j.LogManager; +import org.apache.logging.log4j.Logger; + +class MigrateFromLogback { + private static Logger logger = LogManager.getLogger(); + + doLogWrong() { + try { + // do something + // tag::wrong[] + } catch (Exception e) { + logger.error("The foo process exited with an error: {}", e); + } + // end::wrong[] + } + + doLogRight() { + try { + // do something + // tag::right[] + } catch (Exception e) { + logger.error("The foo process exited with an error.", e); + } + // end::right[] + } +} \ No newline at end of file diff --git a/src/site/antora/modules/ROOT/pages/migrate-from-logback.adoc b/src/site/antora/modules/ROOT/pages/migrate-from-logback.adoc index 9d2ac5cd24..79e8c9a1a8 100644 --- a/src/site/antora/modules/ROOT/pages/migrate-from-logback.adoc +++ b/src/site/antora/modules/ROOT/pages/migrate-from-logback.adoc @@ -106,3 +106,62 @@ To assist with migrating Logback configuration components to Log4j Core, see the * xref:manual/filters.adoc[] For the complete list of all Log4j configuration knobs, see xref:manual/configuration.adoc[the Configuration page]. + +[#parameterized-logging] +=== Parameterized logging + +A common mistake in parameterized logging is to add a `{}` placeholder for the exception associated with a log event: + +[source,java,indent=0] +---- +include::example$migrate-from-logback/MigrateFromLogback.java[tag=wrong] +---- + +Log4j Core and Logback differ in the way they treat this statement: + +Logback:: +Logback interprets the `e` argument as throwable and removes it from the list of parameters. +We end up with a parameterized statement with one placeholder, but zero parameters. +The placeholder therefore remains as is: ++ +[source] +---- +The foo process exited with and error: {} +java.lang.RuntimeException: Message + at example.MigrateFromLogback.doLogWrong(MigrateFromLogback.java:10) +... +---- + +Log4j Core:: +Log4j Core first looks for the parameters of the message. +Since the format string has one placeholder, the `e` argument is interpreted as a parameter of the log message. +The throwable associated to the log event is `null`, which results in a missing stack trace: ++ +[source] +---- +The foo process exited with and error: java.lang.RuntimeException: Message +---- + +To fix this problem and obtain the same output in both backends, you should remove the placeholder from the format string: + +[source,java,indent=0] +---- +include::example$migrate-from-logback/MigrateFromLogback.java[tag=right] +---- + +After the change, the output will look us: + +[source] +---- +The foo process exited with and error. +java.lang.RuntimeException: Message + at example.MigrateFromLogback.doLogWrong(MigrateFromLogback.java:10) +... +---- + +[TIP] +==== +As a temporary solution, the SLF4J-to-Log4j API bridges contain a special +xref:manual/api.adoc#logger-message-factories[`MessageFactory`] +that classifies trailing `Throwable` arguments in the same way Logback does. +To use it, you need to set the xref:manual/systemproperties.adoc#log4j2.messageFactory[`log4j2.messageFactory`] configuration property to `org.apache.logging.slf4j.message.ThrowableConsumingMessageFactory`. \ No newline at end of file
