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