Manual:How to debug

This page gives a basic introduction to debugging MediaWiki software.

One of the first things you will notice is that "echo" generally does not work; this is part of the general design. As this is one of the easiest (and arguably best) tools for debugging, there must be another way.

Setting up Debugging
The first thing you need to do is copy the global variable $wgDebugLogFile from the "/includes/DefaultSettings.php" file, to the "LocalSettings.php" file, and name a text file where you want to debug trace output to be put, e.g.:

/** * The debug log file should be not be publicly accessible if it is used, as it  * may contain private data. But it must be in a directory to which PHP run * within your Web server can write. */ $wgDebugLogFile = 'c:/Program Files/Apache Group/htdocs/mediawiki/debug_log.txt';

There are many debug values set in DefaultSettings.php that you can override in LocalSettings.php, e.g.:

$wgShowSQLErrors = true; $wgDebugDumpSql = true;

In order to profile, you need to copy profiling/debugging constants to the LocalSettings.php file, e.g.: # # /** Enable for more detailed by-function times in debug log */ $wgProfiling   = true; /** Only record profiling info for pages that took longer than this */ $wgProfileLimit = 0.0; /** Don't put non-profiling info into log file */ $wgProfileOnly = false; /** Log sums from profiling into "profiling" table in db. */ $wgProfileToDatabase = false; /** Only profile every n requests when profiling is turned on */ $wgProfileSampleRate = 1; /** If true, print a raw call tree instead of per-function report */ $wgProfileCallTree = false; /** If not empty, specifies profiler type to load */ $wgProfilerType = '' ; /** Settings for UDP profiler */ $wgUDPProfilerHost = '127.0.0.1'; $wgUDPProfilerPort = '3811'; /** Detects non-matching wfProfileIn/wfProfileOut calls */ $wgDebugProfiling = true; /** Output debug message on every wfProfileIn/wfProfileOut */ $wgDebugFunctionEntry = 1; /** Lots of debugging output from SquidUpdate.php */ $wgDebugSquid = false;
 * 1) Profiling / debugging

Setting $wgProfiling will give you basic page timing in $wgDebugLogFile. For more advanced intra-page profiling, you must modify StartProfiler.php.

NOTE: In mediawiki-1.8.2 (have not checked others), $wgProfilerType is not used at all. You will have to change StartProfiler.php to enable desired profiler. Look in that file for more details.

Tracing execution
Once you've set up your variables as above, you can call the global function wfDebug from wherever in the code you like. The function is found in the "includes/GlobalFunctions.php" file

e.g.

wfDebug("This is just testing the debug tracing stuff\n");

Then in the log file you would see: This is just testing the debug tracing stuff

Profiling
Modify StartProfiler.php to load a more advanced profiler.

Then, wrap any function that you want to investigate as a bottleneck in the following code:

At beginning: $fname = 'class_name_if_applicable::function name'; # Just for display wfProfileIn($fname);

At end: wfProfileOut($fname);

In the log file you will see profiling info. Change $wgProfileCallTreein LocalSettings.php to true or false for different display formats.

Logging to Database
To log profiling to a database, first you'll have to create a profiling table in your MediaWiki database using the command in the file maintenance/archives/patch-profiling.sql , and set $wgProfileToDatabase = true in LocalSettings.php

Now go visit some pages (or let your users do so).

Viewing Profile Info
The page profileinfo.php in the MediaWiki root prints profile info from the profiling table. To run it, set $wgEnableProfileInfo = true; in AdminSettings.php. Then, after gathering enough data, visit profileinfo.php to see how much time your profiled code is using and how many times it's being called.