Ready for review
Convert the Logging administration documentation into the new tree
Converts 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.
Seven new pages: the topic page (Explanation, with a diagram of the SLF4J/Logback pipeline), Log File Locations (Reference), and five How-tos — Configure Log Levels, Change Log Levels at Runtime, Analyze Logs with Lilith, Replace Logback with Another SLF4J Provider and Monitor Component Execution Times. 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.
Merge order: this Change Request must be merged after Convert the Debian/Ubuntu (.DEB) installation documentation into the new tree. Log File Locations 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.
Five facts on the legacy page were stale or wrong and are corrected, not carried over:
- 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.
- The Debian packages are tomcat10, tomcat11 and xjetty, not tomcat9; the xjetty one symlinks its Jetty logs directory to /var/log/xwiki.
- "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.
- 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.
- 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.
One correction outside the logging tree: Performance Parameters 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.
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 rather than a copy.
Backlinks: the three new-tree pages that linked the legacy page are repointed in this Change Request — Docker logs (in its content and in its Related links field), Back Up an Instance and Restore Batches, 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.
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.
-
Eleni Cojocariu added a new change for Analyze Logs with Lilith
4 days ago
-
Eleni Cojocariu added a new change for Analyze Logs with Lilith
4 days ago
-
Eleni Cojocariu added a new change for Logging
4 days ago
-
Eleni Cojocariu added a new change for Configure Log Levels
4 days ago
-
Eleni Cojocariu added a new change for Analyze Logs with Lilith
4 days ago
-
Eleni Cojocariu added a new change for XWiki Logs in the Docker Image
4 days ago
-
Eleni Cojocariu added a new change for Performance Parameters
4 days ago
-
Eleni Cojocariu edited the description or the title of the Change Request
4 days ago
All changes
Summary
-
Page properties (3 modified, 0 added, 0 removed)
-
Objects (0 modified, 2 added, 0 removed)
Details
- Page properties
-
- Title
-
... ... @@ -1,0 +1,1 @@ 1 +Logging - Author
-
... ... @@ -1,1 +1,1 @@ 1 -XWiki. XWikiGuest1 +XWiki.elenicojocariu - Default language
-
... ... @@ -1,0 +1,1 @@ 1 +en - Content
-
... ... @@ -1,0 +1,59 @@ 1 +XWiki writes its log records through [[SLF4J>>https://www.slf4j.org/]], backed by [[Logback>>https://logback.qos.ch/]] by default, and the bundled [[Logging Application>>doc:extensions:Extension.Logging Application]] lists every registered logger in the wiki administration. 2 + 3 +The configuration that decides what is written, and where, is the {{scm path="xwiki-platform-core/xwiki-platform-web/xwiki-platform-web-war/src/main/resources/logback.xml"}}##logback.xml##{{/scm}} file of the deployed web application. 4 + 5 +== How XWiki Collects Logs == 6 + 7 +{{plantuml}} 8 +@startuml 9 +!theme bluegray 10 +skinparam componentStyle rectangle 11 +left to right direction 12 + 13 +component "**XWiki**\norg.xwiki, com.xwiki,\ncom.xpn.xwiki" as XWIKI 14 +component "**Apache Commons Logging**" as JCL 15 +component "**Log4j 1.x**" as L41 16 +component "**Log4j 2**" as L42 17 +component "**java.util.logging**\nLucene, behind Solr" as JUL 18 + 19 +component "**SLF4J**\nthe logging facade" as SLF4J 20 +component "**Logback**\nthe default provider" as LOGBACK 21 +component "**Appenders**\nthe console, by default" as OUT 22 + 23 +file "**logback.xml**\nlevels and appenders,\nkept across restarts" as CONF 24 +component "**Logging Application**\nlevels, until the\nnext restart" as APP 25 + 26 +XWIKI --> SLF4J 27 +JCL --> SLF4J : jcl-over-slf4j 28 +L41 --> SLF4J : log4j-over-slf4j 29 +L42 --> SLF4J : log4j-to-slf4j 30 +JUL --> SLF4J : jul-to-slf4j 31 +SLF4J --> LOGBACK 32 +LOGBACK --> OUT 33 +CONF ..> LOGBACK 34 +APP ..> LOGBACK 35 +@enduml 36 +{{/plantuml}} 37 + 38 +Every library on XWiki's runtime classpath ends up in that same output, whichever logging framework it was written against: XWiki ships an SLF4J bridge for Apache Commons Logging, for Log4j 1.x and for Log4j 2, so none of them needs a configuration file of its own. {{version since="18.10.0RC1"}}The same holds for ##java.util.logging##, used by Lucene behind Solr. Unless a bridge is already installed, XWiki installs one at start-up in place of the handlers of the ##java.util.logging## root logger, so that records are not printed twice, and puts those handlers back when it stops. The ##LevelChangePropagator## declared in the Logback configuration applies the levels you configure there to the ##java.util.logging## loggers, so they stop producing records for levels you disabled.{{/version}} 39 + 40 +== Where the Logs Go == 41 + 42 +The shipped Logback configuration declares a single console appender, so XWiki itself writes nowhere else. [[Log File Locations>>doc:documentation.xs.admin.logging.file-locations.WebHome]] gives the file each installation method captures that console into. 43 + 44 +Long operations run as jobs, and a job keeps a log of its own beside the main one. 45 + 46 +== Changing What Is Logged == 47 + 48 +There are two ways to change a logger's level, and they differ in one respect that matters more than the rest: **only a change made in the Logback configuration file survives a restart**. 49 + 50 +* [[Configure Log Levels>>doc:documentation.xs.admin.logging.configure-levels.WebHome]] edits ##logback.xml##, and takes effect at the next restart. 51 +* [[Change Log Levels at Runtime>>doc:documentation.xs.admin.logging.change-levels-runtime.WebHome]] uses the Logging Application, and takes effect at once, which is what you want while reproducing a problem. 52 + 53 +A logger is named after a Java package or class, and a level set on a package applies to everything below it: ##org.xwiki## and ##com.xwiki## cover XWiki's own components, ##com.xpn.xwiki## its older code base, and ##org.hibernate## the database layer. 54 + 55 +== Going Further == 56 + 57 +* [[Analyze Logs with Lilith>>doc:documentation.xs.admin.logging.analyze-lilith.WebHome]] streams the records to a desktop viewer built for large volumes of log events. 58 +* [[Replace Logback with Another SLF4J Provider>>doc:documentation.xs.admin.logging.replace-logback.WebHome]] swaps the backend for a different one. 59 +* [[Monitor Component Execution Times>>doc:documentation.xs.admin.logging.monitor-execution-times.WebHome]] turns on the per-request timings XWiki can record for its major components.
- DocApp.Code.DocumentationClass[0]
-
- FAQ
-
... ... @@ -1,0 +1,3 @@ 1 +== Can I configure logging over JMX? == 2 + 3 +No. The Logback versions XWiki ships no longer expose their configuration over JMX. Use the Logging Application for an immediate change, and ##logback.xml## for one that survives a restart. - Related
-
... ... @@ -1,0 +1,2 @@ 1 +* [[Debugging>>doc:dev:Community.Debugging]] 2 +* [[XWiki Logs in the Docker Image>>doc:documentation.xs.admin.installation.methods.install-xwiki-docker.configuration.logs.WebHome]] - Target
-
... ... @@ -1,0 +1,1 @@ 1 +administrator - Type
-
... ... @@ -1,0 +1,1 @@ 1 +explanation
- DocApp.Code.DocumentationExtensionClass[0]
-
- Technical Identifier
-
... ... @@ -1,0 +1,1 @@ 1 +xwiki:org.xwiki.platform:xwiki-platform-logging-ui
Summary
-
Page properties (3 modified, 0 added, 0 removed)
-
Objects (0 modified, 2 added, 0 removed)
Details
- Page properties
-
- Title
-
... ... @@ -1,0 +1,1 @@ 1 +Log File Locations - Author
-
... ... @@ -1,1 +1,1 @@ 1 -XWiki. XWikiGuest1 +XWiki.elenicojocariu - Default language
-
... ... @@ -1,0 +1,1 @@ 1 +en - Content
-
... ... @@ -1,0 +1,20 @@ 1 +XWiki logs to the console, and the console is captured by whatever starts XWiki, so the file to open depends on how the instance was installed rather than on XWiki itself. 2 + 3 +== Where Each Installation Writes == 4 + 5 +|=Installation Method|=XWiki's Log|=How to Read It 6 +|[[Standalone (demo) distribution>>doc:documentation.xs.admin.installation.methods.install-standalone-demo-distribution.WebHome]]|The console, and ##logs/<yyyy_mm_dd>.jetty.log## under the distribution directory|##tail -f logs/*.jetty.log##. Jetty keeps 90 days of files, named after the GMT day they cover, and writes its access log beside them as ##<yyyy_mm_dd>.request.log##. 7 +|[[Debian or Ubuntu package>>doc:documentation.xs.admin.installation.methods.install-xwiki-debian.WebHome]], on Tomcat|##/var/log/tomcat10/catalina.out## or ##/var/log/tomcat11/catalina.out##, depending on which package is installed|##journalctl -u tomcat10## on a system where Tomcat runs under systemd, otherwise read the file 8 +|[[Debian or Ubuntu package>>doc:documentation.xs.admin.installation.methods.install-xwiki-debian.WebHome]], on Jetty (the ##xjetty## package)|##/var/log/xwiki/<yyyy_mm_dd>.jetty.log##, the package having symlinked Jetty's log directory there|##journalctl -u xwiki##, or read the file 9 +|[[Docker image>>doc:documentation.xs.admin.installation.methods.install-xwiki-docker.configuration.logs.WebHome]]|The container console, and a rotating file in the permanent directory|##docker logs##. That page covers the Docker case in full, including what survives the container. 10 +|[[Manual .war deployment>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.WebHome]]|Wherever the servlet container sends its console|For Tomcat, ##/var/log/tomcat*/catalina.out## on a packaged install or ##<tomcat home>/logs/catalina.out## on an unpacked one 11 + 12 +== Job Logs == 13 + 14 +Operations that can take a while run as jobs: installing or upgrading an extension, deleting a batch of pages, rebuilding the search index. Each job keeps its own log, separate from the main one, in the [[permanent directory>>doc:documentation.xs.admin.configuration.directories.permanent-directory.WebHome]]: 15 + 16 +{{code language="none"}} 17 +<permanent directory>/jobs/status/<job id>/log.xml 18 +{{/code}} 19 + 20 +Those files are written for the user interface rather than for reading directly. The [[Extension Manager>>doc:extensions:Extension.Extension Manager Application]] shows the progress log of an installation or an upgrade, which is the first place to look when an extension fails to install.
- DocApp.Code.DocumentationClass[0]
-
- FAQ
-
... ... @@ -1,0 +1,7 @@ 1 +== Why is there no xwiki.log file? == 2 + 3 +Because the Logback configuration XWiki ships declares a console appender and nothing else. To get a file of your own, add a file appender in ##logback.xml##, as described in [[Configure Log Levels>>doc:documentation.xs.admin.logging.configure-levels.WebHome]]. 4 + 5 +== The log stops at the servlet container's startup messages. Where is the rest? == 6 + 7 +The container is capturing its console somewhere other than the file you opened, which is common when it runs under systemd. Ask systemd instead, with ##journalctl -u## followed by the service name. - Related
-
... ... @@ -1,0 +1,2 @@ 1 +* [[XWiki Logs in the Docker Image>>doc:documentation.xs.admin.installation.methods.install-xwiki-docker.configuration.logs.WebHome]] 2 +* [[XWiki Directories>>doc:documentation.xs.admin.configuration.directories.WebHome]] - Target
-
... ... @@ -1,0 +1,1 @@ 1 +administrator - Type
-
... ... @@ -1,0 +1,1 @@ 1 +reference
- DocApp.Code.DocumentationExtensionClass[0]
-
- Technical Identifier
-
... ... @@ -1,0 +1,1 @@ 1 +xwiki:org.xwiki.platform:xwiki-platform-logging-ui
Summary
-
Page properties (3 modified, 0 added, 0 removed)
-
Objects (0 modified, 2 added, 0 removed)
Details
- Page properties
-
- Title
-
... ... @@ -1,0 +1,1 @@ 1 +Configure Log Levels - Author
-
... ... @@ -1,1 +1,1 @@ 1 -XWiki. XWikiGuest1 +XWiki.elenicojocariu - Default language
-
... ... @@ -1,0 +1,1 @@ 1 +en - Content
-
... ... @@ -1,0 +1,40 @@ 1 +Change which messages XWiki writes to [[its log>>doc:documentation.xs.admin.logging.file-locations.WebHome]] by editing the Logback configuration file, the only place where a level survives a restart. 2 + 3 +1. Open the Logback configuration file. It is ##WEB-INF/classes/logback.xml## inside the deployed web application, except on a Debian or Ubuntu package, where that path is a symbolic link and the file to edit is ##/etc/xwiki/logback.xml##, which a package upgrade leaves alone.((( 4 +{{code language="none"}} 5 +/var/lib/tomcat11/webapps/xwiki/WEB-INF/classes/logback.xml a .war deployment on Tomcat 6 +webapps/xwiki/WEB-INF/classes/logback.xml the standalone distribution 7 +/etc/xwiki/logback.xml a Debian or Ubuntu package 8 +{{/code}} 9 +))) 10 +1. Look at the loggers the file already declares, so that you change one rather than add a second declaration of it. The shipped configuration keeps the root logger at ##warn##, raises XWiki's own components to ##info##, and silences a few libraries that are noisy by default.((( 11 +{{code language="xml"}} 12 +<root level="warn"> 13 + <appender-ref ref="stdout"/> 14 +</root> 15 + 16 +<logger name="org.xwiki" level="info"/> 17 +<logger name="com.xwiki" level="info"/> 18 +<logger name="com.xpn.xwiki" level="warn"/> 19 +<logger name="org.hibernate" level="warn"/> 20 +<logger name="org.hibernate.SQL" level="warn"/> 21 +{{/code}} 22 +))) 23 +1. Set the level you want on the logger you want, naming it [[as precisely as the package tree allows>>doc:documentation.xs.admin.logging.WebHome]]. The levels, from most to least verbose, are ##trace##, ##debug##, ##info##, ##warn## and ##error##. To see the SQL statements XWiki sends to the database, lower the logger the file already declares for them.((( 24 +{{code language="xml"}} 25 +<logger name="org.hibernate.SQL" level="debug"/> 26 +{{/code}} 27 +))) 28 +1. Restart the servlet container. Logback reads the file once at start-up, so nothing changes until then.((( 29 +{{code language="bash"}} 30 +sudo systemctl restart tomcat11 # a Tomcat package 31 +sudo systemctl restart xwiki # the Debian or Ubuntu Jetty package 32 +./stop_xwiki.sh && ./start_xwiki.sh # the standalone distribution 33 +{{/code}} 34 +))) 35 +1. Exercise the feature you are investigating and read the log. The records you asked for are now there, at the level you set, and they stay there across every later restart.((( 36 +{{code language="none"}} 37 +2026-11-10 16:12:51,759 [qtp927327686-37 - http://localhost:8080/xwiki/bin/get/Sandbox/WebHome?] DEBUG o.h.SQL - select count(*) as col_0_0_ from xwikispace xwikispace0_ where xwikispace0_.XWS_PARENT=? 38 +2026-11-10 16:12:51,830 [qtp927327686-166 - http://localhost:8080/xwiki/bin/get/Sandbox/WebHome?] DEBUG o.h.SQL - select count(*) as col_0_0_ from xwikispace xwikispace0_ where xwikispace0_.XWS_PARENT=? and xwikispace0_.XWS_HIDDEN<>true 39 +{{/code}} 40 +)))
- DocApp.Code.DocumentationClass[0]
-
- FAQ
-
... ... @@ -1,0 +1,7 @@ 1 +== Which logger name should I use? == 2 + 3 +The one the records already carry. The logger is the fourth field of each line, with its package shortened to initials, so ##o.h.SQL## in the output above is ##org.hibernate.SQL##. [[Change Log Levels at Runtime>>doc:documentation.xs.admin.logging.change-levels-runtime.WebHome]] lists every registered logger under its full name. 4 + 5 +== Can I write the log to a file of my own? == 6 + 7 +Yes. Declare a Logback file appender in the same file and reference it from the root logger. The [[Docker image>>doc:documentation.xs.admin.installation.methods.install-xwiki-docker.configuration.logs.WebHome]] ships exactly that, with a rotation policy you can copy. - Related
-
... ... @@ -1,0 +1,2 @@ 1 +* [[Change Log Levels at Runtime>>doc:documentation.xs.admin.logging.change-levels-runtime.WebHome]] 2 +* [[Logging Details in the Debugging Guide>>doc:dev:Community.Debugging||anchor="HLogging"]] - Target
-
... ... @@ -1,0 +1,1 @@ 1 +administrator - Type
-
... ... @@ -1,0 +1,1 @@ 1 +howto
- DocApp.Code.DocumentationExtensionClass[0]
-
- Technical Identifier
-
... ... @@ -1,0 +1,1 @@ 1 +xwiki:org.xwiki.platform:xwiki-platform-logging-ui
Summary
-
Page properties (3 modified, 0 added, 0 removed)
-
Attachments (0 modified, 4 added, 0 removed)
-
Objects (0 modified, 2 added, 0 removed)
Details
- Page properties
-
- Title
-
... ... @@ -1,0 +1,1 @@ 1 +Change Log Levels at Runtime - Author
-
... ... @@ -1,1 +1,1 @@ 1 -XWiki. XWikiGuest1 +XWiki.elenicojocariu - Default language
-
... ... @@ -1,0 +1,1 @@ 1 +en - Content
-
... ... @@ -1,0 +1,14 @@ 1 +Raise or lower a logger's level without restarting the server, with the [[Logging Application>>doc:extensions:Extension.Logging Application]] of the wiki administration. 2 + 3 +1. Open the wiki administration and select "Other" in the menu, then "Logging".((( 4 +{{image reference="administration-logging-section.png" size="extra" alt="The Logging entry of the wiki administration menu, with the list of loggers beside it"/}} 5 +))) 6 +1. Filter the "Logger" column to the package or class you are investigating. The table lists every logger XWiki has registered so far, under its full name. A row whose "Level" is empty takes its level from the logger above it in the name, or from the Logback configuration when there is none.((( 7 +{{image reference="logging-filter-logger.png" size="large" alt="The Logger column filtered to org.xwiki.store, showing the matching loggers"/}} 8 +))) 9 +1. Pick a level in the row's list, then select "Set".((( 10 +{{image reference="logging-set-level.png" size="large" alt="The level list of a logger row, expanded on DEBUG"/}} 11 +))) 12 +1. The confirmation names the logger and its new level, and the "Level" column shows it. XWiki starts writing at that level immediately, and keeps doing so until the servlet container is restarted. To keep the change, set it in the Logback configuration file as well, as described in [[Configure Log Levels>>doc:documentation.xs.admin.logging.configure-levels.WebHome]].((( 13 +{{image reference="logging-level-confirmation.png" size="large" alt="The confirmation message and the Logger row now showing the DEBUG level"/}} 14 +)))
- administration-logging-section.png
-
- Author
-
... ... @@ -1,0 +1,1 @@ 1 +XWiki.elenicojocariu - Size
-
... ... @@ -1,0 +1,1 @@ 1 +79.5 KB - Content
- logging-filter-logger.png
-
- Author
-
... ... @@ -1,0 +1,1 @@ 1 +XWiki.elenicojocariu - Size
-
... ... @@ -1,0 +1,1 @@ 1 +18.9 KB - Content
- logging-level-confirmation.png
-
- Author
-
... ... @@ -1,0 +1,1 @@ 1 +XWiki.elenicojocariu - Size
-
... ... @@ -1,0 +1,1 @@ 1 +21.1 KB - Content
- logging-set-level.png
-
- Author
-
... ... @@ -1,0 +1,1 @@ 1 +XWiki.elenicojocariu - Size
-
... ... @@ -1,0 +1,1 @@ 1 +12.4 KB - Content
- DocApp.Code.DocumentationClass[0]
-
- FAQ
-
... ... @@ -1,0 +1,15 @@ 1 +== Why can I read the levels but not change them? == 2 + 3 +The "Actions" column is rendered only for a user who has the programming right. Without it the screen is read only. 4 + 5 +== Can I change a level from a script? == 6 + 7 +Yes. The ##$services.logging## script service does the same from Velocity or Groovy: ##getLevels()## returns every registered logger with its level, ##getLevel()## reads one, and ##setLevel('org.xwiki.store', 'debug')## sets one. ##setLevel## needs the programming right too, and without it does nothing at all rather than reporting an error. 8 + 9 +== Can I set a level for a logger that is not in the list? == 10 + 11 +No. The list holds the loggers XWiki has registered, and a name outside it is refused with "Failed to set log level". Declare it in the Logback configuration file instead. 12 + 13 +== How do I undo a change? == 14 + 15 +Select "default" in the row's list. That unsets the level, which returns the logger to inheriting from its parent rather than to the value in the Logback configuration file. Restart the servlet container to get the configured value back. - Related
-
... ... @@ -1,0 +1,2 @@ 1 +* [[Configure Log Levels>>doc:documentation.xs.admin.logging.configure-levels.WebHome]] 2 +* [[Log File Locations>>doc:documentation.xs.admin.logging.file-locations.WebHome]] - Target
-
... ... @@ -1,0 +1,1 @@ 1 +administrator - Type
-
... ... @@ -1,0 +1,1 @@ 1 +howto
- DocApp.Code.DocumentationExtensionClass[0]
-
- Technical Identifier
-
... ... @@ -1,0 +1,1 @@ 1 +xwiki:org.xwiki.platform:xwiki-platform-logging-ui
Summary
-
Page properties (3 modified, 0 added, 0 removed)
-
Attachments (0 modified, 1 added, 0 removed)
-
Objects (0 modified, 2 added, 0 removed)
Details
- Page properties
-
- Title
-
... ... @@ -1,0 +1,1 @@ 1 +Analyze Logs with Lilith - Author
-
... ... @@ -1,1 +1,1 @@ 1 -XWiki. XWikiGuest1 +XWiki.elenicojocariu - Default language
-
... ... @@ -1,0 +1,1 @@ 1 +en - Content
-
... ... @@ -1,0 +1,26 @@ 1 +Send XWiki's log events to [[Lilith>>https://github.com/huxi/lilith]], a desktop viewer that makes a large volume of events searchable, instead of reading [[the log file>>doc:documentation.xs.admin.logging.file-locations.WebHome]] line by line. 2 + 3 +1. Install Lilith and start it. It listens on port 4560 out of the box, so there is nothing to configure on its side. 4 +1. Declare a Logback socket appender in the Logback configuration file. Set ##RemoteHost## to the machine Lilith runs on, which is not necessarily the one XWiki runs on.((( 5 +{{code language="xml"}} 6 +<appender name="socket" class="ch.qos.logback.classic.net.SocketAppender"> 7 + <RemoteHost>localhost</RemoteHost> 8 + <Port>4560</Port> 9 + <ReconnectionDelay>170</ReconnectionDelay> 10 +</appender> 11 +{{/code}} 12 +))) 13 +1. Reference that appender from the root logger, beside the console one, so the events go to both.((( 14 +{{code language="xml"}} 15 +<root level="warn"> 16 + <appender-ref ref="stdout"/> 17 + <appender-ref ref="socket"/> 18 +</root> 19 +{{/code}} 20 +))) 21 +1. Restart the servlet container. 22 +1. Lilith fills with XWiki's events as the instance starts, one row per record, colour-coded by level. Selecting a row shows its full message, logger and thread below, and for a page request the thread name is the URL being served.((( 23 +{{image reference="lilith-log-viewer.png" size="extra" alt="The Lilith window listing XWiki log events, with the details of the selected event below"/}} 24 +))) 25 + 26 +[[Raising a logger to DEBUG>>doc:documentation.xs.admin.logging.change-levels-runtime.WebHome]] while Lilith is connected is the usual way to use it: the events collect in Lilith to be searched there, instead of scrolling past in the console.
- lilith-log-viewer.png
-
- Author
-
... ... @@ -1,0 +1,1 @@ 1 +XWiki.elenicojocariu - Size
-
... ... @@ -1,0 +1,1 @@ 1 +114.7 KB - Content
- DocApp.Code.DocumentationClass[0]
-
- FAQ
-
... ... @@ -1,0 +1,11 @@ 1 +== Nothing reaches Lilith == 2 + 3 +Check that the appender is referenced from a logger that is actually firing, that port 4560 is reachable from the XWiki machine, and that the servlet container was restarted after the change. 4 + 5 +== Why does every event show the same timestamp? == 6 + 7 +Because Logback renamed the field. XWiki ships Logback 1.3 or later, which serialises the event's time as ##timestamp##, while Lilith reads ##timeStamp##, the name Logback 1.2 used. Java serialisation matches fields by name, so Lilith finds none and shows ##02:00:00.000## on every row. The same rename of ##marker## to ##markerList## leaves the Marker column empty, and ##IncludeCallerData## no longer has any effect: Logback warns at startup that nothing asks for caller extraction, and the detail pane has no Call Location row. Message, level, logger and thread are unaffected, so filtering and searching still work, but read the sequence from the ID column rather than from the clock. Nothing in XWiki's configuration changes this; it needs a Lilith release built against a current Logback. 8 + 9 +== Does this replace the log file? == 10 + 11 +No. The socket appender is an extra destination, and the console appender keeps writing wherever it wrote before. Lilith also only holds what it received while it was running. - Related
-
... ... @@ -1,0 +1,2 @@ 1 +* [[Configure Log Levels>>doc:documentation.xs.admin.logging.configure-levels.WebHome]] 2 +* [[Log File Locations>>doc:documentation.xs.admin.logging.file-locations.WebHome]] - Target
-
... ... @@ -1,0 +1,1 @@ 1 +administrator - Type
-
... ... @@ -1,0 +1,1 @@ 1 +howto
- DocApp.Code.DocumentationExtensionClass[0]
-
- Technical Identifier
-
... ... @@ -1,0 +1,1 @@ 1 +xwiki:org.xwiki.platform:xwiki-platform-logging-ui
Summary
-
Page properties (3 modified, 0 added, 0 removed)
-
Objects (0 modified, 2 added, 0 removed)
Details
- Page properties
-
- Title
-
... ... @@ -1,0 +1,1 @@ 1 +Replace Logback with Another SLF4J Provider - Author
-
... ... @@ -1,1 +1,1 @@ 1 -XWiki. XWikiGuest1 +XWiki.elenicojocariu - Default language
-
... ... @@ -1,0 +1,1 @@ 1 +en - Content
-
... ... @@ -1,0 +1,26 @@ 1 +Run XWiki's logging on a backend other than Logback by swapping the SLF4J provider in ##WEB-INF/lib##, at the cost of the features [[XWiki builds on Logback>>doc:documentation.xs.admin.logging.WebHome]]. 2 + 3 +1. Remove the Logback provider from ##WEB-INF/lib##.((( 4 +{{code language="none"}} 5 +logback-classic-*.jar 6 +logback-core-*.jar 7 +{{/code}} 8 +))) 9 +1. Remove XWiki's own Logback integration, which has nowhere left to plug into. This is the step with a visible consequence: ##DefaultLoggerManager## is the only implementation XWiki has of the component the [[Logging Application>>doc:documentation.xs.admin.logging.change-levels-runtime.WebHome]] reads and writes levels through, and ##LogbackEventGenerator## is what turns log records into the events the per-job logs are built from. Without them, the administration screen has nothing to show and jobs such as an extension installation no longer keep a log of their own.((( 10 +{{code language="none"}} 11 +xwiki-commons-logging-logback-*.jar 12 +{{/code}} 13 +))) 14 +1. Remove the SLF4J bridge for the framework you are moving **to**, or its records will be handed to SLF4J and then back to itself. Moving to Log4j 2 means removing both of the Log4j bridges.((( 15 +{{code language="none"}} 16 +log4j-over-slf4j-*.jar only if you move to Log4j 1.x 17 +log4j-to-slf4j-*.jar only if you move to Log4j 2 18 +{{/code}} 19 +))) 20 +1. Add the backend and its SLF4J 2 provider. For Log4j 2 that is ##log4j-core## plus ##log4j-slf4j2-impl##; ##log4j-api## is already in ##WEB-INF/lib##, so check the version before adding a second copy. 21 +1. Write the backend's own configuration file into ##WEB-INF/classes##, since ##logback.xml## means nothing to it, and give it at least the levels the Logback configuration had. 22 +1. Restart the servlet container. XWiki's startup records now come out through the new backend, wherever its configuration sends them, and the line format is the one that configuration defines rather than Logback's.((( 23 +{{code language="none"}} 24 +2026-11-10 16:12:37,160 [main] INFO o.x.e.i.ServletEnvironment - Using permanent directory [data] 25 +{{/code}} 26 +)))
- DocApp.Code.DocumentationClass[0]
-
- FAQ
-
... ... @@ -1,0 +1,11 @@ 1 +== Why is there no binding jar such as slf4j-log4j12 to add? == 2 + 3 +Because XWiki ships SLF4J 2, which resolves its provider through the Java ##ServiceLoader## rather than through a binding jar. ##slf4j-log4j12## is an SLF4J 1.x binding and is never picked up; what you add is the provider the backend itself publishes, ##log4j-slf4j2-impl## in the case of Log4j 2. 4 + 5 +== Do third-party libraries still log? == 6 + 7 +Yes, through whichever bridges you left in place. ##jcl-over-slf4j##, ##log4j-over-slf4j##, ##log4j-to-slf4j## and ##jul-to-slf4j## each hand one framework's records to SLF4J, and SLF4J then hands them to the new provider. 8 + 9 +== Is this supported? == 10 + 11 +Logback is what XWiki is built, shipped and tested on. Everything above is possible, not recommended, and it is on you to keep it working across upgrades. - Related
-
... ... @@ -1,0 +1,2 @@ 1 +* [[Configure Log Levels>>doc:documentation.xs.admin.logging.configure-levels.WebHome]] 2 +* [[Change Log Levels at Runtime>>doc:documentation.xs.admin.logging.change-levels-runtime.WebHome]] - Target
-
... ... @@ -1,0 +1,1 @@ 1 +administrator - Type
-
... ... @@ -1,0 +1,1 @@ 1 +howto
- DocApp.Code.DocumentationExtensionClass[0]
-
- Technical Identifier
-
... ... @@ -1,0 +1,1 @@ 1 +xwiki:org.xwiki.platform:xwiki-platform-logging-ui
Summary
-
Page properties (3 modified, 0 added, 0 removed)
-
Objects (0 modified, 2 added, 0 removed)
Details
- Page properties
-
- Title
-
... ... @@ -1,0 +1,1 @@ 1 +Monitor Component Execution Times - Author
-
... ... @@ -1,1 +1,1 @@ 1 -XWiki. XWikiGuest1 +XWiki.elenicojocariu - Default language
-
... ... @@ -1,0 +1,1 @@ 1 +en - Content
-
... ... @@ -1,0 +1,26 @@ 1 +Record how long XWiki's major components spend on each request, by turning on the Monitor plugin and letting it write its measurements to [[the log>>doc:documentation.xs.admin.logging.file-locations.WebHome]]. 2 + 3 +1. Check that the plugin is in the plugin list of ##WEB-INF/xwiki.cfg##. It is in the list XWiki ships, so this is normally already done.((( 4 +{{code language="none"}} 5 +xwiki.plugins=\ 6 + [...] 7 + com.xpn.xwiki.monitor.api.MonitorPlugin 8 +{{/code}} 9 +))) 10 +1. Turn the plugin on in the same file. The setting is shipped commented out and defaults to off, so the plugin is loaded but measures nothing until you do this. ##xwiki.monitor.lastlistsize## decides how many recent requests it keeps, and defaults to 20.((( 11 +{{code language="none"}} 12 +xwiki.monitor=1 13 +{{/code}} 14 +))) 15 +1. Raise the plugin's logger to ##debug##, since that is the level it writes its measurements at. Apply it in the Logback configuration file, as described in [[Configure Log Levels>>doc:documentation.xs.admin.logging.configure-levels.WebHome]].((( 16 +{{code language="xml"}} 17 +<logger name="com.xpn.xwiki.monitor" level="debug"/> 18 +{{/code}} 19 +))) 20 +1. Restart the servlet container, since both changes are read at start-up. 21 +1. Browse the wiki and read the log. Each request now produces a ##MONITOR## record with its total duration, followed by one record per timer with the time spent there and the number of calls.((( 22 +{{code language="none"}} 23 +2026-11-10 16:12:51,830 [qtp927327686-166] DEBUG c.x.x.m.a.MonitorData - MONITOR page [Sandbox.WebHome]: [243]ms 24 +2026-11-10 16:12:51,830 [qtp927327686-166] DEBUG c.x.x.m.a.MonitorData - MONITOR page [Sandbox.WebHome], action [view], timer [hibernate]: [86]ms in [14] calls 25 +{{/code}} 26 +)))
- DocApp.Code.DocumentationClass[0]
-
- FAQ
-
... ... @@ -1,0 +1,11 @@ 1 +== Does it slow the wiki down? == 2 + 3 +A little. The shipped ##xwiki.cfg## describes disabling it as worth a minor gain in performance and memory, which is why it is off by default. Turn it on to investigate, not to leave it on. 4 + 5 +== Why is the log silent after turning it on? == 6 + 7 +Because the plugin logs at ##debug##, below the ##warn## the root logger sits at. Step 3 is what makes its records visible; without it the plugin measures and nothing is written. 8 + 9 +== Can I read the measurements without the log? == 10 + 11 +Yes. XWiki ships a hidden page at ##/bin/view/XWiki/RequestsStatus## that shows the requests being served, a consolidated duration per timer and the most recent requests. It is empty until the plugin is active, and nothing in the user interface links to it. - Related
-
... ... @@ -1,0 +1,2 @@ 1 +* [[Performance>>doc:documentation.xs.admin.performance.WebHome]] 2 +* [[Configure Log Levels>>doc:documentation.xs.admin.logging.configure-levels.WebHome]] - Target
-
... ... @@ -1,0 +1,1 @@ 1 +administrator - Type
-
... ... @@ -1,0 +1,1 @@ 1 +howto
- DocApp.Code.DocumentationExtensionClass[0]
-
- Technical Identifier
-
... ... @@ -1,0 +1,1 @@ 1 +xwiki:org.xwiki.platform:xwiki-platform-logging-ui
Summary
-
Page properties (3 modified, 0 added, 0 removed)
-
Objects (1 modified, 0 added, 0 removed)
Details
- Page properties
-
- Author
-
... ... @@ -1,1 +1,1 @@ 1 -XWiki. VincentMassol1 +XWiki.elenicojocariu - Default language
-
... ... @@ -1,0 +1,1 @@ 1 +en - Content
-
... ... @@ -58,5 +58,5 @@ 58 58 59 59 == Changing the Logging Configuration == 60 60 61 -* To change log levels on a running instance, use the Logging Application of the wiki administration, as described in [[Log ging>>doc:Documentation.AdminGuide.Logging]]. Such changes apply immediately, but they are lost when the container is restarted.61 +* To change log levels on a running instance, use the Logging Application of the wiki administration, as described in [[Change Log Levels at Runtime>>doc:documentation.xs.admin.logging.change-levels-runtime.WebHome]]. Such changes apply immediately, but they are lost when the container is restarted. 62 62 * To change the logging configuration permanently, including the log levels, the rotation policy and the destinations, override the ##logback.xml## configuration file as described in [[Custom Configuration Files in Docker>>doc:documentation.xs.admin.installation.methods.install-xwiki-docker.configuration.configuration-files.custom-configuration-files.WebHome]].
- DocApp.Code.DocumentationClass[0]
-
- Related
-
... ... @@ -1,4 +1,4 @@ 1 1 * [[Configuration Files in the XWiki Docker Image>>doc:documentation.xs.admin.installation.methods.install-xwiki-docker.configuration.configuration-files.WebHome]]. 2 2 * [[Custom Configuration Files in Docker>>doc:documentation.xs.admin.installation.methods.install-xwiki-docker.configuration.configuration-files.custom-configuration-files.WebHome]]. 3 3 * [[Docker Volumes Used by XWiki Containers>>doc:documentation.xs.admin.installation.methods.install-xwiki-docker.configuration.volumes.WebHome]]. 4 -* [[Logging>>doc: Documentation.AdminGuide.Logging]].4 +* [[Logging>>doc:documentation.xs.admin.logging.WebHome]].
Summary
-
Page properties (1 modified, 0 added, 0 removed)
Details
- Page properties
-
- Content
-
... ... @@ -20,7 +20,7 @@ 20 20 {{/code}} 21 21 ))) 22 22 1. Copy whatever else you added around the wiki: the JDBC driver and any other jar in ##WEB-INF/lib##, any skin under ##skins##, and the servlet container's own configuration and TLS keystore if you changed them. Archiving the whole web application directory is the way not to forget one of them. 23 -1. Copy the log files, if you want to be able to read afterwards what the instance was doing. They go wherever the [[logging configuration>>xwiki: Documentation.AdminGuide.Logging]] sends them, by default the console output of the servlet container.23 +1. Copy the log files, if you want to be able to read afterwards what the instance was doing. They go wherever the [[logging configuration>>xwiki:documentation.xs.admin.logging.WebHome]] sends them, by default the console output of the servlet container. 24 24 1. Start the servlet container again. 25 25 1. Check that the backup holds one file per part:((( 26 26 {{code language="none"}}
Summary
-
Page properties (1 modified, 0 added, 0 removed)
Details
- Page properties
-
- Content
-
... ... @@ -13,6 +13,6 @@ 13 13 1. Click the "Restore" button, or "Cancel" the action.((( 14 14 {{image reference="restore-single-page.png" size="extra" alt="The restore popup when the batch has a single Page"/}} 15 15 ))) 16 -1. View the status of your restore, and check the [[Job Log>>xwiki: Documentation.AdminGuide.Logging||anchor="HJobLogs"]] if you are an [[advanced user>>xwiki:documentation.xs.user.base.page.edit.simple-advanced.WebHome||anchor="HAdvancedMode"]].(((16 +1. View the status of your restore, and check the [[Job Log>>xwiki:documentation.xs.admin.logging.file-locations.WebHome||anchor="HJobLogs"]] if you are an [[advanced user>>xwiki:documentation.xs.user.base.page.edit.simple-advanced.WebHome||anchor="HAdvancedMode"]].((( 17 17 {{image reference="job-log.png" size="large" alt="The Job Log showing the status of the restore"/}} 18 18 )))
Summary
-
Page properties (2 modified, 0 added, 0 removed)
Details
- Page properties
-
- Default language
-
... ... @@ -1,0 +1,1 @@ 1 +en - Content
-
... ... @@ -7,7 +7,7 @@ 7 7 |##xwiki.store.cache.capacity##|##500##|How many documents that cache holds.|Below the number of documents a wiki actually serves, reads fall through to the database; above it, the extra entries only cost memory. 8 8 |##xwiki.store.cache.pageexistcapacity##|##10000##|How many entries the cache of "does this document exist" holds.|Little: the entries are booleans, so this cache can be large without costing much memory. 9 9 |##xwiki.backlinks##|##1##|Records, on every save, which pages link to which.|The list of pages linking to a page, everywhere it is used. Saving a document costs noticeably less without it, loading one slightly less. 10 -|##xwiki.monitor##|## 1##|Collects per-request statistics through the Monitor plugin.|Thestatisticsthemselves.The calls are spread through the code, soswitchingitoffsavesa little memory and a great many method calls.10 +|##xwiki.monitor##|##0##|Collects per-request statistics through the Monitor plugin, as described in [[Monitor Component Execution Times>>doc:documentation.xs.admin.logging.monitor-execution-times.WebHome]].|Performance, if you turn it on: the calls are spread through the code, so they cost a little memory and a great many method calls in exchange for the statistics. 11 11 |##xwiki.monitor.lastlistsize##|##20##|How many recent requests the Monitor plugin remembers.|Depth of history in those statistics. 12 12 |##xwiki.store.hibernate.custommapping##|##1##|Allows an XClass to be stored in a table of its own instead of the generic schema.|The faster queries custom mapping gives a wiki holding large numbers of objects of one class. See [[Custom Mapping>>Documentation.DevGuide.Tutorials.CustomMapping.WebHome]]. 13 13