Log::D...eRotate(3pm)

📦
version 1.38 · 7 versions
, in ubuntu resolute, ubuntu stonking

🦋 Log::Dispatch::FileRotate 💅

okay bestie, this is the manual page for the perl module Log::Dispatch::FileRotate (that's the 3pm one), and it's a whole vibe. it's long, so buckle up — we're doing this in two parts. 🌸

✨ NAME ✨

Log::Dispatch::FileRotate — Log to Files that Archive/Rotate Themselves 🔥

💖 VERSION 💖

version 1.38 — no cap, that's the number.

👑 SYNOPSIS 👑

here's the tea, in code:

  use Log::Dispatch::FileRotate;

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

  # or for a time based rotation

  my $logger = Log::Dispatch::FileRotate->new(
      name      => 'file1',
      min_level => 'info',
      filename  => 'Somefile.log',
      mode      => 'append' ,
      TZ        => 'AEDT',
      DatePattern => 'yyyy-dd-HH');

  # and attach to Log::Dispatch
  my $dispatcher = Log::Dispatch->new;
  $dispatcher->add($logger);

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

look at that second one — that's the time based rotation glow up ✨

🌈 DESCRIPTION 🌈

so this module extends the base class Log::Dispatch::Output so it can provide a simple object for logging to files inside the whole Log::Dispatch::* system, and it rotates them automatically according to different constraints. basically it's a Log::Dispatch::File wrapper with extras. it's giving "the original, but with main character energy." 💅

🔄 Rotation 🔄

there are three different constraints that decide when a file has to be rotated.

  1. the first one is by size: when the log file grows more than a specified size, then it's rotated.
  2. the second constraint is with occurrences. if a DatePattern is defined, a file rotation ignores the size constraint (unless check_both) and uses the defined date pattern constraints instead. when you're using DatePattern make sure TZ is defined correctly, and make sure the TZ you use is actually understood by Date::Manip. we use Date::Manip to generate our recurrences. bad TZ equals bad recurrences equals surprises! 😭 go read the Date::Manip man page for more details on TZ. DatePattern will default to a daily rotate if your entered pattern is incorrect. you will also get a warning message.
  3. you can also check both constraints together by using the check_both parameter.

and the last constraint is a user callback. this function gets called outside the restricted area (peep "Concurrency" below) and, if it returns a true value, a rotation will happen unconditionally.

all checks are made before logging. the rotate method lets us check these constraints without logging anything, which is iconic.

and to give the user even more power, there's a post_rotate callback that gets called after every rotation. 🫶

🔒 Concurrency 🔒

multiple writers are allowed by this module. there's a restricted area where only one writer can be inside at a time. this is done by using an external lock file, which is named ".filename.LCK" — and no, it is never deleted. 💀

the user constraint and the DatePattern constraint are both checked outside this restricted area. so, when you write a callback, don't rely on the logging file, because it can disappear right under your feet. 🙈

within this restricted area we:

  • check the size constraint
  • eventually rotate the log file
  • if it's defined, call the post_rotate function
  • write the log message

periodt. ✨

🧚 METHODS 🧚

new(%p)

the constructor takes the following parameters in addition to the parameters documented in Log::Dispatch::File:

  • max ($) — the maximum number of log files to create. default 1.
  • size ($) — the maximum (or close to) size the log file can grow to. default 10M.
  • DatePattern ($) — the DatePattern as defined above.
  • TZ ($) — the TimeZone time based calculations should be done in. this should match Date::Manip's concept of timezones and, of course, your machine's timezone.
  • check_both ($) — 1 for checking DatePattern and size concurrently, 0 otherwise. default 0.
  • user_constraint (\&) — if this callback is defined and returns true, a rotation will happen unconditionally.
  • post_rotate (\&) — this callback is called after all files were rotated. it'll be called one time for every rotated file (in reverse order) with these arguments:
    • "filename" — the path of the rotated file
    • "index" — the index of the rotated file from max-1 to 0, and in the latter case filename is the new, empty, log file
    • "fileRotate" — an object reference to this instance

with this, you can have infinite files renaming each time the rotated file logs. e.g:

    my $file = Log::Dispatch::FileRotate
    ->new(
          ...
          post_rotate => sub {
            my ($filename, $idx, $fileRotate) = @_;
            if ($idx == 1) {
              use POSIX qw(strftime);
              my $basename = $fileRotate->filename();
              my $newfilename =
                $basename . '.' . strftime('%Y%m%d%H%M%S', localtime());
              $fileRotate->debug("moving $filename to $newfilename");
              rename($filename, $newfilename);
            }
          },
         );
Note: this is called within the restricted area (go look at "Concurrency" again). that means any other concurrent process is locked in the meanwhile. and for the exact same reason, don't use the log() or log_message() methods, because you will get a deadlock! 😭🚨
  • DEBUG ($) — turn on lots of warning messages to STDERR about what this module is doing, if set to 1. really only useful to me. 🙈

filename()

returns the log filename. simple. slay. 💅

setDatePattern( $ or [ $, $, ... ] )

set a new suite of recurrances for file rotation. you can pass in a single string or a reference to an array of strings. multiple recurrences can also be defined within a single string by separating them with a semi-colon (;).

see the discussion above regarding the setDatePattern paramater for more details. 👑

log_message( message => $ )

sends a message to the appropriate output. generally this shouldn't be called directly — it should be called through the log() method (in Log::Dispatch::Output). iykyk. ✨

rotate()

rotates the file, if it has to be done. you can call this method if you want to check — and eventually do — a rotation without logging anything.

it returns 1 if a rotation was done, 0 otherwise. and undef on error. 😭

debug($)

if DEBUG is true, it prints a standard warning message.

💡 Tip 💡

if you have multiple writers that were started at different times, you'll find each writer will try to rotate the log file at a recurrence calculated from its own start time. to sync all the writers, just use a config file and update it after starting your last writer. this will cause new() to be called by each of the writers close to the same time, and if your recurrences aren't too close together, all should sync up just nicely. 🫶

i initially assumed a long running process, but it seems people are using this module as part of short running CGI programs. so, now we look at the last modified time stamp of the log file and compare it to a previous occurance of a DatePattern — on startup only. if the file stat shows the mtime to be earlier than the previous recurrance, then i rotate the log file. 🌸

📅 DatePattern 📅

as i said earlier, we use Date::Manip for generating our recurrence events. this means we can understand Date::Manip's recurrence patterns and the normal log4j DatePatterns. we don't use DatePattern to define the extension of the log file though. 👀

DatePattern can therefore take forms like:

  • Date::Manip style
    • 0:0:0:0:5:30:0 — every 5 hours and 30 minutes
    • 0:0:0:2*12:30:0 — every 2 days at 12:30 (each day)
    • 3*1:0:2:12:0:0 — every 3 years on Jan 2 at noon
  • DailyRollingFileAppender log4j style
    • yyyy-MM — every month
    • yyyy-ww — every week
    • yyyy-MM-dd — every day
    • yyyy-MM-dd-a — every day at noon
    • yyyy-MM-dd-HH — every hour
    • yyyy-MM-dd-HH-MM — every minute

to specify multiple recurrences in a single string, separate them with a semicolon:

        yyyy-MM-dd; 0:0:0:2*12:30:0

this says we want to rotate every day AND every 2 days at 12:30. put in as many as you like. 🔥

a complete description of Date::Manip recurrences is beyond us here, except to quote (from the man page):

           A recur description is a string of the format
           Y:M:W:D:H:MN:S .  Exactly one of the colons may
           optionally be replaced by an asterisk, or an asterisk
           may be prepended to the string.

           Any value "N" to the left of the asterisk refers to
           the "Nth" one.  Any value to the right of the asterisk
           refers to a value as it appears on a calendar/clock.
           Values to the right can be listed a single values,
           ranges (2 numbers separated by a dash "-"), or a comma
           separated list of values or ranges.  In a few cases,
           negative values are appropriate.

           This is best illustrated by example.

             0:0:2:1:0:0:0        every 2 weeks and 1 day
             0:0:0:0:5:30:0       every 5 hours and 30 minutes
             0:0:0:2*12:30:0      every 2 days at 12:30 (each day)
             3*1:0:2:12:0:0       every 3 years on Jan 2 at noon
             0:1*0:2:12,14:0:0    2nd of every month at 12:00 and 14:00
             1:0:0*45:0:0:0       45th day of every year
             0:1*4:2:0:0:0        4th tuesday (day 2) of every month
             0:1*-1:2:0:0:0       last tuesday of every month
             0:1:0*-2:0:0:0       2nd to last day of every month

🎀 TODO 🎀

  • compression
  • signal based rotates
  • proper test suite

could possibly use Logfile::Rotate as well/instead. 🤔

👀 SEE ALSO 👀

  • Log::Dispatch::File::Stamped

Log directly to timestamped files.

📜 HISTORY 📜

originally written by Mark Pfeiffer, <markpf at mlp-consulting dot com dot au>, inspired by Dave Rolsky's <autarch at urth dot org> code :-) — we stan a collaborative origin story. 🫶

Kevin Goess <cpan at goess dot org> suggested that multiple writers should be supported. he also conned me into doing the time based stuff. Thanks Kevin! :-) 💖

