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.  

Currently, logging pnotes only goes 1 level deep - if pnotes holds,
say, a hash of hashes, only the main hash keys are logged.  Also, 
glob, object, and code references are not supported yet.  Both these
features may be supported in the future via Data::Dumper.

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), Apache::Table(3)

AUTHOR

Geoffrey Young <geoff@cpan.org>

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.