Wiki source code of Logging

Last modified by Antoine Mottier on 2023/07/17

Hide last authors
Manuel Smeria 12.2 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
Silvia Macovei 4.1 4
Vincent Massol 16.1 5 XWiki uses [[SLF4J>>http://www.slf4j.org/]] for logging. By default XWiki is configured so that SLF4J uses [[Logback>>http://logback.qos.ch/]]. XWiki's Logback configuration is located in the ##[[WEB-INF/classes/logback.xml>>https://raw.github.com/xwiki/xwiki-platform/master/xwiki-platform-core/xwiki-platform-web/src/main/resources/logback.xml]]## file.
Vincent Massol 1.1 6
Manuel Smeria 12.2 7 XWiki is also configured by default so that any logs generated by 3rd part JARs used by XWiki (i.e. in the XWiki classpath at runtime) will automatically find their ways to the output defined by the Logback configuration file. This is active for Apache Commons Logging (JCL) and Log4J. This is achieved by using [[a SLF4J Bridge>>http://www.slf4j.org/legacy.html]] for both logging frameworks (it's the ##log4j-over-slf4j-*.jar## and ##jcl-over-slf4j-*.jar## files that provide this feature).
Vincent Massol 11.1 8
Vincent Massol 21.1 9 = Log Location =
Vincent Massol 1.4 10
Vincent Massol 22.1 11 == Main Logs ==
12
Vincent Massol 21.1 13 By default XWiki is configured to log everything on the console only. Whether the console is captured by your Servlet Container or not depends on the container you use.
14
Jean-Sébastien Dennebouy 23.1 15 Here are some potential locations you can check, depending on the [[installation method>>xwiki:Documentation.AdminGuide.Installation.WebHome#HInstallationMethods]] you've chosen::
16
17 * If you use the [[XWiki Debian packaging>>xwiki:Documentation.AdminGuide.Installation.InstallationViaAPT.WebHome]], and thus using Tomcat, it's in ##/var/log/tomcat*/catalina.out##
18 ** Recent Tomcat packages use service logs, visible using the command ##journalctl -u tomcat9.service##
Vincent Massol 21.1 19 * If you use the [[XWiki Docker packaging>>https://github.com/xwiki-contrib/docker-xwiki/blob/master/README.md]] it's in the console that started Tomcat, or if you started it in background, you can get them with ##docker logs <container id>##.
20 * If you use the [[XWiki Standalone packaging>>Documentation.AdminGuide.InstallationStandalone]], then it's in the console and also in ##data/logs/<date>.output.log##.
21 * If you use the [[Manual WAR packaging>>Documentation.AdminGuide.InstallationWAR]], then it depends on the Servlet engine you've used and how you've configured it. You could check in ##/var/log/tomcat*/catalina.out## on unix or ##<tomcat home>/logs/catalina.out## for Tomcat.
22
Vincent Massol 22.1 23 == Job Logs ==
24
25 XWiki has the concept of [[jobs>>extensions:Extension.Job Module.WebHome]] (e.g. when you install or upgrade an Extension or when you delete pages, they all execute in a job). Very often, jobs capture the logs and output them in job log files located in the [[permanent directory>>Documentation.AdminGuide.Configuration.WebHome#HPermanentDirectory]], under the ##jobs## subdirectories. Log files are named ##log.xml##.
26
27 Note that some features allow you to see view these logs in the UI. For exampe the Extension Manager has a UI so that you can [[review the logs when an extension was installed, or updated>>extensions:Extension.Extension Manager Application#HProgressLog]].
28
Vincent Massol 16.1 29 = Configuring Logging =
Vincent Massol 1.1 30
Vincent Massol 14.1 31 There are various ways in which you can configure what to log.
32
Vincent Massol 17.2 33 See also the [[Logging section of the Debugging page>>dev:Community.Debugging#HLogging]] for specific details on some loggers.
Vincent Massol 17.1 34
Anca Luca 20.1 35 {{info}}
36 Of the 3 methods proposed under, only the Manual method is persistent **after a server restart**. So if your server might restart/be restarted and you want the log configuration to be kept after this restart, the only method is adding them to logback.xml.
37 {{/info}}
Anca Luca 18.1 38
Vincent Massol 16.1 39 == Manually ==
Vincent Massol 13.1 40
Anca Luca 20.1 41 Simply edit the Logback configuration file (##logback.xml## in ##WEB-INF/classes## in your web application folder) and restart the Servlet container for it to take effect.
Vincent Massol 13.1 42
Vincent Massol 16.1 43 == Using the Log Application ==
Vincent Massol 13.1 44
45 Starting with XWiki 4.2 a new [[Logging Application>>extensions:Extension.Logging Application]] is available in your wiki's administration UI and you can use it to configure the log levels for all features.
46
Anca Luca 20.1 47 == Using JMX ==
Vincent Massol 13.1 48
Antoine Mottier 24.1 49 Since XWiki 14.8 Logback no longer support JMX so you won't be able to use JMX to update your logging configuration.
50
Manuel Smeria 12.2 51 [[LogBack exposes its configuration with JMX>>http://logback.qos.ch/manual/jmxConfig.html]] making it possible to use a JMX console to modify the logging configuration at runtime, thus not needing to restart the Servlet container. This is very useful in production when needing to debug an issue.
Vincent Massol 8.1 52
Ecaterina Moraru (Valica) 20.4 53 See the [[Monitoring Guide>>Documentation.AdminGuide.Monitoring]] for more details on using JMX with XWiki.
Vincent Massol 8.1 54
Vincent Massol 16.1 55 = Analyzing logs with Lilith =
Vincent Massol 9.1 56
57 [[Lilith>>http://lilith.huxhorn.de/]] is a logging and access event viewer. It makes it easy to analyze large quantities of logs. To use it, configure XWiki's Logging to send events to the Socket appender. Add the following to the ##logback.xml## file:
58
59 {{code language="xml"}}
60 ...
61 <appender name="socket" class="ch.qos.logback.classic.net.SocketAppender">
62 <RemoteHost>localhost</RemoteHost>
63 <Port>4560</Port>
64 <ReconnectionDelay>170</ReconnectionDelay>
65 <IncludeCallerData>true</IncludeCallerData>
66 </appender>
67 ...
68 {{/code}}
69
70 And add the new appender to the list of appenders to use. For example:
71
72 {{code language="xml"}}
73 ...
74 <root level="warn">
Jean-Sébastien Dennebouy 23.1 75 <appender-ref ref="stdout"></appender-ref>
76 <appender-ref ref="socket"></appender-ref>
Vincent Massol 9.1 77 </root>
78 ...
79 {{/code}}
80
81 Open Lilith (it's a desktop application) and it'll automatically listen on port 4560 so when you start XE you'll see its logs show up in Lilith.
82
83 For example:
84
Jean-Sébastien Dennebouy 23.1 85 [[image:lilith.png||width="950"]]
Vincent Massol 9.1 86
Vincent Massol 11.1 87 == Using a different SLF4J implementation ==
88
Thomas Mortagne 15.1 89 If you wish, for example, to use Log4J to log all logs produced by XWiki you can do so by doing the following ([[described in the SLF4J manual>>http://www.slf4j.org/manual.html]]):
Anca Luca 20.1 90
Manuel Smeria 12.2 91 * Remove the Logback SLF4J implementation from the classpath by removing ##WEB-INF/lib/logback-classic-*.jar## and ##WEB-INF/lib/logback-core-*.jar##
92 * Remove the Log4J over SLF4J JAR from the classpath by removing ##WEB-INF/lib/log4j-over-slf4j-*.jar##
Vincent Massol 11.2 93 * Add the Log4J SLF4J implementation to the classpath: ##slf4j-log4j*-*.jar##
94 * Add Log4J itself to the classpath
Vincent Massol 11.1 95
Vincent Massol 16.1 96 = Older XWiki versions =
Vincent Massol 8.1 97
Vincent Massol 16.1 98 XWiki versions 3.0 and older use Commons Logging for logging. By default XWiki was configured so that Commons Logging was using log4J. XWiki's Log4J configuration was located inside XWiki's JAR (xwiki-core-x.y.jar), in a ##[[log4j.properties>>https://raw.github.com/xwiki/xwiki-platform/13e01088e74c170452088a56fe54fb76a7ecb041/xwiki-platform-core/xwiki-platform-oldcore/src/main/resources/log4j.properties]]## file. XWiki' JAR is itself located in your ##WEB-INF/lib/## directory.
Vincent Massol 8.1 99
100 {{info}}
Vincent Massol 16.1 101 By default XWiki was configured to log everything on the console only.
Vincent Massol 8.1 102 {{/info}}
103
104 == Using a custom Log4J configuration ==
105
Vincent Massol 16.1 106 The best solution was to create a new ##log4j.properties## file in your ##WEB-INF/classes## directory. It'll thus override the one from the XWiki JAR. As an example, here's a sample configuration:
Vincent Massol 1.1 107
Silvia Macovei 4.1 108 {{code language="none"}}
Vincent Massol 1.6 109 ### Direct log messages to stdout
Vincent Massol 1.1 110 log4j.appender.stdout=org.apache.log4j.ConsoleAppender
111 log4j.appender.stdout.Target=System.out
112 log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
Vincent Massol 3.3 113 log4j.appender.stdout.layout.ConversionPattern=%d [%X{url}] [%t] %-5p %-30.30c{2} %x - %m %n
Vincent Massol 1.1 114
Vincent Massol 1.6 115 ### By default everything that is of warning or severity WARN, ERROR or FATAL is logged both to
116 ### the console and to the xwiki.log file.
Jerome 6.1 117 log4j.rootLogger=warn, stdout
Vincent Massol 1.1 118
Vincent Massol 1.6 119 ### Hibernate logging options
Vincent Massol 1.1 120 log4j.logger.org.hibernate=warn
121 log4j.logger.org.hibernate.SQL=warn
122 log4j.logger.org.hibernate.type=warn
123 log4j.logger.org.hibernate.ps.PreparedStatementCache=warn
124
Vincent Massol 1.6 125 ### XWiki logging configuration
Vincent Massol 3.3 126 log4j.logger.org.xwiki=info
Vincent Massol 1.1 127 log4j.logger.com.xpn.xwiki=warn
128 log4j.logger.com.xpn.xwiki.render.XWikiRadeoxRenderEngine=warn
Vincent Massol 2.1 129 log4j.logger.com.xpn.xwiki.store.migration=info
Vincent Massol 1.1 130
Vincent Massol 2.1 131 ### Deactive Struts warnings
Vincent Massol 1.1 132 log4j.logger.org.apache.struts.util.RequestUtils=error
133
Vincent Massol 1.6 134 ### Deactivate JGroups warnings
Vincent Massol 1.1 135 log4j.logger.org.jgroups=error
Vincent Massol 2.1 136
137 ## Deactive PDF Export CSS Applier warnings
138 log4j.logger.info.informatica.doc.style.css.dom=error
139 log4j.logger.org.apache.fop.layoutmgr.inline.ContentLayoutManager=error
Silvia Macovei 4.1 140 {{/code}}
Vincent Massol 1.1 141
142 Refer to Log4J's documentation to understand the settings. As an example, to turn on Hibernate's calls, just set the following:
143
Silvia Macovei 4.1 144 {{code}}
Vincent Massol 1.1 145 log4j.logger.org.hibernate.SQL=debug
Silvia Macovei 4.1 146 {{/code}}
Vincent Massol 1.1 147
Vincent Massol 8.1 148 = Activating the XWiki Monitoring feature =
Vincent Massol 3.1 149
Silvia Macovei 4.1 150 {{info}}
151 The monitoring feature is already active in the default configuration.
152 {{/info}}
Vincent Massol 3.1 153
154 XWiki has a feature to monitor times spent in its major components. To activate it, you need to:
155
Anca Luca 20.1 156 * Enable the Monitor plugin by adding/modifying the following plugin definition in the ##xwiki.cfg## configuration file:(((
Silvia Macovei 4.1 157 {{code language="none"}}
Vincent Massol 3.1 158 xwiki.plugins=\
159 [...]
160 com.xpn.xwiki.monitor.api.MonitorPlugin
Silvia Macovei 4.1 161 {{/code}}
Manuel Smeria 12.2 162 )))
Anca Luca 20.1 163 * Enable it by adding/modifying the following in the ##xwiki.cfg## configuration file:(((
Silvia Macovei 4.1 164 {{code language="none"}}
Vincent Massol 3.1 165 xwiki.monitor=1
Silvia Macovei 4.1 166 {{/code}}
Manuel Smeria 12.2 167 )))
Anca Luca 20.1 168 * Since the plugin logs everything under the ##DEBUG## severity you also need to configure the XWiki Logging (as described above) by setting the ##com.xpn.xwiki.monitor## category to the ##DEBUG## level.(((
Vincent Massol 8.1 169 For example for Logback it means adding the following in ##logback.xml##:
170
Silvia Macovei 4.1 171 {{code language="none"}}
Jean-Sébastien Dennebouy 23.1 172 <logger name="com.xpn.xwiki.monitor" level="debug"></logger>
Vincent Massol 8.1 173 {{/code}}
174
175 And for older XWiki versions using Log4J it means adding the following in ##log4j.properties##:
176
177 {{code language="none"}}
Vincent Massol 3.1 178 log4j.logger.com.xpn.xwiki.monitor=debug
Silvia Macovei 4.1 179 {{/code}}
Vincent Massol 8.1 180 )))

Get Connected