Add documentation for ThrowableConsumingMessageFactory

Author: ppkarwasz

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[]
+    }
+}

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`.