--- name: "Log::Dispatch::Dir" section: "3pm" platform: "linux" package: "liblog-dispatch-dir-perl" version: "0.160-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Log::Dispatch::Dir" --- # Log::Dispatch::Dir(3pm) Log messages to separate files in a directory, with rotate options ## NAME Log::Dispatch::Dir - Log messages to separate files in a directory, with rotate options ## VERSION This document describes version 0.160 of Log::Dispatch::Dir (from Perl distribution Log-Dispatch-Dir), released on 2019-01-09. ## SYNOPSIS ``` 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" ); # limit total size my $dir = Log::Dispatch::Dir->new( # ... max_size => 10*1024*1024, # 10MB ); # limit number of files my $dir = Log::Dispatch::Dir->new( # ... max_files => 1000, ); # limit oldest file my $dir = Log::Dispatch::Dir->new( # ... max_age => 10*24*3600, # 10 days ); ``` ## DESCRIPTION This module provides a simple object for logging to directories under the Log::Dispatch::\* system, and automatically rotating them according to different constraints. Each message will be logged to a separate file the directory. Logging to separate files can be useful for example when dumping whole network responses (like HTTP::Response content). ## METHODS ### new(%p) This method takes a hash of parameters. The following options are valid: - • name ($) The name of the object (not the dirname!). Required. - • min\_level ($) The minimum logging level this object will accept. See the Log::Dispatch documentation on Log Levels for more information. Required. - • max\_level ($) The maximum logging level this obejct will accept. See the Log::Dispatch documentation on Log Levels for more information. This is not required. By default the maximum is the highest possible level (which means functionally that the object has no maximum). - • dirname ($) The directory to write to. - • permissions ($) If the directory does not already exist, the permissions that it should be created with. Optional. The argument passed must be a valid octal value, such as 0700 or the constants available from Fcntl, like S\_IRUSR\|S\_IWUSR\|S\_IXUSR. See "chmod" in perlfunc for more on potential traps when passing octal values around. Most importantly, remember that if you pass a string that looks like an octal value, like this: ``` my $mode = '0644'; ``` Then the resulting directory will end up with permissions like this: ``` --w----r-T ``` which is probably not what you want. - • callbacks( \\& or \[ \\&, \\&, ... \] ) This parameter may be a single subroutine reference or an array reference of subroutine references. These callbacks will be called in the order they are given and passed a hash containing the following 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. These callbacks will be called when either the `"log"` or `"log_to"` methods are called and will only be applied to a given message once. - • filename\_pattern ($) Names to give to each file, expressed in pattern a la **strftime()**'s. Optional. Default is '%Y-%m-%d-%H%M%S.pid-%{pid}.%{ext}'. Time is expressed in local time. If file of the same name already exists, a suffix ".1", ".2", and so on will be appended. Available pattern: - %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 Try to detect appropriate file extension using File::LibMagic. For example, if log message looks like an HTML document, then 'html'. If File::LibMagic is not available or type cannot be detected, defaults to 'log'. - %% - literal '%' character - • filename\_sub (\\&) A more generic mechanism for **filename\_pattern**. If **filename\_sub** is given, **filename\_pattern** will be ignored. The code will be called with the same arguments as **log\_message()** and is expected to return a filename. Will die if code returns undef. - • max\_size ($) Maximum total size of files, in bytes. After the size is surpassed, oldest files (based on ctime) will be deleted. Optional. Default is undefined, which means unlimited. - • max\_files ($) Maximum number of files. After this number is surpassed, oldest files (based on ctime) will be deleted. Optional. Default is undefined, which means unlimited. - • max\_age ($) Maximum age of files (based on ctime), in seconds. After the age is surpassed, files older than this age will be deleted. Optional. Default is undefined, which means unlimited. - • rotate\_probability ($) A number between 0 and 1 which specifies the probability that **rotate()** will be called after each **log\_message()**. This is 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 this shouldn't be called directly but should be called through the `"log()"` method (in Log::Dispatch::Output). ## HOMEPAGE Please visit the project's homepage at \. ## SOURCE Source repository is at \. ## BUGS Please report any bugs or feature requests on the bugtracker website \ 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. ## SEE ALSO Log::Dispatch ## AUTHOR perlancar \ ## 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.