NAME
    Apache2::ModLogConfig - a Perl interface to mod_log_config

SYNOPSIS
    Call a Perl handler from a "CustomLog" format specification:

     <Perl>
       use Apache2::ModLogConfig ();

       sub My::Format {
         my ($r)=@_;

         return $a_string;
       }
     </Perl>

     CustomLog LOGFILE "... %{My::Format}^..."

    Use a Perl handler as logfile:

     PerlModule Apache2::ModLogConfig
     PerlModule My::LogReceiver

     CustomLog "@perl: My::LogReceiver" "format spec"

    Print to a logfile:

     use Apache2::ModLogConfig ();

     sub handler {
       my ($r)=@_;
       ...
       my $log=$r->server->custom_log_by_name('logs/access_log');
       my $success=$log->print($r, qw/тут был вася/, "\n");
       ...
     }

INSTALLATION
     perl Makefile.PL
     make
     make test
     make install

DESCRIPTION
    The reason to start this module was to monitor the number of incoming
    and outgoing bytes for each request. "mod_log_config" in combination
    with "mod_logio" can log these numbers. But in Perl they are really hard
    to get.

    "mod_logio" uses a network-level input filter as byte counter. The
    outgoing bytes are counted by the core output filter and reported back
    to "mod_logio" if loaded.

    Now, with the help of this module you can do 3 things:

    *   call a Perl handler from a "CustomLog" format specification

    *   use a Perl handler in place of a logfile

    *   write out-of-bound messages to logfiles managed by "mod_log_config"

    For this to work, the module must be loaded before the
    "PerlOpenLogsHandler" phase. Calling a Perl handler from a format
    specification requires an early start of the interpreter and the module
    must be loaded at that stage. That means you need either a
    "<Perl>...</Perl>" section in your httpd.conf or the module must be
    loaded by "PerlLoadModule".

    Note, while developing this module I have found a bug in httpd that can
    lead to segfaults. It is present at least up to httpd 2.2.17. It occurs
    if "mod_log_config" is statically compiled into httpd and "BufferedLogs"
    are used. In this case avoid changing the "BufferedLogs" setting while
    restarting httpd via "SIGHUP" or "SIGUSR1".

    See <https://issues.apache.org/bugzilla/show_bug.cgi?id=50861>

  Call a Perl handler from a "CustomLog" format specification
    To be used this way "Apache2::ModLogConfig" registers the "^" format
    with "mod_log_config".

    "^" was chosen because it resembles the "^" in a number of Perl
    variables like $^V for example.

    Now, a format specifier can receive an argument. The argument is given
    in braces between the "%" sign and the specifier. The "^" specifier's
    argument specifies the Perl handler to call. A fully qualified name is
    expected.

    Example:

     LogFormat "%{My::Handler::function}^" perllog

    The handler is called with an Apache2::RequestRec object as the only
    parameter. In a chain of internal redirects this is by default the final
    request. It can be modified according to the "mod_log_config"
    documentation:

     LogFormat "%<{My::Handler::function}^" perllog

    This way the initial request is passed to the handler.

    Other modifiers are also applicable as described by "mod_log_config".

  Use a Perl handler in place of a logfile
    Now Perl handler works as log drain. That means it will receive a log
    file.

     CustomLog "@perl: My::LogReceiver" FORMATSPEC

    The prefix @perl: is used to distinguish between a normal file name or
    pipe specification and the Perl handler.

    The actual handler name is resolved the usual modperl way. That means if
    there is no function named "My::LogReceiver", "My::LogReceiver::handler"
    is looked up. Auto-loading should work as well (although untested).
    Further, an anonymous function can be specified as:

     CustomLog "@perl: sub { my ($r, @strings)=@_; ... }" FORMATSPEC

    The handler is called with the final request of a chain of internal
    redirects as the first parameters. The other parameters are all strings
    where each one corresponds to either a the result of a format specifier
    or a constant string.

    Assuming the following format specification

     "input bytes=%I, output bytes=%O"

    the handler is called with 6 parameters:

    *   the request object

    *   the string "input bytes="

    *   a number according to %I

    *   the string ", output bytes="

    *   a number according to %O

    *   and a trailing "\n" to close the line

    Note, a possible "PerlLogHandler" runs before the "mod_log_config"
    handler. So, it's not possible to record a few values here and use them
    in a "PerlLogHandler". A "PerlCleanupHandler" or a request pool cleanup
    handler however should be fine.

    My original problem now can be solved as:

     package My::IO;

     sub handler {
       my ($r, $in, $out)=@_;
       $r->notes->{InBytes}=$in;
       $r->notes->{OutBytes}=$out;
     }

     sub cleanup {
       my ($r)=@_;
       my ($in, $out)=@{$r->notes}{qw/InBytes OutBytes/};
       ...
     }

    in httpd.conf:

     CustomLog "@perl: My::IO" "%I%O"
     PerlCleanupHandler My::IO::cleanup

  Writing to a "CustomLog" logfile and introspection
    Have you ever wanted to write to the access_log directly? I haven't. But
    now it's feasible and perhaps someone finds a weird usage case.

    "Apache2::ModLogConfig" implements the following methods.

   @names=$s->custom_logs
    Assuming $s is a Apache2::ServerRec object this method returns the
    logfile names defined for this VHost. The elements of @names are
    literally the strings specified as first parameter to "CustomLog".

   $log=$s->custom_log_by_name($name)
    Assuming $s is a Apache2::ServerRec object this method returns an
    "Apache2::ModLogConfig" object for the given name.

   $status=$log->print($r, @strings)
    Assuming $log is an "Apache2::ModLogConfig" object and $r is an
    Apache2::RequestRec this method prints the strings in @strings to the
    file. No escaping is done.

    $status is an APR status code ("APR::Const::SUCCESS" if all is well).

  EXPORT
    None.

SEE ALSO
    modperl, mod_log_config, apache httpd

AUTHOR
    Torsten Förtsch, <torsten.foertsch@gmx.net>

COPYRIGHT AND LICENSE
    Copyright (C) 2011 by Torsten Förtsch

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, either Perl version 5.12.3 or, at
    your option, any later version of Perl 5 you may have available.