NAME¶
Log::Agent::Rotate - parameters for logfile rotation
SYNOPSIS¶
require Log::Agent::Rotate;
my $policy = Log::Agent::Rotate->make(
-backlog => 7,
-unzipped => 2,
-is_alone => 0,
-max_size => 100_000,
-max_time => "1w",
-file_perm => 0666
);
DESCRIPTION¶
The "Log::Agent::Rotate" class holds the parameters describing the
logfile rotation policy, and is meant to be supplied to instances of
"Log::Agent::Driver::File" via arguments in the creation routine,
such as "-rotate", or by using array references as values in the
"-channels" hashref: See complementary information in
Log::Agent::Driver::File.
As rotation cycles are performed, the current logfile is renamed, and possibly
compressed, until the maximum backlog is reached, at which time files are
deleted. Assuming a backlog of 5 and that the latest 2 files are not
compressed, the following files can be present on the filesystem:
logfile # the current logfile
logfile.0 # most recently renamed logfile
logfile.1
logfile.2.gz
logfile.3.gz
logfile.4.gz # oldest logfile, unlinked next cycle
The following
switches are available to the creation routine
make(), listed in alphabetical order, all taking a single integer value
as argument:
- backlog
- The total amount of old logfiles to keep, besides the current logfile.
Defaults to 7.
- file_perm
- The file permissions, given as an octal integer value, to supply to
sysopen() during file creation. This value is modified during
execution by the umask of the process. In most cases, it is good practice
to leave this set to the default and let the user process controll the
file permissions.
Defaults to 0666.
- is_alone
- The argument is a boolean stating whether the program writing to the
logfile will be the only one or not. This is a hint that drives some
optimizations, but it is up to the program to guarantee that noone
else will be able to write to or unlink the current logfile when set to
true.
Defaults to false.
- max_size
- The maximum logfile size. This is a threshold, which will cause a logfile
rotation cycle to be performed, when crossed after a write to the file. If
set to 0, this threshold is not checked.
Defaults to 1 megabyte.
- max_time
- The maximum time in seconds between the moment we opened the file and the
next rotation cycle occurs. This threshold is only checked after a write
to the file.
The value can also be given as a string, postfixed by one of the following
letters to specify the period unit (e.g. "3w"):
Letter Unit
------ -------
m minutes
h hours
d days
d days
w weeks
M months (30 days of 24 hours)
y years
Defaults to 0, meaning it is not checked.
- max_write
- The maximum amount of data we can write to the logfile. Like
"max_size", this is a threshold, which is only checked after a
write to the logfile. This is not the total logfile size: if several
programs write to the same logfile and "max_size" is not used,
then the logfiles may never be rotated at all if none of the programs
write at least "max_write" bytes to the logfile before exiting.
Defaults to 0, meaning it is not checked.
- single_host
- The argument is a boolean stating whether the access to the logfiles will
be made from one single host or not. This is a hint that drives some
optimizations, but it is up to the program to guarantee that it is
accurately set.
Defaults to false, which is always a safe value.
- unzipped
- The amount of old logfiles, amongst the most recent ones, that should not
be compressed but be kept as plain files.
Defaults to 1.
To test whether two configurations are strictly identical, use
is_same(),
as in:
print "identical\n" if $x->is_same($y);
where both $x and $y are "Log::Agent::Rotate" objects.
All the aforementioned switches also have a corresponding querying routine that
can be issued on instances of the class to get their value. It is not possible
to modify those attributes.
For instance:
my $x = Log::Agent::Rotate->make(...);
my $mwrite = $x->max_write();
would get the configured
max_write threshold.
AUTHORS¶
Originally written by Raphael Manfredi <Raphael_Manfredi@pobox.com>,
currently maintained by Mark Rogaski <mrogaski@cpan.org>.
Thanks to Chris Meshkin for his suggestions on file permissions.
SEE ALSO¶
Log::Agent(3),
Log::Agent::Driver::File(3),
Log::Agent::Rotate::File(3).