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 <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.