Log::Dispatch::Dir(3) Log messages to separate files in a directory, with rotate options

VERSION

This document describes version 0.14 of Log::Dispatch::Dir (from Perl distribution Log-Dispatch-Dir), released on 2015-12-16.

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:

  • 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'.
  • 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 <https://metacpan.org/release/Log-Dispatch-Dir>.

SOURCE

Source repository is at <https://github.com/perlancar/perl-Log-Dispatch-Dir>.

BUGS

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

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.

AUTHOR

perlancar <[email protected]>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by [email protected]

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