NAME

       Log::Dispatch::Dir - Log messages to separate files in a directory, with rotate options

VERSION

       version 0.11

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

AUTHOR

       Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2013 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.

perl v5.18.1                                       2013-09-09                            Log::Dispatch::Dir(3pm)