$Id: README,v 1.1 2007/02/03 12:26:16 cmanley Exp $
--------
Abstract
--------
Log::Dispatch output class for logging to shared files.
------------
Requirements
------------
Log::Dispatch
Params::Validate
Time::HiRes
Scalar::Util
------------------
Basic Installation
------------------
Log::Dispatch::FileShared may be installed through the CPAN shell
in the usual manner:
# perl -MCPAN -e 'install Log::Dispatch::FileShared'
You can also read this README from the CPAN shell:
# perl -MCPAN -e shell
cpan> readme Log::Dispatch::FileShared
And you can install the component from the CPAN prompt as well:
cpan> install Log::Dispatch::FileShared
-------------------
Manual Installation
-------------------
Log::Dispatch::FileShared can also be installed manually. The latest CPAN
version can be found at
<http://www.cpan.org/modules/by-module/Log/> or in a
similarly named directory at your favorite CPAN mirror.
Downloading and unpacking the distribution are left as exercises for
the reader. To build and test it:
perl Makefile.PL
make test
When you're ready to install the component:
make install
It should now be ready to use.
On Win32 systems, replace "make" in the above commands with "nmake".
The nmake utility can be downloaded from
C<http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/Nmake15.exe>
--------------------
Module Documentation
--------------------
NAME
Log::Dispatch::FileShared - output class for logging to shared files.
SYNOPSIS
use Log::Dispatch::FileShared;
my $output = Log::Dispatch::FileShared->new(
name => 'test',
min_level => 'info',
filename => 'application.log',
);
$output->log( level => 'emerg', message => 'Time to die.' );
DESCRIPTION
This module provides an output class for logging to shared files under
the Log::Dispatch system.
Log messages are written using the flock file locking mechanism on a per
write basis which means that this module is suitable for sharing a log
file in a multitasking environment.
This class descends directly from Log::Dispatch::Output.
OTHER SIMILAR CLASSES
Log::Dispatch::File doesn't provide any locking mechanism which makes it
unsuitable for sharing log files between multiple processes (unless you
don't mind having corrupt log messages on rare occasions).
Log::Dispatch::File::Locked does implement locking, but on a per open
handle basis which means that only a single process can log to the file
as long as the file is open. All other processes will block. The only
way to prevent other processes from blocking is to close the handle
after every write which degrades logging performance very much.
Therefore this class too is unsuitable for sharing log files between
multiple processes.
METHODS
* new(%p)
This method takes a hash of parameters. The following options are
valid:
* name ($)
The name of the object (not the filename!). Required.
* min_level ($)
The minimum logging level this object will accept. See the
Log::Dispatch documentation on Log Levels for more
information. Required.
* max_level ($)
The maximum logging level this obejct will accept. See the
Log::Dispatch documentation on Log Levels for more
information. This is not required. By default the maximum is
the highest possible level (which means functionally that
the object has no maximum).
* filename ($)
The filename to be opened for appending.
* mode ($)
The mode the file should be opened with. Valid options are
'>' (write) and '>>' (append). The default is '>>' (append).
* perms ($)
If the file does not already exist, the permissions that it
should be created with. Optional. The argument passed must
be a valid octal value, such as 0600. It is affected by the
current or given umask.
* umask ($)
The optional umask to use when the file is created for the
first time.
* flock ($)
Whether or not log writes should be wrapped in a flock.
Defaults to true. If true, then for each logged message, a
non-blocking flock is attempted first, and if that fails,
then a blocking flock is attemped with a timeout.
* close_after_write ($)
Whether or not the file should be closed after each write.
This defaults to false. If set to true, then the mode will
aways be append, so that the file is not re-written for each
new message.
Note: opening and closing a file for each write is a
relatively slow process (especially on windoze systems) as
demonstrated in the performance benchmarks.
* close_after_modperl_request ($)
Only applicable for code running in a mod_perl (1 or 2)
environment and defaults to false. Set this to true if the
file should be closed after each mod_perl request which is
useful if you're using a persistent Log::Dispatch object and
intend to periodically roll your log files without having to
restart your web server each time.
* autoflush ($)
Whether or not the file should be autoflushed. This defaults
to true. If flock is true, then flushing always occurs no
matter what this is set to.
* callbacks( \& or [ \&, \&, ... ] )
This parameter may be a single subroutine reference or an
array reference of subroutine references. These callbacks
will be called in the order they are given and passed a hash
containing the following keys:
( message => $log_message, level => $log_level )
The callbacks are expected to modify the message and then
return a single scalar containing that modified message.
These callbacks will be called when either the "log" or
"log_to" methods are called and will only be applied to a
given message once.
* log_message( message => $ )
Sends a message to the appropriate output. Generally this shouldn't
be called directly but should be called through the "log()" method
(in Log::Dispatch::Output).
BENCHMARKS
FreeBSD 6.1 with a single Intel(R) Xeon(TM) CPU 3.60GHz
Measuring 10000 logs of using defaults...
Log::Dispatch::FileShared... 0.739 seconds (avg 0.00007)
Log::Dispatch::File... 0.622 seconds (avg 0.00006)
Measuring 10000 logs of using autoflush=0, flock=0...
Log::Dispatch::FileShared... 0.575 seconds (avg 0.00006)
Log::Dispatch::File... 0.574 seconds (avg 0.00006)
Measuring 10000 logs of using autoflush=1, flock=0...
Log::Dispatch::FileShared... 0.618 seconds (avg 0.00006)
Log::Dispatch::File... 0.623 seconds (avg 0.00006)
Measuring 10000 logs of using flock=1...
Log::Dispatch::FileShared... 0.739 seconds (avg 0.00007)
Measuring 10000 logs of using close_after_write=1, flock=0...
Log::Dispatch::FileShared... 1.080 seconds (avg 0.00011)
Log::Dispatch::File... 1.035 seconds (avg 0.00010)
Measuring 10000 logs of using close_after_modperl_request=1, flock=1...
Log::Dispatch::FileShared... 0.768 seconds (avg 0.00008)
MSWin32 with a Pentium CPU 3.0GHz
Measuring 10000 logs of using defaults...
Log::Dispatch::FileShared... 1.235 seconds (avg 0.00012)
Log::Dispatch::File... 1.047 seconds (avg 0.00010)
Measuring 10000 logs of using autoflush=0, flock=0...
Log::Dispatch::FileShared... 0.875 seconds (avg 0.00009)
Log::Dispatch::File... 0.907 seconds (avg 0.00009)
Measuring 10000 logs of using autoflush=1, flock=0...
Log::Dispatch::FileShared... 1.063 seconds (avg 0.00011)
Log::Dispatch::File... 1.047 seconds (avg 0.00010)
Measuring 10000 logs of using flock=1...
Log::Dispatch::FileShared... 1.251 seconds (avg 0.00013)
Measuring 10000 logs of using close_after_write=1, flock=0...
Log::Dispatch::FileShared... 74.128 seconds (avg 0.00741)
Log::Dispatch::File... 79.660 seconds (avg 0.00797)
Note how rediculously slow MSWin32 is when close_after_write=1 is
used.
SEE ALSO
Log::Dispatch::File.
AUTHOR
Craig Manley
COPYRIGHT AND LICENSE
Copyright (C) 2007 Craig Manley This library is free software; you can
redistribute it and/or modify it under the same terms as Perl itself.