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

FreeBSD Manual Pages

  
 
  

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

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:

       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:

	    --w----r-T

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

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

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | HOMEPAGE | SOURCE | BUGS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Log::Dispatch::Dir&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help