Add Logback's throwable-consuming semantics as an option

log4j-slf4j-impl/src/main/java/org/apache/logging/slf4j/message/ThrowableConsumingMessageFactory.java

@@ -0,0 +1,187 @@
+/*
+ * 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.
+ */
+package org.apache.logging.slf4j.message;
+
+import java.util.Arrays;
+import org.apache.logging.log4j.message.Message;
+import org.apache.logging.log4j.message.MessageFactory2;
+import org.apache.logging.log4j.message.ObjectMessage;
+import org.apache.logging.log4j.message.ParameterizedMessage;
+import org.apache.logging.log4j.message.SimpleMessage;
+
+/**
+ * A message factory that eagerly removes a trailing throwable argument.
+ * <p>
+ *     This factory implements the algorithm used by Logback 1.1.x or later to determine
+ *     {@link Message#getThrowable()}: if the last argument is a {@link Throwable} and there are less arguments than
+ *     the number of placeholders incremented by one, the last argument will be used as
+ *     {@link Message#getThrowable()} and will <strong>not</strong> appear in the parameterized message.
+ * </p>
+ * <p>
+ *     The usual Log4j semantic only looks for throwables once <strong>all</strong> the placeholders have been filled.
+ * </p>
+ * @since 2.24.0
+ */
+public final class ThrowableConsumingMessageFactory implements MessageFactory2 {
+
+    private Message newParameterizedMessage(final Object throwable, final String pattern, final Object... args) {
+        return new ParameterizedMessage(pattern, args, (Throwable) throwable);
+    }
+
+    @Override
+    public Message newMessage(final Object message) {
+        return new ObjectMessage(message);
+    }
+
+    @Override
+    public Message newMessage(final String message) {
+        return new SimpleMessage(message);
+    }
+
+    @Override
+    public Message newMessage(final String message, final Object... params) {
+        if (params != null && params.length > 0) {
+            final Object lastArg = params[params.length - 1];
+            return lastArg instanceof Throwable
+                    ? newParameterizedMessage(lastArg, message, Arrays.copyOf(params, params.length - 1))
+                    : newParameterizedMessage(null, message, params);
+        }
+        return new SimpleMessage(message);
+    }
+
+    @Override
+    public Message newMessage(final CharSequence charSequence) {
+        return new SimpleMessage(charSequence);
+    }
+
+    @Override
+    public Message newMessage(final String message, final Object p0) {
+        return p0 instanceof Throwable
+                ? newParameterizedMessage(p0, message)
+                : newParameterizedMessage(null, message, p0);
+    }
+
+    @Override
+    public Message newMessage(final String message, final Object p0, final Object p1) {
+        return p1 instanceof Throwable
+                ? newParameterizedMessage(p1, message, p0)
+                : newParameterizedMessage(null, message, p0, p1);
+    }
+
+    @Override
+    public Message newMessage(final String message, final Object p0, final Object p1, final Object p2) {
+        return p2 instanceof Throwable
+                ? newParameterizedMessage(p2, message, p0, p1)
+                : newParameterizedMessage(null, message, p0, p1, p2);
+    }
+
+    @Override
+    public Message newMessage(
+            final String message, final Object p0, final Object p1, final Object p2, final Object p3) {
+        return p3 instanceof Throwable
+                ? newParameterizedMessage(p3, message, p0, p1, p2)
+                : newParameterizedMessage(null, message, p0, p1, p2, p3);
+    }
+
+    @Override
+    public Message newMessage(
+            final String message, final Object p0, final Object p1, final Object p2, final Object p3, final Object p4) {
+        return p4 instanceof Throwable
+                ? newParameterizedMessage(p4, message, p0, p1, p2, p3)
+                : newParameterizedMessage(null, message, p0, p1, p2, p3, p4);
+    }
+
+    @Override
+    public Message newMessage(
+            final String message,
+            final Object p0,
+            final Object p1,
+            final Object p2,
+            final Object p3,
+            final Object p4,
+            final Object p5) {
+        return p5 instanceof Throwable
+                ? newParameterizedMessage(p5, message, p0, p1, p2, p3, p4)
+                : newParameterizedMessage(null, message, p0, p1, p2, p3, p4, p5);
+    }
+
+    @Override
+    public Message newMessage(
+            final String message,
+            final Object p0,
+            final Object p1,
+            final Object p2,
+            final Object p3,
+            final Object p4,
+            final Object p5,
+            final Object p6) {
+        return p6 instanceof Throwable
+                ? newParameterizedMessage(p6, message, p0, p1, p2, p3, p4, p5)
+                : newParameterizedMessage(null, message, p0, p1, p2, p3, p4, p5, p6);
+    }
+
+    @Override
+    public Message newMessage(
+            final String message,
+            final Object p0,
+            final Object p1,
+            final Object p2,
+            final Object p3,
+            final Object p4,
+            final Object p5,
+            final Object p6,
+            final Object p7) {
+        return p7 instanceof Throwable
+                ? newParameterizedMessage(p7, message, p0, p1, p2, p3, p4, p5, p6)
+                : newParameterizedMessage(null, message, p0, p1, p2, p3, p4, p5, p6, p7);
+    }
+
+    @Override
+    public Message newMessage(
+            final String message,
+            final Object p0,
+            final Object p1,
+            final Object p2,
+            final Object p3,
+            final Object p4,
+            final Object p5,
+            final Object p6,
+            final Object p7,
+            final Object p8) {
+        return p8 instanceof Throwable
+                ? newParameterizedMessage(p8, message, p0, p1, p2, p3, p4, p5, p6, p7)
+                : newParameterizedMessage(null, message, p0, p1, p2, p3, p4, p5, p6, p7, p8);
+    }
+
+    @Override
+    public Message newMessage(
+            final String message,
+            final Object p0,
+            final Object p1,
+            final Object p2,
+            final Object p3,
+            final Object p4,
+            final Object p5,
+            final Object p6,
+            final Object p7,
+            final Object p8,
+            final Object p9) {
+        return p9 instanceof Throwable
+                ? newParameterizedMessage(p9, message, p0, p1, p2, p3, p4, p5, p6, p7, p8)
+                : newParameterizedMessage(null, message, p0, p1, p2, p3, p4, p5, p6, p7, p8, p9);
+    }
+}

