flog(n)                                                   flog(n)

NAME
        flog - real time log splitter and viewer

SYNOPSIS
        flog  -c=file [ -d[=file] ] [ -g=GID|group ]  [ -u=UID|
        user ] [ -o ]

DESCRIPTION
        flog grew out of the desire to have Apache httpd(8) dir-
        ect log output to  multiple files dependent  upon various
        parameters. While

        CustomLog file-pipe format-or-nickname env=[!]environment-variable

        is pretty nifty it's basically an if-then-else construct,
        and I desired more of a switch-case one.  Hence flog was
        born.

        Yes,  there are other means of acheiving similar results.
        Apache::Request with mod_perl comes to mind.

OPTIONS
        -c=file
                Use configuration file

        -d
        -d=file
                Open file in  clobber mode for  debug output.  If
                file is not specified /dev/tty8 is used instead.

        -g=GID|group
                flog will run as the group specified

        -o
                flog will  NOT  pre-open  all of %FILES  for you.
                You'll need to use printFlog instead of print.

                printFlog(FH, [close])

                printFlog's first argument is the filehandle to
                open (if necessary). If its second argument is
                true, it will close the file after writing. See
                CAVEATS

        -u=UID|user
                flog will run as the user specified

CONFIGURATION
        Configuration of flog is meant to be fairly straight for-
        ward.  The configuration  file should contain  at least a
        global hash named FILES, and a sub named flog.

        %FILES
                The keys for  %FILES  are  file descriptor  names
                which flog will automatically open for you.

                The values for  %FILES are  anonymous arrays. The
                first index  is the  file name  to be  associated
                with the  key/file handle. If the second index is
                present  and  true,  the file handle  will be un-
                buffered. See CAVEATS

        Flog::init();
                A call to this function after declaring %FILES.

        sub flog
                The subroutine  called for each  log entry  which
                contains the logic  to determine where  the entry
                should be output to. It takes no arguments.

SIGNALS
        flog will respond  to various signals.  Listed below are
        those that have special meaning.
        
        HUP
                Flush buffers, reread the configuration file, and
                reopen all of %FILEs unless -o is was used.

        INT, PIPE, TERM
                Flush buffers and exit.

        USR1
                Flush buffers.
                NOT YET IMPLEMENTED

        USR2
                Flush  buffers.  Toggle  the  pausing  of  output
                (queueing input) useful for log rotation etc.
                NOT YET IMPLEMENTED


CAVEATS
        The -g and -u options  only work if the current user is
        allowed to setuid. This is typically root.

        From perlfaq5
        In most stdio implementations, the type of output buffer-
        ing and the  size of the  buffer varies  according to the
        type of device. Disk files are block buffered, often with
        a buffer size of more than 2k.

        4k seems pretty typical, to get an idea what 4k of log is
        examine the 4k-block file in the root directory of the
        flog package.

        Pros
                Buffering helps your system reduce I/O.  Big deal
                you say?  Well,  more often  than not  I/O is the
                main bottleneck in modern systems.  Especially on
                web servers.  So you typically want to do as lit-
                tle writing to the disk as possible.

                Closing and reopening a file as printFlog does is
                moderately expensive, since close forces a write.

        Cons
                flog's  buffered logs are  slightly more prone to
                data loss or  corruption than an  unbuffered log.
                If the  system  undergoes a  disorderly shutdown,
                i.e.;  flog does not receive a  recognized signal
                it won't have a chance to flush its buffers.  And
                since the buffer is block/byte-wise and not line-
                wise,  if this were to occur  your log may become
                corrupt. The last write may not have ended with a
                newline. However this  could easily be fixed with
                a text editor.

                Each open buffered log will consume 0-4k  for the
                actual data buffer, and a filehandle.

        In conclusion;  if resource usage is critical  use -o, if
        resources are  not an issue,  but the  low potential  for
        data loss is unexceptable, use an unbuffered log.  Other-
        wise use a buffered log.

TODO
        See the TODO file that came in the distributionpackage.

BUGS
        None known. Bug reports to: webmaster@pthbb.org

SEE ALSO
        httpd(8), PERL(1).

        Documentation on  Apache  log file-pipe  configuration is
        available from
        http://www.apache.org/docs/mod/mod_log_config.html#transferlog

LICENSE
        LGPL or Perl artistic license.

AUTHORS
        http://pthbb.org