NAME
Apache::DebugInfo - log various bits of per-request data
SYNOPSIS
There are two ways to use this module...
1) using Apache::DebugInfo to control debugging automatically
httpd.conf:
PerlInitHandler Apache::DebugInfo
PerlSetVar DebugInfo On
PerlSetVar DebugPID On
PerlSetVar DebugHeadersIn On
PerlSetVar DebugDirConfig On
PerlSetVar DebugHeadersOut On
PerlSetVar DebugNotes On
PerlSetVar DebugPNotes On
PerlSetVar DebugGetHandlers On
PerlSetVar DebugTimestamp On
PerlSetVar DebugMarkPhases On
PerlSetVar DebugFile "/path/to/debug_log"
PerlSetVar DebugIPList "1.2.3.4 1.2.4."
PerlSetVar DebugTypeList ".html .cgi"
2) using Apache::DebugInfo on the fly
in handler or script:
use Apache::DebugInfo;
my $r = shift;
my $debug = Apache::DebugInfo->new($r);
# set the output file
$debug->file("/path/to/debug_log");
# get the ip addresses for which output is enabled
my $ip_list = $debug->ip;
# dump $r->headers_in right now
$debug->headers_in;
# log $r->headers_out after the response goes to the client
$debug->headers_in('PerlCleanupHandler');
# log all the $r->pnotes at Fixup and at Cleanup
$debug->pnotes('PerlCleanupHandler','PerlFixupHandler');DESCRIPTION
Apache::DebugInfo gives the programmer the ability to monitor various bits of per-request data.
You can enable Apache::DebugInfo as a PerlInitHandler, in which case it chooses what request phase to display the appropriate data. The output of data can be controlled by setting various variables to On:
DebugInfo - enable Apache::DebugInfo handler
DebugPID - dumps apache child pid during request init
DebugHeadersIn - dumps request headers_in during request init
DebugDirConfig - dumps PerlSetVar and PerlAddVar during request init
DebugGetHandlers - dumps enabled request handlers during init
DebugHeadersOut - dumps request headers_out during request cleanup
DebugNotes - dumps request notes during request cleanup
DebugPNotes - dumps request pnotes during request cleanup
DebugTimestamp - prints localtime at the start of each request
DebugMarkPhases - prints the name of the request phase when the
phase is entered, prior to any other handlersAlternatively, you can control output activity on the fly by calling Apache::DebugInfo methods directly (see METHODS below).
Additionally, the following optional variables hold special arguments:
DebugFile - absolute path of file that will store the info
don't forget to make the file writable by
whichever user Apache runs as (likely nobody)
defaults to STDERR (which is likely error_log)
DebugIPList - a space delimited list of IP address for which
debugging is enabled
this can be a partial IP - 1.2.3 will match
1.2.3.5 and 1.2.3.6
if absent, defaults to all remote ip addresses
DebugTypeList - a space delimited list of file extensions for
which debugging is enabled (.cgi, .html...)
if absent, defaults to all typesMETHODS
Apache::DebugInfo provides an object oriented interface to allow you to call the various methods from either a module, handler, or an Apache::Registry script.
Constructor: new($r) - create a new Apache::DebugInfo object requires a valid Apache request object
Methods: The following methods can be called without any arguments, in which case the associated data is output immediately. Optionally, each can be called with a list (either explicitly or as an array) of Perl*Handlers, which will log the data during the appropriate phase:
headers_in() - display incoming HTTP headers
headers_out() - display outgoing HTTP headers
notes() - display strings set by $r->notes
pnotes() - display variables set by $r->pnotes
pid() - display the apache child process PID
get_handlers() - display variables set by PerlSetVar and PerlAddVar
dir_config() - display the enabled handlers for this request
timestamp() - display the current system time
mark_phases() - display the phase before executing any other
handlers. if given the argument 'All',
mark_phases will display the entry into all
phases after the current phase. calling with
no arguments outputs the current phase
immediately.
There are also the following methods available for manipulating
the behavior of the above methods:
file($file) - get or set the output file
accepts an absolute filename as an argument
returns the output filehandle
defaults to, but overrides DebugFile above
ip($list) - get or set the ip list
accepts a space delimited list as an argument
defaults to, but overrides DebugIPList above
type($list) - get or set the file type list
accepts a space delimited list as an argument
defaults to, but overrides DebugTypeList aboveNOTES
Setting DebugInfo to Off has no effect on the ability to make direct method calls.
Verbose debugging is enabled by setting the variable $Apache::DebugInfo::DEBUG=1 to or greater. To turn off all messages set LogLevel above info.
This is alpha software, and as such has not been tested on multiple platforms or environments. It requires PERL_INIT=1, PERL_CLEANUP=1, PERL_LOG_API=1, PERL_FILE_API=1, PERL_STACKED_HANDLERS=1, and maybe other hooks to function properly.
FEATURES/BUGS
Once a debug handler is added to a given request phase, it can no longer be controlled by ip() or type(). file(), however, takes affect on invocation. This is because the matching is done when the Perl*Handler is added to the stack, while the output file is used when the Perl*Handler is actually executed.
Calling Apache::DebugInfo methods with 'PerlHandler' as an argument has been disabled - doing so gets your headers and script printed to the browser, so I thought I'd save the unaware from potential pitfalls.
Phase misspellings, like 'PelrInitHandler' pass through without warning, in case you were wondering where your output went...
The get_handlers and mark_phases methods are incomplete, mainly due to oversights in the mod_perl API. Currently (as of mod_perl 1.2401), they cannot function properly on the following callbacks: PerlInitHandler As such, they have been disabled until forthcoming corrections to the API can be implemented. PerlHeaderParserHandlers and PerlPostRequestHandlers function normally.
The output uri is whatever the uri was when new() was called (either on the fly or in Apache::DebugInfo::handler). Thus if the uri has undergone translation since the new() call the original, not the new, uri will be output. This feature can be easily remedied, but having a changing uri in the output may be confusing when debugging. Future behavior will be influenced by user feedback.
SEE ALSO
perl(1), mod_perl(1), Apache(3)
AUTHOR
Geoffrey Young <geoff@cpan.org>
COPYRIGHT
Copyright (c) 2000, Geoffrey Young. All rights reserved.
This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.