Ready for review

Last modified by Eleni Cojocariu on 2026/11/13 20:57

Show last authors
1 Converts [[Logging>>Documentation.AdminGuide.Logging]] into ##documentation.xs.admin.logging##, a new top-level Administrator topic beside Performance, Store and Statistics Configuration. The legacy page mixed an explanation of the logging stack, a file-location reference and five unrelated procedures into one page; the new tree had no logging topic at all.
2
3 **Seven new pages**: the topic page (Explanation, with a diagram of the SLF4J/Logback pipeline), [[Log File Locations>>documentation.xs.admin.logging.file-locations.WebHome]] (Reference), and five How-tos — [[Configure Log Levels>>documentation.xs.admin.logging.configure-levels.WebHome]], [[Change Log Levels at Runtime>>documentation.xs.admin.logging.change-levels-runtime.WebHome]], [[Analyze Logs with Lilith>>documentation.xs.admin.logging.analyze-lilith.WebHome]], [[Replace Logback with Another SLF4J Provider>>documentation.xs.admin.logging.replace-logback.WebHome]] and [[Monitor Component Execution Times>>documentation.xs.admin.logging.monitor-execution-times.WebHome]]. Each How-to ends on a result step, which no legacy procedure had, and the runtime one carries four screenshots captured on an 18.9.0 instance.
4
5 **Merge order**: this Change Request must be merged **after** [[Convert the Debian/Ubuntu (.DEB) installation documentation into the new tree>>ChangeRequest.Data.convert-debian-ubuntu-deb-i-01331ce0-336b-4184-a61e-f7d5d250af35.WebHome]]. [[Log File Locations>>documentation.xs.admin.logging.file-locations.WebHome]] links ##documentation.xs.admin.installation.methods.install-xwiki-debian.WebHome## twice, for the Tomcat and the ##xjetty## packages, and that page is created by that Change Request. Merged the other way round, those two cells ship as red links.
6
7 **Five facts on the legacy page were stale or wrong and are corrected, not carried over:**
8
9 * The standalone distribution has not written ##data/logs/<date>.output.log## since XWIKI-18152 (the Jetty 10 upgrade). Jetty's ##console-capture## module tees stdout to ##logs/<yyyy_mm_dd>.jetty.log## under the distribution directory, with ##logs/<yyyy_mm_dd>.request.log## beside it.
10 * The Debian packages are ##tomcat10##, ##tomcat11## and ##xjetty##, not ##tomcat9##; the ##xjetty## one symlinks its Jetty ##logs## directory to ##/var/log/xwiki##.
11 * "The monitoring feature is already active in the default configuration" is false. ##MonitorPlugin.init()## reads ##ParamAsLong("xwiki.monitor", 0)## and ##xwiki.monitor## is commented out in the shipped ##xwiki.cfg##: the plugin is loaded, but inactive.
12 * The SLF4J section listed ##slf4j-log4j*-*.jar##, the SLF4J **1.x** binding. XWiki ships SLF4J 2.0.17, which resolves its provider through the ##ServiceLoader## and has no ##slf4j-log4j12##; the page now describes swapping the provider generically, with ##log4j-slf4j2-impl## as the worked example, and warns that dropping Logback also disables the Logging Application and the per-job logs.
13 * On a Debian or Ubuntu package the Logback file to edit is ##/etc/xwiki/logback.xml## — ##WEB-INF/classes/logback.xml## is a symbolic link to it, so an edit there survives a package upgrade. The legacy page never said this.
14
15 **One correction outside the logging tree**: [[Performance Parameters>>documentation.xs.admin.performance.parameters.WebHome]] documents ##xwiki.monitor## with a default of ##1##, under an intro saying every parameter ships commented out at the default shown. ##MonitorPlugin.init()## reads ##ParamAsLong("xwiki.monitor", 0)##, so the default is ##0## and that row contradicted the new How-to. Its "Default" and "What is given up" cells are corrected here, rather than left to contradict a page this Change Request adds.
16
17 **Dropped as obsolete**: the JMX section (Logback dropped JMX support in XWiki 14.8, far below the LTS) survives as an FAQ entry on the topic page that says so and points at the Logging Application instead; the Docker log locations are a link to [[the page that already documents them>>documentation.xs.admin.installation.methods.install-xwiki-docker.configuration.logs.WebHome]] rather than a copy.
18
19 **Backlinks**: the three new-tree pages that linked the legacy page are repointed in this Change Request — [[Docker logs>>documentation.xs.admin.installation.methods.install-xwiki-docker.configuration.logs.WebHome]] (in its content **and** in its Related links field), [[Back Up an Instance>>documentation.xs.admin.backup.backup-instance.WebHome]] and [[Restore Batches>>documentation.xs.admin.base.page.index.restore-batches.WebHome]], whose deep link to ##HJobLogs## still resolves because the new Reference page keeps a "Job Logs" heading. Five legacy-tree pages and one release note are left alone as historical records; the seven extensions-wiki pages and the two dev-wiki ones need their own edits, since a Change Request cannot span two wikis.
20
21 **Not in this Change Request**: the strip of ##Documentation.AdminGuide.Logging## itself and the deletion of its ##lilith.png## attachment. The open Change Request "Convert the Debian/Ubuntu (.DEB) installation documentation into the new tree" still carries its own file change on that page, and two Change Requests editing it would conflict. The strip follows in its own Change Request once that one merges.

Get Connected