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