Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  LOG::DISPATCH::DIR (3)

.ds Aq ’


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



This document describes version 0.14 of Log::Dispatch::Dir (from Perl distribution Log-Dispatch-Dir), released on 2015-12-16.


    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


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



This method takes a hash of parameters. The following options are valid:
o name ($)

The name of the object (not the dirname!). Required.

o min_level ($)

The minimum logging level this object will accept. See the Log::Dispatch documentation on Log Levels for more information. Required.

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

o dirname ($)

The directory to write to.

o 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:


which is probably not what you want.

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

o filename_pattern ($)

Names to give to each file, expressed in pattern a la strftime()’s. Optional. Default is ’{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

o filename_sub (\&)

A more generic mechanism for <B>filename_patternB>. If <B>filename_subB> is given, <B>filename_patternB> 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.

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

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

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

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




Please visit the project’s homepage at <>.


Source repository is at <>.


Please report any bugs or feature requests on the bugtracker website <>

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.


perlancar <>


This software is copyright (c) 2015 by

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

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 LOG::DISPATCH::DIR (3) 2015-12-16

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.