This is an automated email from the ASF dual-hosted git repository.
pkarwasz pushed a commit to branch 2.x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
The following commit(s) were added to refs/heads/2.x by this push:
new 7209b27ba4 doc: clarify `%ex` whitespace behavior across versions
(#3918)
7209b27ba4 is described below
commit 7209b27ba4b2a9a9ce7be99b3a8af9bd74de5ad0
Author: Piotr P. Karwasz <[email protected]>
AuthorDate: Fri Sep 12 13:21:08 2025 +0200
doc: clarify `%ex` whitespace behavior across versions (#3918)
This update documents the historical whitespace handling of the `%ex`
pattern converter and how it has evolved in the `2.25.x` releases.
Key point: since `2.25.2`, when users add `%ex` explicitly in their
pattern, Log4j no longer inserts any automatic separator. It is now entirely up
to the user to decide how (or whether) to separate the stack trace from the
preceding output.
Related to #3837
Co-authored-by: Volkan Yazıcı <[email protected]>
---
.../antora/modules/ROOT/pages/manual/pattern-layout.adoc | 12 ++++++++----
1 file changed, 8 insertions(+), 4 deletions(-)
diff --git a/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc
b/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc
index b6b4aa788f..0199783f1d 100644
--- a/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc
@@ -97,8 +97,7 @@ There is no explicit separator between text and conversion
specifiers.
The pattern parser knows when it has reached the end of a conversion specifier
when it reads a conversion character.
In the example above the conversion specifier `%-5p` means the priority of the
log event should be left justified to a width of five characters.
-If the pattern string does not contain a specifier to handle a `Throwable`
being logged, parsing of the pattern will act as if the `%xEx` specifier had
been added to the end of the string.
-To suppress the formatting of the `Throwable` completely simply add `%ex\{0}`
as a specifier in the pattern string.
+If the pattern string does not contain a specifier to handle a `Throwable`
being logged, parsing of the pattern will act as if the `%n%ex` specifier had
been added to the end of the string.
[#config]
== Configuration
@@ -176,7 +175,7 @@ If configured, the `replace` element must specify the
regular expression to matc
|Default value |`true`
|===
-If `true` and the user-provided pattern does not contain an exception
converter, an implicit <<converter-exception-extended,`%xEx`>> pattern is
appended.
+If `true` and the user-provided pattern does not contain an exception
converter, an implicit <<converter-exception-extended,`%n%ex`>> pattern is
appended.
This means that if you do not include a way to output exceptions in your
pattern, the default exception formatter will be added to the end of the
pattern.
Setting this to `false` disables this behavior and allows you to exclude
exceptions from your pattern output.
@@ -603,7 +602,12 @@ In this mode, the exception stack trace will be rendered
according to the config
[IMPORTANT]
====
-All rendered exception stack traces are ensured to be prefixed with a new line
obtained using `System.lineSeparator()`.
+Earlier versions of Log4j Core always inserted a space between the *output* of
the previous conversion specifier and the stack trace.
+Starting with version `2.25.0`, this was changed to a line separator instead
of a space.
+Since version `2.25.2`, automatic separation occurs *only* for converters
implicitly added via the <<plugin-attr-alwaysWriteExceptions>> option.
+
+When you add a throwable converter explicitly in your pattern, Log4j Core no
longer inserts any separator on its own: you have full control over whether and
how to separate the stack trace from the preceding message.
+Thus, if you explicitly provide an exception stack trace converter (e.g.,
`%ex`), and want to prefix it with a newline, you need it add the newline
prefix yourself too (e.g., `%n%ex`).
====
link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`]
specifier grammar **for rendering stack traces**:
