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      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_object = Apache::DebugInfo->new($r);

     # set the output file
     $debug_object->file("/path/to/debug_log");

     # get the ip addresses for which output is enabled
     my $ip_list = $debug_object->ip;

     # 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
  - use file type for filtering
  - 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::DebugInfo handler

  DebugPID        - dumps apache child pid during request init
  DebugHeadersIn  - dumps request headers_in during request init

  DebugHeadersOut - dumps request headers_out during request cleanup
  DebugNotes      - dumps request notes during request cleanup
  DebugPNotes     - dumps request 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 optional 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
                    debugging is enabled
                    this can be a partial IP - 1.2.3 will match
                    1.2.3.5 and 1.2.3.6

  DebugTypeList   - a space delimited list of file extensions
                    for which debugging is enabled

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 all the request incoming HTTP headers

   headers_out() - display all the request outgoing HTTP headers

   notes()       - display all the request strings set by $r->notes

   pnotes()      - display all the request variables set by $r->pnotes

   pid()         - display the apache child process PID

   timestamp()   - display the current system time

   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
                   overrides DebugFile above

   ip($list)     - get or set the ip list
                   accepts a space delimited list as an argument
                   overrides DebugIPList above

   type($list)   - get or set the file type list
                   accepts a space delimited list as an argument
                   overrides DebugTypeList above

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.  

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 becuase matching is done whenever
the handler is added to the stack, but the output file is used when
the 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...

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.