Log::D...h::Dir(3pm)

💖 Log::Dispatch::Dir — the manual, but make it cute 💖

okay so bestie, you know the Log::Dispatch::Dir page? that's the one we're doing. it lives in the Log::D...h::Dir(3pm) slot of your man pages, and it's genuinely one of my faves, no cap. it logs messages into separate files in a directory, and it rotates them for you based on whatever constraints you want. let's get into it 🫶

---

✨ NAME ✨

Log::Dispatch::Dir — log messages to separate files in a directory, with rotate options. that's the whole vibe. 💅

---

🌸 VERSION 🌸

this doc describes version 0.160 of Log::Dispatch::Dir (from the Perl distribution Log-Dispatch-Dir), released on 2019-01-09. vintage but iconic. ⭐

---

🦋 SYNOPSIS 🦋

the classic setup:

use Log::Dispatch::Dir;

my $dir = Log::Dispatch::Dir->new(
    name => 'dir1',
    min_level => 'info',
    dirname => 'somedir.log',
    filename_pattern => '%Y-%m-%d-%H%M%S.%{ext}',
);
$dir->log( level => 'info', message => 'your comment\n" );

want to cap the total size? say less:

# limit total size
my $dir = Log::Dispatch::Dir->new(
    # ...
    max_size => 10*1024*1024, # 10MB
);

want to cap the number of files instead?

# limit number of files
my $dir = Log::Dispatch::Dir->new(
    # ...
    max_files => 1000,
);

orrrr you can cap by how old a file is allowed to get:

# limit oldest file
my $dir = Log::Dispatch::Dir->new(
    # ...
    max_age => 10*24*3600, # 10 days
);

---

💜 DESCRIPTION 💜

so Log::Dispatch::Dir gives you a simple object for logging into directories, sitting right inside the Log::Dispatch::* system, and it auto-rotates them based on whatever constraints you set up. every single message gets logged to its own separate file in the directory. one message, one file. main character energy, honestly.

and logging to separate files is actually so useful — like when you're dumping whole network responses (think HTTP::Response content). perfect for that. 🌈

---

👑 METHODS 👑

🎀 new(%p)

this method takes a hash of parameters, bestie. here's every option that's valid:

• name ($) — the name of the object. and note, it's not the dirname!! Required. don't get it twisted 🙈
• min_level ($) — the minimum logging level this object will accept. peep the Log::Dispatch documentation on Log Levels for more. Required.
• max_level ($) — the maximum logging level this object will accept. again, see the Log::Dispatch documentation on Log Levels. this one is not required — by default the maximum is the highest possible level, which functionally means the object has no maximum at all. slay, no ceiling 💅
• dirname ($) — the directory to write to.
• permissions ($) — if the directory doesn't already exist, these are the permissions it should be created with. optional. the argument you pass has to be a valid octal value, like 0700, or the constants from Fcntl, like S_IRUSR|S_IWUSR|S_IXUSR.

see "chmod" in perlfunc for more on the potential traps when you're passing octal values around. and most importantly bestie, remember: if you pass a string that looks like an octal value, like this:

my $mode = '0644';

then your resulting directory ends up with permissions like this:

--w----r-T

which is probably not what you want. i'm crying, please don't do that 😭

• callbacks( \& or [ \&, \&, ... ] ) — this parameter can be a single subroutine reference, or an array reference full of subroutine references. these callbacks get called in the order you give them, and each one gets passed a hash containing these keys:

( message => $log_message, level => $log_level )

the callbacks are expected to modify the message and then return a single scalar containing that modified message. they get called when either the "log" or "log_to" methods are called, and they'll only be applied to a given message once. no double-dipping 🍓

• filename_pattern ($) — the names to give each file, expressed in a pattern à la strftime(). optional. default is '%Y-%m-%d-%H%M%S.pid-%{pid}.%{ext}'. time is expressed in local time.

if a file with the same name already exists, a suffix ".1", ".2", and so on gets appended.

here are the available patterns:

• %Y — 4-digit year number, e.g. 2009
• %y — 2-digit year number, e.g. 09 for year 2009
• %m — 2-digit month, e.g. 04 for April
• %d — 2-digit day of month, e.g. 28
• %H — 2-digit hour, e.g. 01
• %M — 2-digit minute, e.g. 57
• %S — 2-digit second, e.g. 59
• %z — the time zone as hour offset from GMT
• %Z — the time zone or name or abbreviation
• %{pid} — Process ID
• %{ext} — Guessed file extension. tries to detect the appropriate file extension using File::LibMagic. for example, if the log message looks like an HTML document, then 'html'. if File::LibMagic isn't available or the type can't be detected, it defaults to 'log'.
• %% — literal '%' character

• filename_sub (\&) — a more generic mechanism than filename_pattern. if filename_sub is given, filename_pattern gets ignored. the code will be called with the same arguments as log_message() and is expected to return a filename. it will die if the code returns undef. 💀
• max_size ($) — maximum total size of files, in bytes. once that size is surpassed, the oldest files (based on ctime) get deleted. optional. default is undefined, which means unlimited.
• max_files ($) — maximum number of files. once this number is surpassed, the oldest files (based on ctime) get deleted. optional. default is undefined, which means unlimited.
• max_age ($) — maximum age of files (based on ctime), in seconds. once the age is surpassed, files older than this age get deleted. optional. default is undefined, which means unlimited.
• rotate_probability ($) — a number between 0 and 1 specifying the probability that rotate() will be called after each log_message(). it's a balance between performance and rotate-size accuracy. 1 means always rotate, 0 means never rotate. optional. default is 0.25.

🧚 log_message(message => $)

sends a message to the appropriate output. generally you shouldn't call this one directly, bestie — it should be called through the "log()" method (in Log::Dispatch::Output). iykyk 💖

---

🌟 HOMEPAGE 🌟

come visit the project's homepage at <https://metacpan.org/release/Log-Dispatch-Dir>. 🎀

---

💫 SOURCE 💫

the source repository lives at <https://github.com/perlancar/perl-Log-Dispatch-Dir>. go peek, it's giving open source excellence ✨

---

💀 BUGS 💀

please report any bugs or feature requests on the bugtracker website <https://rt.cpan.org/Public/Dist/Display.html?Name=Log-Dispatch-Dir>.

and when you submit a bug or a request, please include a test-file or a patch to an existing test-file that illustrates the bug or the desired feature. help us help you, fr fr 🙏

---

🔥 SEE ALSO 🔥

• Log::Dispatch

---

🫶 AUTHOR 🫶

perlancar <perlancar@cpan.org> — we stan 👑

---

🌸 COPYRIGHT AND LICENSE 🌸

this software is copyright (c) 2019, 2017, 2015, 2014, 2013, 2011 by perlancar@cpan.org.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, bestie!! 🎉 the footer says this came from perl v5.28.1, dated 2019-01-12 — so go forth, log to a million tiny files, rotate them responsibly, and remember: one message, one file, periodt 💅💖🦋