NAME

Log::Dispatch::FileRotate - Log to files that archive/rotate themselves

SYNOPSIS

use Log::Dispatch::FileRotate;

my $file = Log::Dispatch::FileRotate->new( name      => 'file1',
                                     min_level => 'info',
                                     filename  => 'Somefile.log',
                                     mode      => 'append' ,
                                     size      => 10,
                                     max       => 6,
                                    );

$file->log( level => 'info', message => "your comment\n" );

DESCRIPTION

This module provides a simple object for logging to files under the Log::Dispatch::* system, and automatically rotating them according to different constraints. This is basically a Log::Dispatch::File wrapper with additions. To that end the arguments

name, min_level, filename and  mode

behave the same as Log::Dispatch::File. So see its man page (perldoc Log::Dispatch::File)

The arguments size and max specify the maximum size (in meg) and maximum number of log files created. The size defaults to 10M and the max number of files defaults to 1.

Later I'll provide time based constaints as well.

We handle multiple writers using flock().

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.

• -- size ($)

  The maxium (or close to) size the log file can grow too.

• -- max ($)

  The maxium number of log files to create.

• -- min_level ($)

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

• -- max_level ($)

  The maximum logging level this obejct will accept. See the Log::Dispatch documentation 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 writing. This is the base name. Rotated log files will be renamed filename.1 thru to filename.max. Where max is the paramater defined above.

• -- mode ($)

  The mode the file should be opened with. Valid options are 'write', '>', 'append', '>>', or the relevant constants from Fcntl. The default is 'write'.

• -- autoflush ($)

  Whether or not the file should be autoflushed. This defaults to true.

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

TODO

compression, time based rotates, signal based rotates, proper test suite

Could possibly use Logfile::Rotate as well/instead.

AUTHOR

Mark Pfeiffer, <markpf@mlp-consulting.com.au> inspired by Dave Rolsky's, <autarch@urth.org>, code :-)

Kevin Goess <kevin@goess.org> suggested multiple writers should be supported. Thanks Kevin.