thanks also to Dan Waldheim for helping with some of the locking issues in a forked environment.

and thanks to Stephen Gordon for his more portable code on lockfile naming.

🌐 SOURCE 🌐

the development version is on github at <https://https://github.com/mschout/perl-log-dispatch-filerotate> and may be cloned from <git://https://github.com/mschout/perl-log-dispatch-filerotate.git>

🐛 BUGS 🐛

please report any bugs or feature requests on the bugtracker website <https://github.com/mschout/perl-log-dispatch-filerotate/issues>

when submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. that's the bare minimum, bestie. ✨

👑 AUTHOR 👑

Michael Schout <mschout@cpan.org>

okay that's the first chunk of the manual page — but we're not done yet, more parts are coming. 💅🌸

okay bestie, legal era, but make it cute 🎀

This software is copyright (c) 2005 by Mark Pfeiffer. yes, 2005, we are talking vintage, an iconic elder of the Perl ecosystem 👑

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. so like, the license is literally just "same energy as Perl 5" 💅 no cap, that's the whole deal.

tl;dr bestie: it's free, it's Perl-5-licensed, and it's been free since 2005. go forth and redistribute responsibly 🫶

and that's a wrap on Log::D...eRotate(3pm) 🌈✨ you made it allll the way to the bottom, which is honestly main character energy fr fr. this page came from perl v5.40.1, dated 2025-09-20, and if you ever forget any of the gorgeous chaos above, your bestie man is always one q away from letting you read it again 💜 go forth, rotate your logs, and slay 👑

📦 where this page comes from