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.

           This option has no effect on Win32 systems.

           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.

COPYRIGHT

       Copyright (c) 2000, Raphael Manfredi.

       Copyright (c) 2002-2015, Mark Rogaski; all rights reserved.

       This program is free software; you can redistribute it and/or modify it under the terms of
       the Artistic License 2.0, a copy of which can be found with perl.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the Artistic License 2.0 for more details.

       http://www.perlfoundation.org/artistic_license_2_0

SEE ALSO

       Log::Agent(3), Log::Agent::Driver::File(3), Log::Agent::Rotate::File(3).