=head1 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 DebugHeadersIn On PerlSetVar DebugHeadersOut On PerlSetVar DebugNotes On PerlSetVar DebugPNotes On PerlSetVar DebugPID On PerlSetVar DebugIPList "1.2.3.4, 1.2.3." PerlSetVar DebugFile "/path/to/debug_log" 2) using Apache::DebugInfo on the fly in handler or script: use Apache::DebugInfo; my $r = shift; my $debug_object = Apache::DebugInfo->new($r); # dump $r->headers_in right now $debug_object->headers_in; # log $r->headers_out after the response goes to the client $debug_object->headers_in('PerlCleanupHandler'); # log all the $r->pnotes at Fixup and at Cleanup $debug_object->pnotes('PerlCleanupHandler','PerlFixupHandler'); DESCRIPTION Apache::DebugInfo offers the ability to monitor various bits of per-request data. Its functionality is similar to Apache::DumpHeaders while offering several additional features, including the ability to - separate inbound from outbound HTTP headers - view the contents of $r->notes and $r->pnotes - view any of these at the various points in the request cycle - add output for any request phase from a single entry point - use as a PerlInitHandler or with direct method calls - use partial IP addresses for filtering by IP - offer a subclassable interface 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::DebugLog handler DebugPID - calls pid() during request init DebugHeadersIn - calls headers_in() during request init DebugHeadersOut - calls headers_out() during request cleanup DebugNotes - calls notes() during request cleanup DebugPNotes - calls pnotes() during request cleanup Alternatively, you can control output activity on the fly by calling Apache::DebugInfo methods directly (see METHODS below). Additionally, the following variables hold special arguments: DebugFile - absolute path of file that will store the info defaults to STDERR (which is likely error_log) DebugIPList - a space delimited list of IP address for which data should be captured this can be a partial IP - 1.2.3 will match 1.2.3.5 and 1.2.3.6 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: All methods can be called without any arguments, in which case the associated data is logged 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 all of the incoming HTTP headers headers_out() - display all of the outgoing HTTP headers notes() - display all the strings set by $r->notes pnotes() - display all the variables set by $r->pnotes pid() - display the process PID NOTES 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 Setting DebugInfo to Off has no effect on direct method calls. 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... SEE ALSO perl(1), mod_perl(1), Apache(3) AUTHOR Geoffrey Young COPYRIGHT Copyright 2000 Geoffrey Young - all rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.