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

VERSION
    This document describes version 0.160 of Log::Dispatch::Dir (from Perl
    distribution Log-Dispatch-Dir), released on 2019-01-09.

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).

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.

SEE ALSO
    Log::Dispatch

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2019, 2017, 2015, 2014, 2013, 2011 by
    perlancar@cpan.org.

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

