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 handlers Alternatively, 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 types METHODS 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 above NOTES 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 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.