NAME¶
Log::Dispatch::Dir - Log messages to separate files in a directory, with rotate
options
VERSION¶
This document describes version 0.12 of Log::Dispatch::Dir (from Perl
distribution Log-Dispatch-Dir), released on 2014-05-17.
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).
SEE ALSO¶
Log::Dispatch
HOMEPAGE¶
Please visit the project's homepage at
<
https://metacpan.org/release/Log-Dispatch-Dir>.
SOURCE¶
Source repository is at
<
https://github.com/sharyanto/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¶
Steven Haryanto <stevenharyanto@gmail.com>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2014 by Steven Haryanto.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.