log4j-slf4j-impl/src/main/java/org/apache/logging/slf4j/message/package-info.java

@@ -0,0 +1,22 @@
+/*
+ * 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.
+ */
+@Export
+@Version("2.24.0")
+package org.apache.logging.slf4j.message;
+
+import org.osgi.annotation.bundle.Export;
+import org.osgi.annotation.versioning.Version;

log4j-slf4j-impl/src/test/java/org/apache/logging/slf4j/message/ThrowableConsumingMessageFactoryTest.java

@@ -0,0 +1,138 @@
+/*
+ * 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.
+ */
+package org.apache.logging.slf4j.message;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.apache.logging.log4j.message.Message;
+import org.apache.logging.log4j.message.MessageFactory2;
+import org.junit.jupiter.api.Test;
+
+public class ThrowableConsumingMessageFactoryTest {
+
+    private static final String MESSAGE = "MESSAGE";
+    private static final Object P0 = new Object();
+    private static final Object P1 = new Object();
+    private static final Object P2 = new Object();
+    private static final Object P3 = new Object();
+    private static final Object P4 = new Object();
+    private static final Object P5 = new Object();
+    private static final Object P6 = new Object();
+    private static final Object P7 = new Object();
+    private static final Object P8 = new Object();
+    private static final Object P9 = new Object();
+    private static final Object P10 = new Object();
+    private static final Object THROWABLE = new Throwable();
+
+    @Test
+    void should_not_consume_last_object_parameter() {
+        final MessageFactory2 factory = new ThrowableConsumingMessageFactory();
+        assertThat(factory.newMessage(MESSAGE, P0))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(1, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(2, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(3, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(4, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(5, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(6, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(7, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6, P7))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(8, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6, P7, P8))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(9, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6, P7, P8, P9))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(10, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6, P7, P8, P9, P10))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(11, null);
+    }
+
+    @Test
+    void should_consume_last_throwable_parameter() {
+        final MessageFactory2 factory = new ThrowableConsumingMessageFactory();
+        assertThat(factory.newMessage(MESSAGE, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(0, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(1, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(2, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(3, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(4, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(5, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(6, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(7, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6, P7, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(8, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6, P7, P8, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(9, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6, P7, P8, P9, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(10, THROWABLE);
+    }
+}

log4j-slf4j2-impl/src/main/java/org/apache/logging/slf4j/message/ThrowableConsumingMessageFactory.java

@@ -0,0 +1,187 @@
+/*
+ * 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.
+ */
+package org.apache.logging.slf4j.message;
+
+import java.util.Arrays;
+import org.apache.logging.log4j.message.Message;
+import org.apache.logging.log4j.message.MessageFactory2;
+import org.apache.logging.log4j.message.ObjectMessage;
+import org.apache.logging.log4j.message.ParameterizedMessage;
+import org.apache.logging.log4j.message.SimpleMessage;
+
+/**
+ * A message factory that eagerly removes a trailing throwable argument.
+ * <p>
+ *     This factory implements the algorithm used by Logback 1.1.x or later to determine
+ *     {@link Message#getThrowable()}: if the last argument is a {@link Throwable} and there are less arguments than
+ *     the number of placeholders incremented by one, the last argument will be used as
+ *     {@link Message#getThrowable()} and will <strong>not</strong> appear in the parameterized message.
+ * </p>
+ * <p>
+ *     The usual Log4j semantic only looks for throwables once <strong>all</strong> the placeholders have been filled.
+ * </p>
+ * @since 2.24.0
+ */
+public final class ThrowableConsumingMessageFactory implements MessageFactory2 {
+
+    private Message newParameterizedMessage(final Object throwable, final String pattern, final Object... args) {
+        return new ParameterizedMessage(pattern, args, (Throwable) throwable);
+    }
+
+    @Override
+    public Message newMessage(final Object message) {
+        return new ObjectMessage(message);
+    }
+
+    @Override
+    public Message newMessage(final String message) {
+        return new SimpleMessage(message);
+    }
+
+    @Override
+    public Message newMessage(final String message, final Object... params) {
+        if (params != null && params.length > 0) {
+            final Object lastArg = params[params.length - 1];
+            return lastArg instanceof Throwable
+                    ? newParameterizedMessage(lastArg, message, Arrays.copyOf(params, params.length - 1))
+                    : newParameterizedMessage(null, message, params);
+        }
+        return new SimpleMessage(message);
+    }
+
+    @Override
+    public Message newMessage(final CharSequence charSequence) {
+        return new SimpleMessage(charSequence);
+    }
+
+    @Override
+    public Message newMessage(final String message, final Object p0) {
+        return p0 instanceof Throwable
+                ? newParameterizedMessage(p0, message)
+                : newParameterizedMessage(null, message, p0);
+    }
+
+    @Override
+    public Message newMessage(final String message, final Object p0, final Object p1) {
+        return p1 instanceof Throwable
+                ? newParameterizedMessage(p1, message, p0)
+                : newParameterizedMessage(null, message, p0, p1);
+    }
+
+    @Override
+    public Message newMessage(final String message, final Object p0, final Object p1, final Object p2) {
+        return p2 instanceof Throwable
+                ? newParameterizedMessage(p2, message, p0, p1)
+                : newParameterizedMessage(null, message, p0, p1, p2);
+    }
+
+    @Override
+    public Message newMessage(
+            final String message, final Object p0, final Object p1, final Object p2, final Object p3) {
+        return p3 instanceof Throwable
+                ? newParameterizedMessage(p3, message, p0, p1, p2)
+                : newParameterizedMessage(null, message, p0, p1, p2, p3);
+    }
+
+    @Override
+    public Message newMessage(
+            final String message, final Object p0, final Object p1, final Object p2, final Object p3, final Object p4) {
+        return p4 instanceof Throwable
+                ? newParameterizedMessage(p4, message, p0, p1, p2, p3)
+                : newParameterizedMessage(null, message, p0, p1, p2, p3, p4);
+    }
+
+    @Override
+    public Message newMessage(
+            final String message,
+            final Object p0,
+            final Object p1,
+            final Object p2,
+            final Object p3,
+            final Object p4,
+            final Object p5) {
+        return p5 instanceof Throwable
+                ? newParameterizedMessage(p5, message, p0, p1, p2, p3, p4)
+                : newParameterizedMessage(null, message, p0, p1, p2, p3, p4, p5);
+    }
+
+    @Override
+    public Message newMessage(
+            final String message,
+            final Object p0,
+            final Object p1,
+            final Object p2,
+            final Object p3,
+            final Object p4,
+            final Object p5,
+            final Object p6) {
+        return p6 instanceof Throwable
+                ? newParameterizedMessage(p6, message, p0, p1, p2, p3, p4, p5)
+                : newParameterizedMessage(null, message, p0, p1, p2, p3, p4, p5, p6);
+    }
+
+    @Override
+    public Message newMessage(
+            final String message,
+            final Object p0,
+            final Object p1,
+            final Object p2,
+            final Object p3,
+            final Object p4,
+            final Object p5,
+            final Object p6,
+            final Object p7) {
+        return p7 instanceof Throwable
+                ? newParameterizedMessage(p7, message, p0, p1, p2, p3, p4, p5, p6)
+                : newParameterizedMessage(null, message, p0, p1, p2, p3, p4, p5, p6, p7);
+    }
+
+    @Override
+    public Message newMessage(
+            final String message,
+            final Object p0,
+            final Object p1,
+            final Object p2,
+            final Object p3,
+            final Object p4,
+            final Object p5,
+            final Object p6,
+            final Object p7,
+            final Object p8) {
+        return p8 instanceof Throwable
+                ? newParameterizedMessage(p8, message, p0, p1, p2, p3, p4, p5, p6, p7)
+                : newParameterizedMessage(null, message, p0, p1, p2, p3, p4, p5, p6, p7, p8);
+    }
+
+    @Override
+    public Message newMessage(
+            final String message,
+            final Object p0,
+            final Object p1,
+            final Object p2,
+            final Object p3,
+            final Object p4,
+            final Object p5,
+            final Object p6,
+            final Object p7,
+            final Object p8,
+            final Object p9) {
+        return p9 instanceof Throwable
+                ? newParameterizedMessage(p9, message, p0, p1, p2, p3, p4, p5, p6, p7, p8)
+                : newParameterizedMessage(null, message, p0, p1, p2, p3, p4, p5, p6, p7, p8, p9);
+    }
+}

log4j-slf4j2-impl/src/main/java/org/apache/logging/slf4j/message/package-info.java

@@ -0,0 +1,22 @@
+/*
+ * 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.
+ */
+@Export
+@Version("2.24.0")
+package org.apache.logging.slf4j.message;
+
+import org.osgi.annotation.bundle.Export;
+import org.osgi.annotation.versioning.Version;

log4j-slf4j2-impl/src/test/java/org/apache/logging/slf4j/message/ThrowableConsumingMessageFactoryTest.java

@@ -0,0 +1,138 @@
+/*
+ * 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.
+ */
+package org.apache.logging.slf4j.message;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.apache.logging.log4j.message.Message;
+import org.apache.logging.log4j.message.MessageFactory2;
+import org.junit.jupiter.api.Test;
+
+public class ThrowableConsumingMessageFactoryTest {
+
+    private static final String MESSAGE = "MESSAGE";
+    private static final Object P0 = new Object();
+    private static final Object P1 = new Object();
+    private static final Object P2 = new Object();
+    private static final Object P3 = new Object();
+    private static final Object P4 = new Object();
+    private static final Object P5 = new Object();
+    private static final Object P6 = new Object();
+    private static final Object P7 = new Object();
+    private static final Object P8 = new Object();
+    private static final Object P9 = new Object();
+    private static final Object P10 = new Object();
+    private static final Object THROWABLE = new Throwable();
+
+    @Test
+    void should_not_consume_last_object_parameter() {
+        final MessageFactory2 factory = new ThrowableConsumingMessageFactory();
+        assertThat(factory.newMessage(MESSAGE, P0))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(1, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(2, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(3, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(4, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(5, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(6, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(7, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6, P7))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(8, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6, P7, P8))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(9, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6, P7, P8, P9))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(10, null);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6, P7, P8, P9, P10))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(11, null);
+    }
+
+    @Test
+    void should_consume_last_throwable_parameter() {
+        final MessageFactory2 factory = new ThrowableConsumingMessageFactory();
+        assertThat(factory.newMessage(MESSAGE, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(0, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(1, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(2, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(3, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(4, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(5, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(6, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(7, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6, P7, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(8, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6, P7, P8, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(9, THROWABLE);
+        assertThat(factory.newMessage(MESSAGE, P0, P1, P2, P3, P4, P5, P6, P7, P8, P9, THROWABLE))
+                .extracting(m -> m.getParameters().length, Message::getThrowable)
+                .as("checking parameter count and throwable")
+                .containsExactly(10, THROWABLE);
+    }
+}

src/changelog/.2.x.x/2363_add_logback_throwable_consuming_semantics.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<entry xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xmlns="https://logging.apache.org/xml/ns"
+       xsi:schemaLocation="https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-changelog-0.xsd"
+       type="added">
+  <issue id="2363" link="https://github.com/apache/logging-log4j2/pull/2363"/>
+  <description format="asciidoc">
+    Add Logback throwable-consuming semantics as an option in `log4j-slf4j-impl` and `log4j-slf4j2-impl`.
+    Users can enable it by setting the property `log4j2.messageFactory` to `org.apache.logging.slf4j.message.ThrowableConsumingMessageFactory`.
+  </description>
+</entry>

src/site/antora/modules/ROOT/examples/migrate-from-logback/MigrateFromLogback.java

@@ -0,0 +1,44 @@
+/*
+ * 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.
+ */
+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 exception) {
+            logger.error("The foo process exited with an error: {}", exception);
+        }
+        // end::wrong[]
+    }
+
+    doLogRight() {
+        try {
+            // do something
+            // tag::right[]
+        } catch (Exception exception) {
+            logger.error("The foo process exited with an error.", exception);
+        }
+        // end::right[]
+    }
+}

src/site/antora/modules/ROOT/pages/migrate-from-logback.adoc

@@ -106,3 +106,63 @@ 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 `exception` 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 `exception` 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 get 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`.
+====