Skip to content

Commit 427fa60

Browse files
ppkarwaszvy
andcommitted
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ı <volkan.yazici@oracle.com>
1 parent 4ed5a1e commit 427fa60

File tree

1 file changed

+8
-4
lines changed

1 file changed

+8
-4
lines changed

src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -97,8 +97,7 @@ There is no explicit separator between text and conversion specifiers.
9797
The pattern parser knows when it has reached the end of a conversion specifier when it reads a conversion character.
9898
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.
9999
100-
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.
101-
To suppress the formatting of the `Throwable` completely simply add `%ex\{0}` as a specifier in the pattern string.
100+
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.
102101
103102
[#config]
104103
== Configuration
@@ -176,7 +175,7 @@ If configured, the `replace` element must specify the regular expression to matc
176175
|Default value |`true`
177176
|===
178177
179-
If `true` and the user-provided pattern does not contain an exception converter, an implicit <<converter-exception-extended,`%xEx`>> pattern is appended.
178+
If `true` and the user-provided pattern does not contain an exception converter, an implicit <<converter-exception-extended,`%n%ex`>> pattern is appended.
180179
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.
181180
Setting this to `false` disables this behavior and allows you to exclude exceptions from your pattern output.
182181
@@ -603,7 +602,12 @@ In this mode, the exception stack trace will be rendered according to the config
603602
604603
[IMPORTANT]
605604
====
606-
All rendered exception stack traces are ensured to be prefixed with a new line obtained using `System.lineSeparator()`.
605+
Earlier versions of Log4j Core always inserted a space between the *output* of the previous conversion specifier and the stack trace.
606+
Starting with version `2.25.0`, this was changed to a line separator instead of a space.
607+
Since version `2.25.2`, automatic separation occurs *only* for converters implicitly added via the <<plugin-attr-alwaysWriteExceptions>> option.
608+
609+
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.
610+
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`).
607611
====
608612
609613
link:../javadoc/log4j-core/org/apache/logging/log4j/core/pattern/ThrowablePatternConverter.html[`ThrowablePatternConverter`] specifier grammar **for rendering stack traces**:

0 commit comments

Comments
 (0)