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