The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Log-Rolling-1.02
River stage zero No dependents
++
/ Log::Rolling

NAME

Log::Rolling - Log to simple and self-limiting logfiles.

VERSION

Version 1.02

SYNOPSIS

Log::Rolling is a module designed to give programs lightweight, yet powerful logging facilities. One of the primary benefits is that, while the logs can be infinitely long and handled by something like logrotate, the module is capable of limiting the number of lines in the log in a fashion where by the oldest lines roll off to keep the size constant at the maximum allowed size, if so tuned.

This module is particularly useful when you need to keep logs around for a certain amount of available data, but do not need to incur the complexity and overhead of using something as heavy as logrotate or other methods of archiving. Since the rolling is built into the logging facility, no extra cron jobs or the like are necessary.

Data is buffered throughout the run of a program with each call to entry(). Once commit() is called, that buffer is written to the log file, and the log buffer is cleared. The commit() method may be called as many times as necessary; however, it is best to do so as few times as required due to the overhead of file operations involved in rolling the log--hence the reason the entries are stored in memory until manually committed in the first place.

     use Log::Rolling;
     my $log = Log::Rolling->new('/path/to/logfile.txt');

     # Define the maximum log size in lines.  Default is 0 (infinite).
     $log->max_size(50000);

     # Add a log entry line.
     $log->entry("Log information string here...");

     # Commit all log entry lines in memory to file and roll the log lines
     # to accomodate max_size.
     $log->commit;

METHODS

new()

     my $log = Log::Rolling->new('/path/to/logfile.txt'); 
     my $log = Log::Rolling->new(log_file => '/path/to/file',
                                 max_size => 5000,
                                 wait_attempts => 30,
                                 wait_interval => 1,
                                 mode => 0600
                                 pid => 1);

If no logfile is given, or if the logfile is unusable, the constructor returns false (0).

log_file()

This method defines the path of the logfile. Returns the value of the logfile, or false (0) if the logfile is unusable.

max_size()

This method sets the maximum size of the logfile in lines. The size is infinite (0) unless this method is called, or unless the size was defined using new(). Returns the maximum size.

wait_attempts()

This method sets the maximum number of attempts to wait for a lock on the logfile. Returns the maximum wait attempt setting.

wait_interval()

This method sets the interval in seconds between attempts to wait for a lock on the logfile. Returns the wait interval setting.

mode()

This method sets the file mode to be used when creating the log file if the file does not yet exist. The value should be an octal value (e.g., 0644). Returns the file mode.

pid()

This method sets whether the process ID will be recorded in the log entry. Enable PID with 1, disable with 0. Returns the value of the setting.

entry()

Adds an entry to the log file accumulation buffer in memory. No entries are ever written to disk unless and until commit() is called.

commit()

Commits the current log file data in memory to the actual file on disk, and clears the log accumulation buffer.

roll()

This method rolls the oldest entries out of the logfile and leaves only up to max_size lines (or less, if the contents are not that long) within the logfile. Returns true (1) if log was successfully rolled, or false (0) if it was not. This method is not meant to be called independantly. Doing so will simply return false (0).

clear()

This method clears the buffered log entries without writing them to file, should it be deemed necessary to "revoke" log entries already made but not yet committed to file. Returns true (1).

AUTHOR

Mark Luljak, <fairlite at fairlite.com>

Fairlight Consulting - http://www.fairlite.com/

BUGS

Please report any bugs or feature requests to bug-log-selfmaintaining at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Log-Rolling. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Log::Rolling

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2008-2009 Mark Luljak, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.