NAME Log::Dispatch::Dir - Log messages to separate files in a directory, with rotate options VERSION version 0.07 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.%{pid}.html', ); $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}'. 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 AUTHOR Steven Haryanto COPYRIGHT AND LICENSE This software is copyright (c) 2011 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.