Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Log::Dispatch::Dir(3) User Contributed Perl DocumentationLog::Dispatch::Dir(3)

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

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

	   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

       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.

       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

       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


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

       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

       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) 2019, 2017, 2015,	2014, 2013, 2011 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.

perl v5.32.0			  2019-01-09		 Log::Dispatch::Dir(3)


Want to link to this manual page? Use this URL:

home | help