Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Log::Dispatch::FileShaUser3Contributed Perl DocumeLog::Dispatch::FileShared(3)

NAME
       Log::Dispatch::FileShared - Log::Dispatch 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
       o   new(%p)

	   This	method takes a hash of parameters.  The	following options are
	   valid:

	   o	   name	($)

		   The name of the object (not the filename!).	Required.

	   o	   min_level ($)

		   The minimum logging level this object will accept.  See the
		   Log::Dispatch documentation on Log Levels for more
		   information.	 Required.

	   o	   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).

	   o	   filename ($)

		   The filename	to be opened for appending.

	   o	   mode	($)

		   The mode the	file should be opened with.  Valid options are
		   '>' (write) and '>>'	(append).  The default is '>>'
		   (append).

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

	   o	   umask ($)

		   The optional	umask to use when the file is created for the
		   first time.

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

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

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

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

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

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

perl v5.32.1			  2007-02-03	  Log::Dispatch::FileShared(3)

NAME | SYNOPSIS | DESCRIPTION | OTHER SIMILAR CLASSES | METHODS | BENCHMARKS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Log::Dispatch::FileShared&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help