Debugging: Difference between revisions
Tim Bahula 2 (talk | contribs) m (→Debug SQL queries: clean up, typos fixed: techncially → technically) |
|||
(10 intermediate revisions by 8 users not shown) | |||
Line 1: | Line 1: | ||
{{Developer tools}} | {{Developer tools}} | ||
==Using debugging messages== | ==Using debugging messages== | ||
Debugging messages are intended to help diagnose problems and/or help Moodle developers. If you have a problem with your Moodle site and ask for help in a Moodle.org forum, a developer may ask you to turn enable debugging i.e. turn debugging messages on, in order to locate the cause of the problem. If you are having problems such as a blank screen or incomplete screens, then turning on debugging is usually the first thing to try. | Debugging messages are intended to help diagnose problems and/or help Moodle developers. If you have a problem with your Moodle site and ask for help in a Moodle.org forum, a developer may ask you to turn enable debugging i.e. turn debugging messages on, in order to locate the cause of the problem. If you are having problems such as a blank screen or incomplete screens, then turning on debugging is usually the first thing to try. | ||
==Enabling debugging== | ==Enabling debugging== | ||
To enable debugging, go to ''Site administration > Development > Debugging'' . | |||
To enable debugging, go to ''Site administration > Development > Debugging | |||
===Debug messages=== | ===Debug messages=== | ||
The options are: | The options are: | ||
* NONE: Do not show any errors or warnings (Default) | * NONE: Do not show any errors or warnings (Default) | ||
* MINIMAL: Show only fatal errors | * MINIMAL: Show only fatal errors | ||
Line 17: | Line 11: | ||
* ALL: Show all reasonable PHP debug messages | * ALL: Show all reasonable PHP debug messages | ||
* DEVELOPER: extra Moodle debug messages for developers | * DEVELOPER: extra Moodle debug messages for developers | ||
Notes: | Notes: | ||
# It is recommended that a record of error messages is kept, and for the admin to regularly monitor the error logs. This may be done by setting 'Debug messages' (debug) to Normal and leaving 'Display debug messages' (debugdisplay) off (unticked). Error messages are then recorded in the server logs. | # It is recommended that a record of error messages is kept, and for the admin to regularly monitor the error logs. This may be done by setting 'Debug messages' (debug) to Normal and leaving 'Display debug messages' (debugdisplay) off (unticked). Error messages are then recorded in the server logs. | ||
# If 'Debug messages' is set to Developer on a production (public) site, it is recommended to copy and paste the debugging message obtained and then turn off Developer debugging. This is because debugging messages can give clues to a hacker as to the set-up of your site. | # If 'Debug messages' is set to Developer on a production (public) site, it is recommended to copy and paste the debugging message obtained and then turn off Developer debugging. This is because debugging messages can give clues to a hacker as to the set-up of your site. | ||
===Display debug messages=== | ===Display debug messages=== | ||
If you select this checkbox, the debug messages are displayed directly in the browser, otherwise they are stored in the server logs. | If you select this checkbox, the debug messages are displayed directly in the browser, otherwise they are stored in the server logs. | ||
===Debug | ==== Debug outgoing mail (SMTP) ==== | ||
You can use the config.php file to turn on more "tools" which will assist you with debugging the outgoing emails (and SMTP server configuration): | |||
You can | |||
* Redirect all outgoing emails to a specific address: | * Redirect all outgoing emails to a specific address: | ||
< | <syntaxhighlight lang="php"> | ||
// Divert all outgoing emails to this address to test and debug emailing features | // Divert all outgoing emails to this address to test and debug emailing features | ||
// $CFG->divertallemailsto = 'root@localhost.local'; // NOT FOR PRODUCTION SERVERS! | // $CFG->divertallemailsto = 'root@localhost.local'; // NOT FOR PRODUCTION SERVERS! | ||
</ | </syntaxhighlight> | ||
* Turn on the CRON debugging and run CLI cron.php script. | * Turn on the CRON debugging and run CLI cron.php script. | ||
< | <syntaxhighlight lang="php"> | ||
// Force developer level debug and add debug info to the output of cron | // Force developer level debug and add debug info to the output of cron | ||
// $CFG->showcrondebugging = true; | // $CFG->showcrondebugging = true; | ||
</ | </syntaxhighlight> | ||
And then use SSH (or putty.exe, on windows) to run: | And then use SSH (or putty.exe, on windows) to run: | ||
< | <syntaxhighlight lang="php"> | ||
you@moodle-server(/var/www/html/moodle)# php admin/cli/cron.php | you@moodle-server(/var/www/html/moodle)# php admin/cli/cron.php | ||
</ | </syntaxhighlight> | ||
* Turn on verbose SMTP debugging and output it into system's error_log (code hack): | * Turn on verbose SMTP debugging and output it into system's error_log (code hack): | ||
As [https://moodle.org/mod/forum/discuss.php?d=316222#p1289850 suggested] on Moodle's discussion forums: | As [https://moodle.org/mod/forum/discuss.php?d=316222#p1289850 suggested] on Moodle's discussion forums: | ||
Open [https://github.com/moodle/moodle/blob/master/lib/moodlelib.php#L5379 lib/moodlelib.php L5379] and change it to: | Open [https://github.com/moodle/moodle/blob/master/lib/moodlelib.php#L5379 lib/moodlelib.php L5379] and change it to: | ||
< | <syntaxhighlight lang="php"> | ||
if (!empty($CFG->debugsmtp)) { | if (!empty($CFG->debugsmtp)) { | ||
$mailer->SMTPDebug = 1; // 0 - no debug ... 4 - low level full debug | $mailer->SMTPDebug = 1; // 0 - no debug ... 4 - low level full debug | ||
$mailer->Debugoutput = "error_log"; | $mailer->Debugoutput = "error_log"; | ||
} | } | ||
</ | </syntaxhighlight> | ||
See more info about [https://github.com/moodle/moodle/blob/master/lib/phpmailer/class.phpmailer.php#L314 SMTPDebug] parameters & [https://github.com/moodle/moodle/blob/master/lib/phpmailer/class.phpmailer.php#L328 Debugoutput] parameters, | See more info about [https://github.com/moodle/moodle/blob/master/lib/phpmailer/class.phpmailer.php#L314 SMTPDebug] parameters & [https://github.com/moodle/moodle/blob/master/lib/phpmailer/class.phpmailer.php#L328 Debugoutput] parameters, | ||
Set-up mailcatcher (https://mailcatcher.me/). | Set-up mailcatcher (https://mailcatcher.me/). | ||
===Performance info=== | ===Performance info=== | ||
The Performance info option determines whether performance info will be included in the footer of the standard theme (and some other themes). Performance info includes the time for the page to load, the amount of memory used to generate the page, cpu usage, load, and the record cache hit/miss ration. | The Performance info option determines whether performance info will be included in the footer of the standard theme (and some other themes). Performance info includes the time for the page to load, the amount of memory used to generate the page, cpu usage, load, and the record cache hit/miss ration. | ||
If you add | If you add | ||
< | <syntaxhighlight lang="php"> | ||
define('MDL_PERF', true); | define('MDL_PERF', true); | ||
define('MDL_PERFDB', true); | define('MDL_PERFDB', true); | ||
define('MDL_PERFTOLOG', true); | define('MDL_PERFTOLOG', true); | ||
define('MDL_PERFTOFOOT', true); | define('MDL_PERFTOFOOT', true); | ||
</ | </syntaxhighlight> | ||
to your config.php file, then it will also count database queries. (This has to be in config.php, because Moodle starts doing DB queries before it loads the config information in the database!) | to your config.php file, then it will also count database queries. (This has to be in config.php, because Moodle starts doing DB queries before it loads the config information in the database!) | ||
To hide performance info from ordinary users, see the discussion [https://moodle.org/mod/forum/discuss.php?d=358032 Performance info only for admins?] | To hide performance info from ordinary users, see the discussion [https://moodle.org/mod/forum/discuss.php?d=358032 Performance info only for admins?] | ||
===Show origin of languages strings=== | ===Show origin of languages strings=== | ||
Helps with [[:dev:Translation|translation]] and also with [[Language customization]]. Sometimes <code>?strings=1</code> should be added; other times <code>&strings=1</code>. See the Wikipedia article [http://en.wikipedia.org/wiki/Query_string Query string] for details. | Helps with [[:dev:Translation|translation]] and also with [[Language customization]]. Sometimes <code>?strings=1</code> should be added; other times <code>&strings=1</code>. See the Wikipedia article [http://en.wikipedia.org/wiki/Query_string Query string] for details. | ||
=== Show origin of SQL calls === | |||
If you turn this on, then for every bit of SQL send to the Database server, an SQL comment is added with all or part of the PHP stack trace. That means that if something happens which causes the query to be logged by the database (e.g. and error, or a slow query) you can find where in Moodle that query came from. | |||
===Show validator links=== | ===Show validator links=== | ||
Be careful, read the warning. | Be careful, read the warning. | ||
===Show page information=== | ===Show page information=== | ||
To show page information printed in the page footer. | To show page information printed in the page footer. | ||
===Show template information=== | |||
To show templates used for rendering as comments in the page HTML. After changing the setting, you need to purge caches for the change to take effect. | |||
Example of how the templates are shown in the page HTML source:<syntaxhighlight lang="html"> | |||
<!-- template(PHP): core/pix_icon_fontawesome --> | |||
<i class="icon fa fa-window-close fa-fw " aria-hidden="true"></i> | |||
<!-- /template(PHP): core/pix_icon_fontawesome --> | |||
</syntaxhighlight>It is important to note the added comments can interfere with some scripts and can even break core functionality! | |||
===Debug SQL queries=== | ===Debug SQL queries=== | ||
You can add (turn ON) any of the following dboptions in your config.php files, which log different types of SQL queries into | You can add (turn ON) any of the following dboptions in your config.php files, which log different types of SQL queries into mdl_log_queries table: | ||
* '''logall''' - log all queries - suitable only for developers, causes high server loads and NOT recommended for production. | * '''logall''' - log all queries - suitable only for developers, causes high server loads and NOT recommended for production. | ||
* '''logslow''' - log queries that take longer than specified number of seconds (float values are accepted). | * '''logslow''' - log queries that take longer than specified number of seconds (float values are accepted). | ||
* '''logerrors''' - log all error queries. | * '''logerrors''' - log all error queries. | ||
Full sample: | Full sample: | ||
< | <syntaxhighlight lang="php"> | ||
$CFG->dboptions = array ( | $CFG->dboptions = array ( | ||
//'logall' => true, | //'logall' => true, | ||
Line 99: | Line 87: | ||
'logerrors' => true, | 'logerrors' => true, | ||
); | ); | ||
</ | </syntaxhighlight>However, if you are in control of your Database server, your database probably has an option to log slow database queries in the database logs, and that is probably a technically better solution, if it is available to you. | ||
==What to do if you cannot get to the admin screens== | ==What to do if you cannot get to the admin screens== | ||
If the error is stopping you even getting to the admin screens to turn on debugging, then you can set the debugging setting manually. | If the error is stopping you even getting to the admin screens to turn on debugging, then you can set the debugging setting manually. | ||
===Try typing the URL directly=== | ===Try typing the URL directly=== | ||
The debug settings are at the URL <code><nowiki>http://.../admin/settings.php?section=debugging</nowiki></code> on your server. Sometimes that URL will work, even though the pages you need to go to get there (for example the site front page) do not. So it is worth trying to enter that URL directly. | The debug settings are at the URL <code><nowiki>http://.../admin/settings.php?section=debugging</nowiki></code> on your server. Sometimes that URL will work, even though the pages you need to go to get there (for example the site front page) do not. So it is worth trying to enter that URL directly. | ||
===In config.php=== | ===In config.php=== | ||
In [[Configuration file|config.php]] you can uncomment lines (delete the // at the start of the line) under Section 7 to enable debugging for all or just specific users: | In [[Configuration file|config.php]] you can uncomment lines (delete the // at the start of the line) under Section 7 to enable debugging for all or just specific users: | ||
<syntaxhighlight lang="php"> | |||
< | |||
//========================================================================= | //========================================================================= | ||
// 7. SETTINGS FOR DEVELOPMENT SERVERS - not intended for production use!!! | // 7. SETTINGS FOR DEVELOPMENT SERVERS - not intended for production use!!! | ||
Line 128: | Line 109: | ||
// for these users only. | // for these users only. | ||
// $CFG->debugusers = '2'; | // $CFG->debugusers = '2'; | ||
</ | </syntaxhighlight> | ||
Remember to comment those lines again (reinsert the // at the start of the line) when you have finished diagnosing your problem. | Remember to comment those lines again (reinsert the // at the start of the line) when you have finished diagnosing your problem. | ||
Line 135: | Line 115: | ||
'''NOTE 2''': if you find your config.php does not have the above settings (you have a cut down approx 30 lines config.php) look for a "config-dist.php" file that contains the full details. I would suggest transferring your details in the current config.php file you have into the full config file and renaming that one to "config.php". | '''NOTE 2''': if you find your config.php does not have the above settings (you have a cut down approx 30 lines config.php) look for a "config-dist.php" file that contains the full details. I would suggest transferring your details in the current config.php file you have into the full config file and renaming that one to "config.php". | ||
==See also== | ==See also== | ||
* If you are a developer looking for usage information on the <tt>debugging()</tt> statement, try lib/weblib.php for documentation on how it is used, and lib/setuplib.php for definitions of which PHP error levels the <tt>DEBUG_*</tt> flags map to. | |||
* Developers can also use [http://xdebug.org/ XDEBUG] (Installed as a module on the Apache server) to further dig into the code, step by step using an [http://xdebug.org/docs/remote XDEBUG client application]. Probably, as part of their favorite IDE. For example: [http://php.netbeans.org/ NetBeans], [http://www.jetbrains.com/phpstorm/ phpStorm] or... | |||
[[es:Depuración]] | [[es:Depuración]] | ||
[[fr:Débogage]] | [[fr:Débogage]] | ||
[[de:Debugging]] | [[de:Debugging]] |
Latest revision as of 16:43, 14 November 2024
Using debugging messages
Debugging messages are intended to help diagnose problems and/or help Moodle developers. If you have a problem with your Moodle site and ask for help in a Moodle.org forum, a developer may ask you to turn enable debugging i.e. turn debugging messages on, in order to locate the cause of the problem. If you are having problems such as a blank screen or incomplete screens, then turning on debugging is usually the first thing to try.
Enabling debugging
To enable debugging, go to Site administration > Development > Debugging .
Debug messages
The options are:
- NONE: Do not show any errors or warnings (Default)
- MINIMAL: Show only fatal errors
- NORMAL: Show warnings, errors and notices
- ALL: Show all reasonable PHP debug messages
- DEVELOPER: extra Moodle debug messages for developers
Notes:
- It is recommended that a record of error messages is kept, and for the admin to regularly monitor the error logs. This may be done by setting 'Debug messages' (debug) to Normal and leaving 'Display debug messages' (debugdisplay) off (unticked). Error messages are then recorded in the server logs.
- If 'Debug messages' is set to Developer on a production (public) site, it is recommended to copy and paste the debugging message obtained and then turn off Developer debugging. This is because debugging messages can give clues to a hacker as to the set-up of your site.
Display debug messages
If you select this checkbox, the debug messages are displayed directly in the browser, otherwise they are stored in the server logs.
Debug outgoing mail (SMTP)
You can use the config.php file to turn on more "tools" which will assist you with debugging the outgoing emails (and SMTP server configuration):
- Redirect all outgoing emails to a specific address:
// Divert all outgoing emails to this address to test and debug emailing features
// $CFG->divertallemailsto = 'root@localhost.local'; // NOT FOR PRODUCTION SERVERS!
- Turn on the CRON debugging and run CLI cron.php script.
// Force developer level debug and add debug info to the output of cron
// $CFG->showcrondebugging = true;
And then use SSH (or putty.exe, on windows) to run:
you@moodle-server(/var/www/html/moodle)# php admin/cli/cron.php
- Turn on verbose SMTP debugging and output it into system's error_log (code hack):
As suggested on Moodle's discussion forums: Open lib/moodlelib.php L5379 and change it to:
if (!empty($CFG->debugsmtp)) {
$mailer->SMTPDebug = 1; // 0 - no debug ... 4 - low level full debug
$mailer->Debugoutput = "error_log";
}
See more info about SMTPDebug parameters & Debugoutput parameters, Set-up mailcatcher (https://mailcatcher.me/).
Performance info
The Performance info option determines whether performance info will be included in the footer of the standard theme (and some other themes). Performance info includes the time for the page to load, the amount of memory used to generate the page, cpu usage, load, and the record cache hit/miss ration.
If you add
define('MDL_PERF', true);
define('MDL_PERFDB', true);
define('MDL_PERFTOLOG', true);
define('MDL_PERFTOFOOT', true);
to your config.php file, then it will also count database queries. (This has to be in config.php, because Moodle starts doing DB queries before it loads the config information in the database!)
To hide performance info from ordinary users, see the discussion Performance info only for admins?
Show origin of languages strings
Helps with translation and also with Language customization. Sometimes ?strings=1
should be added; other times &strings=1
. See the Wikipedia article Query string for details.
Show origin of SQL calls
If you turn this on, then for every bit of SQL send to the Database server, an SQL comment is added with all or part of the PHP stack trace. That means that if something happens which causes the query to be logged by the database (e.g. and error, or a slow query) you can find where in Moodle that query came from.
Show validator links
Be careful, read the warning.
Show page information
To show page information printed in the page footer.
Show template information
To show templates used for rendering as comments in the page HTML. After changing the setting, you need to purge caches for the change to take effect.
Example of how the templates are shown in the page HTML source:
<!-- template(PHP): core/pix_icon_fontawesome -->
<i class="icon fa fa-window-close fa-fw " aria-hidden="true"></i>
<!-- /template(PHP): core/pix_icon_fontawesome -->
It is important to note the added comments can interfere with some scripts and can even break core functionality!
Debug SQL queries
You can add (turn ON) any of the following dboptions in your config.php files, which log different types of SQL queries into mdl_log_queries table:
- logall - log all queries - suitable only for developers, causes high server loads and NOT recommended for production.
- logslow - log queries that take longer than specified number of seconds (float values are accepted).
- logerrors - log all error queries.
Full sample:
$CFG->dboptions = array (
//'logall' => true,
'logslow' => 5,
'logerrors' => true,
);
However, if you are in control of your Database server, your database probably has an option to log slow database queries in the database logs, and that is probably a technically better solution, if it is available to you.
What to do if you cannot get to the admin screens
If the error is stopping you even getting to the admin screens to turn on debugging, then you can set the debugging setting manually.
Try typing the URL directly
The debug settings are at the URL http://.../admin/settings.php?section=debugging
on your server. Sometimes that URL will work, even though the pages you need to go to get there (for example the site front page) do not. So it is worth trying to enter that URL directly.
In config.php
In config.php you can uncomment lines (delete the // at the start of the line) under Section 7 to enable debugging for all or just specific users:
//=========================================================================
// 7. SETTINGS FOR DEVELOPMENT SERVERS - not intended for production use!!!
//=========================================================================
//
// Force a debugging mode regardless the settings in the site administration
// @error_reporting(E_ALL | E_STRICT); // NOT FOR PRODUCTION SERVERS!
// @ini_set('display_errors', '1'); // NOT FOR PRODUCTION SERVERS!
// $CFG->debug = (E_ALL | E_STRICT); // === DEBUG_DEVELOPER - NOT FOR PRODUCTION SERVERS!
// $CFG->debugdisplay = 1; // NOT FOR PRODUCTION SERVERS!
//
// You can specify a comma separated list of user ids that that always see
// debug messages, this overrides the debug flag in $CFG->debug and $CFG->debugdisplay
// for these users only.
// $CFG->debugusers = '2';
Remember to comment those lines again (reinsert the // at the start of the line) when you have finished diagnosing your problem.
NOTE 1: do not try to modify the config database table directly, it will not work because the values are cached in MUC.
NOTE 2: if you find your config.php does not have the above settings (you have a cut down approx 30 lines config.php) look for a "config-dist.php" file that contains the full details. I would suggest transferring your details in the current config.php file you have into the full config file and renaming that one to "config.php".
See also
- If you are a developer looking for usage information on the debugging() statement, try lib/weblib.php for documentation on how it is used, and lib/setuplib.php for definitions of which PHP error levels the DEBUG_* flags map to.
- Developers can also use XDEBUG (Installed as a module on the Apache server) to further dig into the code, step by step using an XDEBUG client application. Probably, as part of their favorite IDE. For example: NetBeans, phpStorm or...