Difference between revisions of "Developer Area/Core Subsystems/Error Handling, Logging and Messages"
From Mahara Wiki
< Developer Area | Core Subsystems
Brettwilkins (talk | contribs) (Created page with "This page details how the error/excpetion handling and logging works in Mahara. It also details how messages displayed to the user. This page is '''not''' about the system for me…") |
|||
| Line 3: | Line 3: | ||
<div id="section_1"> | <div id="section_1"> | ||
| − | === Error handling === | + | ===Error handling=== |
This section describes error handling, '''not''' exceptions, which are described below. | This section describes error handling, '''not''' exceptions, which are described below. | ||
| Line 9: | Line 9: | ||
<div id="section_2"> | <div id="section_2"> | ||
| − | ==== Concepts ==== | + | ====Concepts==== |
Error handling is done with the help of two concepts: log '''levels''' and log '''targets'''. | Error handling is done with the help of two concepts: log '''levels''' and log '''targets'''. | ||
| Line 21: | Line 21: | ||
</div><div id="section_3"> | </div><div id="section_3"> | ||
| − | ==== Types of Log Levels ==== | + | ====Types of Log Levels==== |
The debug, info and warning levels have a similar meaning to what you would expect - they are for messages in increasing importance (and presumably decreasing occurance). The "environment" level is for messages that are related to the sanity of the setup that Mahara is installed in - for example, register_globals being turned on. Developers will probably never need to use this level. | The debug, info and warning levels have a similar meaning to what you would expect - they are for messages in increasing importance (and presumably decreasing occurance). The "environment" level is for messages that are related to the sanity of the setup that Mahara is installed in - for example, register_globals being turned on. Developers will probably never need to use this level. | ||
| Line 27: | Line 27: | ||
</div><div id="section_4"> | </div><div id="section_4"> | ||
| − | ==== Backtraces ==== | + | ====Backtraces==== |
You can configure which levels of logging generate backtraces in the config.php file. This allows you to choose which levels to receive more information about. Typically, you only want backtraces for warnings, but you can generate backtraces for all levels of errors if required. | You can configure which levels of logging generate backtraces in the config.php file. This allows you to choose which levels to receive more information about. Typically, you only want backtraces for warnings, but you can generate backtraces for all levels of errors if required. | ||
| Line 33: | Line 33: | ||
</div><div id="section_5"> | </div><div id="section_5"> | ||
| − | ==== Configuration ==== | + | ====Configuration==== |
See config-dist.php for examples of how to configure logging. | See config-dist.php for examples of how to configure logging. | ||
| Line 39: | Line 39: | ||
</div><div id="section_6"> | </div><div id="section_6"> | ||
| − | ==== Triggering errors ==== | + | ====Triggering errors==== |
; The following four functions are available for triggering errors | ; The following four functions are available for triggering errors | ||
| Line 47: | Line 47: | ||
:* log_environ | :* log_environ | ||
; Each one takes three parameters | ; Each one takes three parameters | ||
| − | : :* '''$message''' | + | : :* '''$message''': The message to log |
| − | :* '''$escape''' | + | :* '''$escape''': Whether to HTML escape the message when it appears in an HTML context. By default, this is true. This allows messages to be logged that include HTML, if necessary. Not normally so useful for logging, but as the messaging system uses this and the underlying engine is the same, the support is available for this. |
| − | :* '''$backtrace''' | + | :* '''$backtrace''': Whether this message should include a backtrace. By default this is true, but there may be cases where you wish to log a message and the backtrace won't be helpful, in which case you can set this to false. |
</div><div id="section_7"> | </div><div id="section_7"> | ||
| − | ==== Notes ==== | + | ====Notes==== |
PHP notices and warnings are changed to "warning" level messages and then are handled the same as the rest of the system. | PHP notices and warnings are changed to "warning" level messages and then are handled the same as the rest of the system. | ||
| Line 59: | Line 59: | ||
</div></div><div id="section_8"> | </div></div><div id="section_8"> | ||
| − | === Exceptions === | + | ===Exceptions=== |
There is a default exception handler registered, if it catches anything it will end the script with a non-committal message to the user. Please try to catch exceptions that your code can deal with if possible, without catching the "Exception" class itself. | There is a default exception handler registered, if it catches anything it will end the script with a non-committal message to the user. Please try to catch exceptions that your code can deal with if possible, without catching the "Exception" class itself. | ||
</div> | </div> | ||
Revision as of 15:13, 11 May 2011
This page details how the error/excpetion handling and logging works in Mahara. It also details how messages displayed to the user. This page is not about the system for messaging users through email etc.
Error handling
This section describes error handling, not exceptions, which are described below.
Concepts
Error handling is done with the help of two concepts: log levels and log targets.
A log level is reasonably straight forward - there are four levels of logging in the system, debug, info, warning and environment. Errors that occur in the system will occur at one of those four levels.
A log target is either the error log or the screen at this point, although targets such as email, emaildigest etc. are easily enough added. For each log level, you can configure the system to send the messages at that level to any combination of the log targets.
So, for example, you could send debug and info notices to the logs, warnings to the log and screen and environment errors nowhere. Different combinations will suit different installations, from development to a production site.
Types of Log Levels
The debug, info and warning levels have a similar meaning to what you would expect - they are for messages in increasing importance (and presumably decreasing occurance). The "environment" level is for messages that are related to the sanity of the setup that Mahara is installed in - for example, register_globals being turned on. Developers will probably never need to use this level.
Backtraces
You can configure which levels of logging generate backtraces in the config.php file. This allows you to choose which levels to receive more information about. Typically, you only want backtraces for warnings, but you can generate backtraces for all levels of errors if required.
Configuration
See config-dist.php for examples of how to configure logging.
Triggering errors
- The following four functions are available for triggering errors
- :* log_debug
- log_info
- log_warn
- log_environ
- Each one takes three parameters
- :* $message: The message to log
- $escape: Whether to HTML escape the message when it appears in an HTML context. By default, this is true. This allows messages to be logged that include HTML, if necessary. Not normally so useful for logging, but as the messaging system uses this and the underlying engine is the same, the support is available for this.
- $backtrace: Whether this message should include a backtrace. By default this is true, but there may be cases where you wish to log a message and the backtrace won't be helpful, in which case you can set this to false.
Notes
PHP notices and warnings are changed to "warning" level messages and then are handled the same as the rest of the system.
Exceptions
There is a default exception handler registered, if it catches anything it will end the script with a non-committal message to the user. Please try to catch exceptions that your code can deal with if possible, without catching the "Exception" class itself.