Debugging

Debugging

There are several possibilities for debugging XWiki:

Debugging XWiki from your IDE

Debugging with Eclipse

Once you've gotten the debugger working, you'll wonder how you ever survived without it.

Complete tutorial based on M2Eclipse

Debug XWiki with Eclipse

Debug a XWiki released version

• Follow the steps in under Building In Eclipse including the optional "Import the WAR as a web project".
• Select from the Eclipse menu Run > Debug...
• Create a new configuration for your server
• Hit the Debug button
• Set breakpoints, step through code, have fun!

If you are working on an XWiki plugin in a separate project in your workspace, you can ensure it is automatically deployed to XWiki's WEB-INF/lib directory when debugging. Open the project properties of the XWiki project resulting from the WAR import above, go to the J2EE Module Dependencies section, and add your plugin project.

Remote Debugging

To perform remote debugging, start you wiki in debug mode. To do this modify the way you start your container and ensure that the following JVM parameters are passed:

-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005

For example, for Jetty you could use the following start script:

#!/bin/sh

JETTY_HOME=.
JETTY_PORT=8080
JAVA_OPTS="-Xmx300m -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005"

java $JAVA_OPTS -Dfile.encoding=iso-8859-1 -Djetty.port=$JETTY_PORT -Djetty.home=$JETTY_HOME -jar $JETTY_HOME/start.jar

If you are using the Tomcat service on Windows, you should modify the JVM args with the Tomcat Service Configuration Panel. Select the Java tab and add each of the options on a separate line. For example:

-Dcatalina.home=C:\\\Program Files\\\Apache Software Foundation\\\Tomcat 5.5
-Dcatalina.base=C:\\\Program Files\\\Apache Software Foundation\\\Tomcat 5.5
-Djava.endorsed.dirs=C:\\\Program Files\\\Apache Software Foundation\\\Tomcat 5.5\\\common\\\endorsed
-Djava.io.tmpdir=C:\\\Program Files\\\Apache Software Foundation\\\Tomcat 5.5\\\temp
-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
-Djava.util.logging.config.file=C:\\\Program Files\\\Apache Software Foundation\\\Tomcat 5.5\\\conf\\\logging.properties
-Xdebug
-Xnoagent
-Djava.compiler=NONE  
-Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n

Then, in your favorite IDE, open the XWiki project and run a remote debugging session, attached to the socket on port 5005. For example, using IntelliJ IDEA, go to Run|Edit Configurations... and create a new Remote configuration (default parameters should be fine). Then execute it and IDEA will connect to the executing JVM.

You can then place breakpoints in your source code.

Logging

Turning on logging inside XWiki

See the Logging page in the Admin guide.

Logging calls at the database level

Turn on logging in your database to see all SQL queries executed against it.

Generating a debug version of XWiki

Our Maven2 build has support for running a Log Aspect against XWiki's core. This Log Aspect logs all method calls with parameters. This is useful, especially in the case when you cannot debug the application (for example when you cannot reproduce the problem on your machine you can send an "aspectified" XWiki JAR and ask the user to run it and send you the logs). Note that you'll need to ask the user to add the AspectJ Runtime JAR to his WEB-INF/lib directory too.

To generate the aspectified XWiki JAR, run mvn install -Pdebug in XWiki's Core module directory.

See the Profiling page for more details on how to use the Aspect.