1NAME
2 Log::Dispatch::Dir - Log messages to separate files in a directory, with
3 rotate options
4
5VERSION
6 This document describes version 0.160 of Log::Dispatch::Dir (from Perl
7 distribution Log-Dispatch-Dir), released on 2019-01-09.
8
9SYNOPSIS
10 use Log::Dispatch::Dir;
11
12 my $dir = Log::Dispatch::Dir->new(
13 name => 'dir1',
14 min_level => 'info',
15 dirname => 'somedir.log',
16 filename_pattern => '%Y-%m-%d-%H%M%S.%{ext}',
17 );
18 $dir->log( level => 'info', message => 'your comment\n" );
19
20 # limit total size
21 my $dir = Log::Dispatch::Dir->new(
22 # ...
23 max_size => 10*1024*1024, # 10MB
24 );
25
26 # limit number of files
27 my $dir = Log::Dispatch::Dir->new(
28 # ...
29 max_files => 1000,
30 );
31
32 # limit oldest file
33 my $dir = Log::Dispatch::Dir->new(
34 # ...
35 max_age => 10*24*3600, # 10 days
36 );
37
38DESCRIPTION
39 This module provides a simple object for logging to directories under
40 the Log::Dispatch::* system, and automatically rotating them according
41 to different constraints. Each message will be logged to a separate file
42 the directory.
43
44 Logging to separate files can be useful for example when dumping whole
45 network responses (like HTTP::Response content).
46
47METHODS
48 new(%p)
49 This method takes a hash of parameters. The following options are valid:
50
51 * name ($)
52
53 The name of the object (not the dirname!). Required.
54
55 * min_level ($)
56
57 The minimum logging level this object will accept. See the
58 Log::Dispatch documentation on Log Levels for more information.
59 Required.
60
61 * max_level ($)
62
63 The maximum logging level this obejct will accept. See the
64 Log::Dispatch documentation on Log Levels for more information. This
65 is not required. By default the maximum is the highest possible
66 level (which means functionally that the object has no maximum).
67
68 * dirname ($)
69
70 The directory to write to.
71
72 * permissions ($)
73
74 If the directory does not already exist, the permissions that it
75 should be created with. Optional. The argument passed must be a
76 valid octal value, such as 0700 or the constants available from
77 Fcntl, like S_IRUSR|S_IWUSR|S_IXUSR.
78
79 See "chmod" in perlfunc for more on potential traps when passing
80 octal values around. Most importantly, remember that if you pass a
81 string that looks like an octal value, like this:
82
83 my $mode = '0644';
84
85 Then the resulting directory will end up with permissions like this:
86
87 --w----r-T
88
89 which is probably not what you want.
90
91 * callbacks( \& or [ \&, \&, ... ] )
92
93 This parameter may be a single subroutine reference or an array
94 reference of subroutine references. These callbacks will be called
95 in the order they are given and passed a hash containing the
96 following keys:
97
98 ( message => $log_message, level => $log_level )
99
100 The callbacks are expected to modify the message and then return a
101 single scalar containing that modified message. These callbacks will
102 be called when either the "log" or "log_to" methods are called and
103 will only be applied to a given message once.
104
105 * filename_pattern ($)
106
107 Names to give to each file, expressed in pattern a la strftime()'s.
108 Optional. Default is '%Y-%m-%d-%H%M%S.pid-%{pid}.%{ext}'. Time is
109 expressed in local time.
110
111 If file of the same name already exists, a suffix ".1", ".2", and so
112 on will be appended.
113
114 Available pattern:
115
116 %Y - 4-digit year number, e.g. 2009
117 %y - 2-digit year number, e.g. 09 for year 2009
118 %m - 2-digit month, e.g. 04 for April
119 %d - 2-digit day of month, e.g. 28
120 %H - 2-digit hour, e.g. 01
121 %M - 2-digit minute, e.g. 57
122 %S - 2-digit second, e.g. 59
123 %z - the time zone as hour offset from GMT
124 %Z - the time zone or name or abbreviation
125 %{pid} - Process ID
126 %{ext} - Guessed file extension
127 Try to detect appropriate file extension using
128 File::LibMagic. For example, if log message looks like an
129 HTML document, then 'html'. If File::LibMagic is not
130 available or type cannot be detected, defaults to 'log'.
131
132 %% - literal '%' character
133
134 * filename_sub (\&)
135
136 A more generic mechanism for filename_pattern. If filename_sub is
137 given, filename_pattern will be ignored. The code will be called
138 with the same arguments as log_message() and is expected to return a
139 filename. Will die if code returns undef.
140
141 * max_size ($)
142
143 Maximum total size of files, in bytes. After the size is surpassed,
144 oldest files (based on ctime) will be deleted. Optional. Default is
145 undefined, which means unlimited.
146
147 * max_files ($)
148
149 Maximum number of files. After this number is surpassed, oldest
150 files (based on ctime) will be deleted. Optional. Default is
151 undefined, which means unlimited.
152
153 * max_age ($)
154
155 Maximum age of files (based on ctime), in seconds. After the age is
156 surpassed, files older than this age will be deleted. Optional.
157 Default is undefined, which means unlimited.
158
159 * rotate_probability ($)
160
161 A number between 0 and 1 which specifies the probability that
162 rotate() will be called after each log_message(). This is a balance
163 between performance and rotate size accuracy. 1 means always rotate,
164 0 means never rotate. Optional. Default is 0.25.
165
166 log_message(message => $)
167 Sends a message to the appropriate output. Generally this shouldn't be
168 called directly but should be called through the "log()" method (in
169 Log::Dispatch::Output).
170
171HOMEPAGE
172 Please visit the project's homepage at
173 <https://metacpan.org/release/Log-Dispatch-Dir>.
174
175SOURCE
176 Source repository is at
177 <https://github.com/perlancar/perl-Log-Dispatch-Dir>.
178
179BUGS
180 Please report any bugs or feature requests on the bugtracker website
181 <https://rt.cpan.org/Public/Dist/Display.html?Name=Log-Dispatch-Dir>
182
183 When submitting a bug or request, please include a test-file or a patch
184 to an existing test-file that illustrates the bug or desired feature.
185
186SEE ALSO
187 Log::Dispatch
188
189AUTHOR
190 perlancar <perlancar@cpan.org>
191
192COPYRIGHT AND LICENSE
193 This software is copyright (c) 2019, 2017, 2015, 2014, 2013, 2011 by
194 perlancar@cpan.org.
195
196 This is free software; you can redistribute it and/or modify it under
197 the same terms as the Perl 5 programming language system itself.
198
199