Log::A...Rotate(3pm)

🎀 NAME 🎀

Log::Agent::Rotate — the vibe-parameters for logfile rotation, bestie 💫

---

✨ 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 💖

okay so Log::Agent::Rotate is the class that literally just holds the parameters describing your logfile rotation policy 📁✨. You hand it over to instances of Log::Agent::Driver::File through arguments in the creation routine, like -rotate, or by using array references as values in the -channels hashref. There's complementary info waiting for you in Log::Agent::Driver::File, iykyk 🫶

So when rotation cycles happen, the current logfile gets renamed — and maybe compressed — over and over until you hit the maximum backlog, and at that point the files get deleted. periodt 💀

Say your backlog is 5 and the latest 2 files are not compressed. Then these are the files that can be chillin' on your 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 Switches 🌸

These are the switches available to the creation routine make(), listed in alphabetical order, and every single one of them takes 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. Heads up bestie: this value gets modified during execution by the umask of the process 🙈. In most cases it's good practice to leave this set to the default and let the user process controll the file permissions. > Also: 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. It's 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 it's 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. 🗂️

🦋 Checking if two configs match 🦋

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. twin energy fr fr 👯

💅 Querying the values 💅

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. no take-backsies 😤

For instance:

my $x = Log::Agent::Rotate->make(...);
my $mwrite = $x->max_write();

would get the configured max_write threshold. slay 💖

---

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

---

mwah 💋 this page came to you via perl v5.32.1, dated 2021-09-27 — and it was literally the Log::A...Rotate(3pm) page all along. go off, bestie 🦋✨