mod_backtrace
Introduction
mod_backtrace can be used in two ways:
- Annotate error log with backtraces when certain conditions are met.
- Provide an API to other modules for obtaining a backtrace. mod_whatkilledus uses this API, which is how crash reports can include a backtrace of the crashing thread when mod_backtrace is loaded.
- Overview (read this first)
- mod_whatkilledus documentation
Supported platforms
- Windows Vista or Windows Server 2008 and newer
- any Linux since at least 2004
- any FreeBSD since at least 2004
- Mac OS X 10.5 and later
- Solaris 9 and later
Building and enabling mod_backtrace
Detailed configuration information
BacktraceSymbolPath directive (Windows only)
On the Windows platform, information for resolving symbols in
backtraces is commonly maintained in .pdb files.
mod_backtrace will automatically include the Apache
httpd bin and modules directory in the
symbol path used when resolving backtraces, and will warn
if .pdb files are not found there.
Use this directive to point to other directories which may contain symbol files for other components.
Default value: none
Argument:
Use a semicolon-delimited path of directories (with forward slashes).
Example:
BacktraceSymbolPath c:/symbols;c:/Windows/symbols
BacktraceErrorLogging directive (Apache httpd < 2.4)
This can be used to log a backtrace showing the writer of the error log message, and may be helpful in occasional circumstances when the code path to the failure is not obvious. When logged, the backtrace will appear on a separate line in the error log.
Default value: Off
Argument:
- Off
- Disable
- On
- Enable for all error log messages. This is not recommended..
/search-string/- Log the backtrace if search-string (fixed text) occurs in the error log message. The formatted message text is searched.
error==apr-error-code- Log the backtrace if the APR error code for the message is apr-error-code.
oserror==OS-error-code- Log the backtrace if the APR error code is a mapping of the
specified OS-error-code. Such error codes appear as
as
(OS nnnnn)in the error log.
ErrorLogFormat directive (Apache httpd >= 2.4)
ErrorLogFormat is a core Apache httpd directive which controls the format of error log records for Apache httpd 2.4 and later.
As with BacktraceErrorLogging for older levels of Apache httpd, this feature can be used to log backtraces for selected error log messages. However, the backtrace will be provided on the same line.
The format string for a backtrace is %B. It takes
an argument to restrict when the backtrace will be
logged. As with other error log format strings, the argument
argument is configured
as %{optional-argument}B.
Optional argument to %B:
/search-string/- Log the backtrace if search-string (fixed text) occurs in the error log message. The message format string is searched, not the formatted message text.
error==apr-error-code- Log the backtrace if the APR error code for the message is apr-error-code.
oserror==OS-error-code- Log the backtrace if the APR error code is a mapping of the
specified OS-error-code. Such error codes appear as
as
(OS nnnnn)in the error log.
Without the optional argument, the backtrace will not be logged.
Optional function APIs
mod_backtrace exports two functions which are used by mod_whatkilledus. These functions provide access to low-level code which obtains and formats backtraces and provides descriptions of exceptions.
You can check the mod_whatkilledus source code to see how these functions may be used. At present these are not considered clearly defined programming interfaces, and they may change without notice.
This is expected to change in the future once a few additional features are implemented.