1Log::Dispatch::FileRotaUtsee(r3)Contributed Perl DocumenLtoagt:i:oDnispatch::FileRotate(3)
2
6 Log::Dispatch::FileRotate - Log to Files that Archive/Rotate Themselves
7
9 version 1.38
10
12 use Log::Dispatch::FileRotate;
13 my $logger = Log::Dispatch::FileRotate->new(
15 name => 'file1',
16 min_level => 'info',
17 filename => 'Somefile.log',
18 mode => 'append' ,
19 size => 10*1024*1024,
20 max => 6);
21 # or for a time based rotation
23 my $logger = Log::Dispatch::FileRotate->new(
25 name => 'file1',
26 min_level => 'info',
27 filename => 'Somefile.log',
28 mode => 'append' ,
29 TZ => 'AEDT',
30 DatePattern => 'yyyy-dd-HH');
31 # and attach to Log::Dispatch
33 my $dispatcher = Log::Dispatch->new;
34 $dispatcher->add($logger);
35 $dispatcher->log( level => 'info', message => "your comment\n" );
37
39 This module extends the base class Log::Dispatch::Output to provides a
40 simple object for logging to files under the Log::Dispatch::* system,
41 and automatically rotating them according to different constraints.
42 This is basically a Log::Dispatch::File wrapper with additions.
43 Rotation
45 There are three different constraints which decide when a file must be
46 rotated.
47 The first is by size: when the log file grows more than a specified
49 size, then it's rotated.
50 The second constraint is with occurrences. If a "DatePattern" is
52 defined, a file rotation ignores size constraint (unless "check_both")
53 and uses the defined date pattern constraints. When using "DatePattern"
54 make sure TZ is defined correctly and that the TZ you use is understood
55 by Date::Manip. We use Date::Manip to generate our recurrences. Bad TZ
56 equals bad recurrences equals surprises! Read the Date::Manip man page
57 for more details on TZ. "DatePattern" will default to a daily rotate if
58 your entered pattern is incorrect. You will also get a warning message.
59 You can also check both constraints together by using the "check_both"
61 parameter.
62 The latter constraint is a user callback. This function is called
64 outside the restricted area (see "Concurrency") and, if it returns a
65 true value, a rotation will happen unconditionally.
66 All check are made before logging. The "rotate" method leaves us check
68 these constraints without logging anything.
69 To let more power at the user, a "post_rotate" callback it'll call
71 after every rotation.
72 Concurrency
74 Multiple writers are allowed by this module. There is a restricted area
75 where only one writer can be inside. This is done by using an external
76 lock file, which name is "".filename.LCK"" (never deleted).
77 The user constraint and the "DatePattern" constraint are checked
79 outside this restricted area. So, when you write a callback, don't rely
80 on the logging file because it can disappear under your feet.
81 Within this restricted area we:
83 • check the size constraint
85 • eventually rotate the log file
87 • if it's defined, call the "post_rotate" function
89 • write the log message
91
93 new(%p)
94 The constructor takes the following parameters in addition to
95 parameters documented in Log::Dispatch::File:
96 max ($)
98 The maximum number of log files to create. Default 1.
99 size ($)
101 The maximum (or close to) size the log file can grow too. Default
102 10M.
103 DatePattern ($)
105 The "DatePattern" as defined above.
106 TZ ($)
108 The TimeZone time based calculations should be done in. This should
109 match Date::Manip's concept of timezones and of course your
110 machines timezone.
111 check_both ($)
113 1 for checking "DatePattern" and size concurrently, 0 otherwise.
114 Default 0.
115 user_constraint (\&)
117 If this callback is defined and returns true, a rotation will
118 happen unconditionally.
119 post_rotate (\&)
121 This callback is called after that all files were rotated. Will be
122 called one time for every rotated file (in reverse order) with this
123 arguments:
124 "filename"
126 the path of the rotated file
127 "index"
129 the index of the rotated file from "max"-1 to 0, in the latter
130 case "filename" is the new, empty, log file
131 "fileRotate"
133 a object reference to this instance
134 With this, you can have infinite files renaming each time the
136 rotated file log. E.g:
137 my $file = Log::Dispatch::FileRotate
139 ->new(
140 ...
141 post_rotate => sub {
142 my ($filename, $idx, $fileRotate) = @_;
143 if ($idx == 1) {
144 use POSIX qw(strftime);
145 my $basename = $fileRotate->filename();
146 my $newfilename =
147 $basename . '.' . strftime('%Y%m%d%H%M%S', localtime());
148 $fileRotate->debug("moving $filename to $newfilename");
149 rename($filename, $newfilename);
150 }
151 },
152 );
153 Note: this is called within the restricted area (see
155 "Concurrency"). This means that any other concurrent process is
156 locked in the meanwhile. For the same reason, don't use the log()
157 or log_message() methods because you will get a deadlock!
158 DEBUG ($)
160 Turn on lots of warning messages to STDERR about what this module
161 is doing if set to 1. Really only useful to me.
162 filename()
164 Returns the log filename.
165 setDatePattern( $ or [ $, $, ... ] )
167 Set a new suite of recurrances for file rotation. You can pass in a
168 single string or a reference to an array of strings. Multiple
169 recurrences can also be define within a single string by seperating
170 them with a semi-colon (;)
171 See the discussion above regarding the setDatePattern paramater for
173 more details.
174 log_message( message => $ )
176 Sends a message to the appropriate output. Generally this shouldn't be
177 called directly but should be called through the log() method (in
178 Log::Dispatch::Output).
179 rotate()
181 Rotates the file, if it has to be done. You can call this method if you
182 want to check, and eventually do, a rotation without logging anything.
183 Returns 1 if a rotation was done, 0 otherwise. "undef" on error.
185 debug($)
187 If "DEBUG" is true, prints a standard warning message.
188
190 If you have multiple writers that were started at different times you
191 will find each writer will try to rotate the log file at a recurrence
192 calculated from its start time. To sync all the writers just use a
193 config file and update it after starting your last writer. This will
194 cause new() to be called by each of the writers close to the same time,
195 and if your recurrences aren't too close together all should sync up
196 just nicely.
197 I initially assumed a long running process but it seems people are
199 using this module as part of short running CGI programs. So, now we
200 look at the last modified time stamp of the log file and compare it to
201 a previous occurance of a "DatePattern", on startup only. If the file
202 stat shows the mtime to be earlier than the previous recurrance then I
203 rotate the log file.
204
206 As I said earlier we use Date::Manip for generating our recurrence
207 events. This means we can understand Date::Manip's recurrence patterns
208 and the normal log4j DatePatterns. We don't use DatePattern to define
209 the extension of the log file though.
210 DatePattern can therefore take forms like:
212 Date::Manip style
214 0:0:0:0:5:30:0 every 5 hours and 30 minutes
215 0:0:0:2*12:30:0 every 2 days at 12:30 (each day)
216 3*1:0:2:12:0:0 every 3 years on Jan 2 at noon
217 DailyRollingFileAppender log4j style
219 yyyy-MM every month
220 yyyy-ww every week
221 yyyy-MM-dd every day
222 yyyy-MM-dd-a every day at noon
223 yyyy-MM-dd-HH every hour
224 yyyy-MM-dd-HH-MM every minute
225 To specify multiple recurrences in a single string separate them with a
227 semicolon:
228 yyyy-MM-dd; 0:0:0:2*12:30:0
229 This says we want to rotate every day AND every 2 days at 12:30. Put in
231 as many as you like.
232 A complete description of Date::Manip recurrences is beyond us here
234 except to quote (from the man page):
235 A recur description is a string of the format
237 Y:M:W:D:H:MN:S . Exactly one of the colons may
238 optionally be replaced by an asterisk, or an asterisk
239 may be prepended to the string.
240 Any value "N" to the left of the asterisk refers to
242 the "Nth" one. Any value to the right of the asterisk
243 refers to a value as it appears on a calendar/clock.
244 Values to the right can be listed a single values,
245 ranges (2 numbers separated by a dash "-"), or a comma
246 separated list of values or ranges. In a few cases,
247 negative values are appropriate.
248 This is best illustrated by example.
250 0:0:2:1:0:0:0 every 2 weeks and 1 day
252 0:0:0:0:5:30:0 every 5 hours and 30 minutes
253 0:0:0:2*12:30:0 every 2 days at 12:30 (each day)
254 3*1:0:2:12:0:0 every 3 years on Jan 2 at noon
255 0:1*0:2:12,14:0:0 2nd of every month at 12:00 and 14:00
256 1:0:0*45:0:0:0 45th day of every year
257 0:1*4:2:0:0:0 4th tuesday (day 2) of every month
258 0:1*-1:2:0:0:0 last tuesday of every month
259 0:1:0*-2:0:0:0 2nd to last day of every month
260
262 compression, signal based rotates, proper test suite
263 Could possibly use Logfile::Rotate as well/instead.
265
267 • Log::Dispatch::File::Stamped
268 Log directly to timestamped files.
270
272 Originally written by Mark Pfeiffer, <markpf at mlp-consulting dot com
273 dot au> inspired by Dave Rolsky's, <autarch at urth dot org>, code :-)
274 Kevin Goess <cpan at goess dot org> suggested multiple writers should
276 be supported. He also conned me into doing the time based stuff.
277 Thanks Kevin! :-)
278 Thanks also to Dan Waldheim for helping with some of the locking issues
280 in a forked environment.
281 And thanks to Stephen Gordon for his more portable code on lockfile
283 naming.
284
286 The development version is on github at
287 <https://https://github.com/mschout/perl-log-dispatch-filerotate> and
288 may be cloned from
289 <git://https://github.com/mschout/perl-log-dispatch-filerotate.git>
290
292 Please report any bugs or feature requests on the bugtracker website
293 <https://github.com/mschout/perl-log-dispatch-filerotate/issues>
294 When submitting a bug or request, please include a test-file or a patch
296 to an existing test-file that illustrates the bug or desired feature.
297
299 Michael Schout <mschout@cpan.org>
300
302 This software is copyright (c) 2005 by Mark Pfeiffer.
303 This is free software; you can redistribute it and/or modify it under
305 the same terms as the Perl 5 programming language system itself.
306perl v5.38.0 2023-07-20 Log::Dispatch::FileRotate(3)