6.4 Custom Exception Handling Hooks

Normally PSE will catch and display information about uncaught exceptions raised in servlets. You can control how and when this happens by setting options in the pse.conf file, however sometimes it is desirable to act on uncaught exceptions in a customized manner. For example, you may want to automatically send an e-mail to an administrator or developer when servlets raise an uncaught exception. PSE provides a way to do this through exception hooks.

To create an exception hook, you must define two functions in an external module to handle exceptions that should be formatted in either HTML or text only. These functions must have the following signature:

text_traceback( req, exception, traceback, frames)
html_traceback( req, exception, traceback, frames)
The req argument is the request object from mod_python. This can be used to find information about the request that may be helpful in providing debugging information. Please refer to the mod_python documentation for details.

The exception argument is the exception only portion of the traceback, as a list, similar to the result of the format_exception_only function from the traceback module.

The traceback argument is a list of ``pre-processed'' stack entries from the traceback, similar to teh result of the extract_tb function from the traceback module. However, only relevant stack entries are returned, which do not include references to internal PSE functions. Refer to the Python traceback module documentation for details.

The frames argument is a list of frame objects, similar to the result of a call to the getinnerframes function from the inspect module. A frame object can be used to obtain information about each frame in the stack, such as the current function, module, line number, and source code (if available). Refer to the Python inspect module documentation for details.

The return value is a string message to be sent to the browser, which should contain either HTML or plain text, as indicated by the function name.

The module must contain both functions for the hooks to be initialized by PSE. In the pse.conf file in the [Debug] section, set ExceptionHooksModule to the full path of the module containing your custom exception hooks functions. You will need to restart apache for the changes to take effect.