Skip to content

[Misc] Apply the logging best practices: don't drop the caught exception in a warn() - #399

Merged
vmassol merged 1 commit into
masterfrom
misc-logging-rendering
Aug 3, 2026
Merged

[Misc] Apply the logging best practices: don't drop the caught exception in a warn()#399
vmassol merged 1 commit into
masterfrom
misc-logging-rendering

Conversation

@vmassol

@vmassol vmassol commented Aug 3, 2026

Copy link
Copy Markdown
Member

The six-pass logging audit that ran over xwiki-platform (PRs #6055 … #6079 there) had never been pointed at this repository. This is that scan, re-implemented as a single parser covering all six passes' categories: placeholder arity and syntax, bracketing, warn() with a Throwable, concatenated / String.format() messages, e.getMessage(), calls with no message literal at all, printStackTrace(), System.out, redundant level guards, what a catch does with the exception it holds, and how the Logger field is acquired, named and modified. It resolves every Logger-typed identifier in a file rather than matching a receiver named logger, so a differently-named field is not invisible to it.

Over 667 src/main/java files it reports 8 candidates, of which 2 are real — and src/test/java adds nothing at all.

The two fixes

Both are the same defect: a warn() inside a catch that never mentions the exception, so the reason the operation failed reached no log at all. warn() must not print a stack trace, so the cause goes into a placeholder:

  • DefaultLinkCheckerThread.sendEventcatch (Exception e) around the Observation Manager lookup. The comment says "log a warning since it's not really normal", but nothing said what was not normal.
  • DefaultMacroManager.getMacroIdscatch (ParseException e) on an invalid macro id. The message explains the expected format at length; the exception is the only thing that said which part of the actual hint was wrong (Invalid macro id format [macro/invalidsyntax]).

Both tests that pin these messages are updated. Also fixes continnue in the comment immediately above the link-checker change.

The six candidates that are not violations

Recorded here so a future re-run recognises them instead of re-deciding:

  • The four if (LOGGER.isDebugEnabled()) guards in BlockStateChainingListener (invalid definition-list / list nesting). The pass-4 rule is to unwrap a guard around a single parameterized call — unless the guard also skips real work. Each of these calls builds a new IllegalStateException(), i.e. captures a stack trace, and argument evaluation is not deferred by SLF4J. Removing the guard would pay a stack-trace capture on every misnested list item in every parse. They are also else if branches of a real condition, so the guard is load-bearing in the control flow as well.
  • JspWikiSerializer.print / println's System.out — the serializer's output sink when no buffer is set, i.e. console output is the point (the same call as MimeTypesUtil.main in the platform audit). The class is also part of the integrated WikiModel code.

Verification

mvn -B -ntp test green from xwiki-rendering-transformation-macro (93 tests) and from xwiki-rendering-transformation-linkchecker (13 tests).

…ion in a warn()

First pass of the xwiki-platform logging audit over xwiki-rendering. Two warn()
calls inside a catch never mentioned the exception they were holding, so the
reason the operation failed reached no log at all. warn() must not print a stack
trace, so the cause goes into a placeholder as
ExceptionUtils.getRootCauseMessage(e).

Everything else the audit's detector reports in this repo is a non-violation and
is recorded in the PR description: the four isDebugEnabled() guards in
BlockStateChainingListener (they also skip a `new IllegalStateException()`, which
captures a stack trace, so removing them would pay that on every event) and
JspWikiSerializer's System.out (an output sink, not logging).

Also fixes "continnue" in the comment right above the link-checker change.
@vmassol vmassol self-assigned this Aug 3, 2026
@vmassol
vmassol merged commit 80c4e16 into master Aug 3, 2026
2 checks passed
@vmassol
vmassol deleted the misc-logging-rendering branch August 3, 2026 08:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant