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