1FileRotate(3) User Contributed Perl Documentation FileRotate(3)
2
6 Log::Dispatch::FileRotate - Log to files that archive/rotate themselves
7
9 use Log::Dispatch::FileRotate;
10 my $file = Log::Dispatch::FileRotate->new( name => 'file1',
12 min_level => 'info',
13 filename => 'Somefile.log',
14 mode => 'append' ,
15 size => 10,
16 max => 6,
17 );
18 # or for a time based rotation
19 my $file = Log::Dispatch::FileRotate->new( name => 'file1',
21 min_level => 'info',
22 filename => 'Somefile.log',
23 mode => 'append' ,
24 TZ => 'AEDT',
25 DatePattern => 'yyyy-dd-HH',
26 );
27 $file->log( level => 'info', message => "your comment\n" );
29
31 This module provides a simple object for logging to files under the
32 Log::Dispatch::* system, and automatically rotating them according to
33 different constraints. This is basically a Log::Dispatch::File wrapper
34 with additions. To that end the arguments
35 name, min_level, filename and mode
37 behave the same as Log::Dispatch::File. So see its man page (perldoc
39 Log::Dispatch::File)
40 The arguments size and max specify the maximum size and maximum number
42 of log files created. The size defaults to 10M and the max number of
43 files defaults to 1. If DatePattern is not defined then we default to
44 working in size mode. That is, use size values for deciding when to
45 rotate.
46 Once DatePattern is defined FileRotate will move into time mode. Once
48 this happens file rotation ignores size constraints and uses the
49 defined date pattern constraints.
50 If you setup a config file using Log::Log4perl::init_and_watch() or the
52 like, you can switch between modes just by commenting out the DatePat‐
53 tern line.
54 When using DatePattern make sure TZ is defined correctly and that the
56 TZ you use is understood by Date::Manip. We use Date::Manip to generate
57 our recurrences. Bad TZ equals bad recurrences equals surprises! Read
58 the Date::Manip man page for more details on TZ.
59 DatePattern will default to a daily rotate if your entered pattern is
61 incorrect. You will also get a warning message.
62 If you have multiple writers that were started at different times you
64 will find each writer will try to rotate the log file at a recurrence
65 calculated from its start time. To sync all the writers just use a con‐
66 fig file and update it after starting your last writer. This will cause
67 Log::Dispatch::FileRotate->new() to be called by each of the writers
68 close to the same time, and if your recurrences aren't too close
69 together all should sync up just nicely.
70 I initially aasumed a long runinng process but it seems people are
72 using this module as part of short running CGI programs. So, now we
73 look at the last modified time stamp of the log file and compare it to
74 a previous occurance of a DatePattern, on startup only. If the file
75 stat shows the mtime to be earlier than the previous recurrance then I
76 rotate the log file.
77 We handle multiple writers using flock().
79
81 As I said earlier we use Date::Manip for generating our recurrence
82 events. This means we can understand Date::Manip's recurrence patterns
83 and the normal log4j DatePatterns. We don't use DatePattern to define
84 the extension of the log file though.
85 DatePattern can therefore take forms like:
87 Date::Manip style
89 0:0:0:0:5:30:0 every 5 hours and 30 minutes
90 0:0:0:2*12:30:0 every 2 days at 12:30 (each day)
91 3*1:0:2:12:0:0 every 3 years on Jan 2 at noon
92 DailyRollingFileAppender log4j style
94 yyyy-MM every month
95 yyyy-ww every week
96 yyyy-MM-dd every day
97 yyyy-MM-dd-a every day at noon
98 yyyy-MM-dd-HH every hour
99 yyyy-MM-dd-HH-MM every minute
100 To specify multiple recurrences in a single string separate them with a
102 semicolon:
103 yyyy-MM-dd; 0:0:0:2*12:30:0
104 This says we want to rotate every day AND every 2 days at 12:30. Put in
106 as many as you like.
107 A complete description of Date::Manip recurrences is beyond us here
109 except to quote (from the man page):
110 A recur description is a string of the format
112 Y:M:W:D:H:MN:S . Exactly one of the colons may
113 optionally be replaced by an asterisk, or an asterisk
114 may be prepended to the string.
115 Any value "N" to the left of the asterisk refers to
117 the "Nth" one. Any value to the right of the asterisk
118 refers to a value as it appears on a calendar/clock.
119 Values to the right can be listed a single values,
120 ranges (2 numbers separated by a dash "-"), or a comma
121 separated list of values or ranges. In a few cases,
122 negative values are appropriate.
123 This is best illustrated by example.
125 0:0:2:1:0:0:0 every 2 weeks and 1 day
127 0:0:0:0:5:30:0 every 5 hours and 30 minutes
128 0:0:0:2*12:30:0 every 2 days at 12:30 (each day)
129 3*1:0:2:12:0:0 every 3 years on Jan 2 at noon
130 0:1*0:2:12,14:0:0 2nd of every month at 12:00 and 14:00
131 1:0:0*45:0:0:0 45th day of every year
132 0:1*4:2:0:0:0 4th tuesday (day 2) of every month
133 0:1*-1:2:0:0:0 last tuesday of every month
134 0:1:0*-2:0:0:0 2nd to last day of every month
135
137 * new(%p)
138 This method takes a hash of parameters. The following options are
139 valid:
140 -- name ($)
142 The name of the object (not the filename!). Required.
143 -- size ($)
145 The maxium (or close to) size the log file can grow too.
146 -- max ($)
148 The maxium number of log files to create.
149 -- TZ ($)
151 The TimeZone time based calculations should be done in. This should
152 match Date::Manip's concept of timezones and of course your
153 machines timezone. Date::Manip will normally work everything out
154 for you. Except in my case where EST means Eastern Standard Time in
155 Australia not the US! I had to use AEST or EADT instead. Here is a
156 list of Date::Manip's timezones straight from its man page.
157 The following timezone names are currently understood (and
159 can be used in parsing dates). These are zones defined in
160 RFC 822.
161 Universal: GMT, UT
163 US zones : EST, EDT, CST, CDT, MST, MDT, PST, PDT
164 Military : A to Z (except J)
165 Other : +HHMM or -HHMM
166 ISO 8601 : +HH:MM, +HH, -HH:MM, -HH
167 In addition, the following timezone abbreviations are also
169 accepted.
170 IDLW -1200 International Date Line West
172 NT -1100 Nome
173 HST -1000 Hawaii Standard
174 CAT -1000 Central Alaska
175 AHST -1000 Alaska-Hawaii Standard
176 AKST -0900 Alaska Standard
177 YST -0900 Yukon Standard
178 HDT -0900 Hawaii Daylight
179 AKDT -0800 Alaska Daylight
180 YDT -0800 Yukon Daylight
181 PST -0800 Pacific Standard
182 PDT -0700 Pacific Daylight
183 MST -0700 Mountain Standard
184 MDT -0600 Mountain Daylight
185 CST -0600 Central Standard
186 CDT -0500 Central Daylight
187 EST -0500 Eastern Standard
188 SAT -0400 Chile
189 EDT -0400 Eastern Daylight
190 AST -0400 Atlantic Standard
191 ADT -0300 Atlantic Daylight
192 NDT -0230 Newfoundland Daylight
193 AT -0200 Azores
194 WAT -0100 West Africa
195 GMT +0000 Greenwich Mean
196 UT +0000 Universal (Coordinated)
197 UTC +0000 Universal (Coordinated)
198 WET +0000 Western European
199 WEST +0000 Alias for Western European
200 CET +0100 Central European
201 FWT +0100 French Winter
202 MET +0100 Middle European
203 MEZ +0100 Middle European
204 MEWT +0100 Middle European Winter
205 SWT +0100 Swedish Winter
206 BST +0100 British Summer bst=Brazil standard -0300
207 GB +0100 GMT with daylight savings
208 CEST +0200 Central European Summer
209 EET +0200 Eastern Europe, USSR Zone 1
210 FST +0200 French Summer
211 MEST +0200 Middle European Summer
212 MESZ +0200 Middle European Summer
213 METDST +0200 An alias for MEST used by HP-UX
214 SAST +0200 South African Standard
215 SST +0200 Swedish Summer sst=South Sumatra +0700
216 EEST +0300 Eastern Europe Summer
217 BT +0300 Baghdad, USSR Zone 2
218 MSK +0300 Moscow
219 IT +0330 Iran
220 ZP4 +0400 USSR Zone 3
221 MSD +0300 Moscow Daylight
222 ZP5 +0500 USSR Zone 4
223 IST +0530 Indian Standard
224 ZP6 +0600 USSR Zone 5
225 CCT +0800 China Coast, USSR Zone 7
226 AWST +0800 West Australian Standard
227 WST +0800 West Australian Standard
228 PHT +0800 Asia Manila
229 JST +0900 Japan Standard, USSR Zone 8
230 ROK +0900 Republic of Korea
231 CAST +0930 Central Australian Standard
232 EAST +1000 Eastern Australian Standard
233 GST +1000 Guam Standard, USSR Zone 9 gst=Greenland Std
234 CADT +1030 Central Australian Daylight
235 EADT +1100 Eastern Australian Daylight
236 IDLE +1200 International Date Line East
237 NZST +1200 New Zealand Standard
238 NZT +1200 New Zealand
239 NZDT +1300 New Zealand Daylight
240 -- DatePattern ($)
242 The DatePattern as defined above.
243 -- min_level ($)
245 The minimum logging level this object will accept. See the
246 Log::Dispatch documentation for more information. Required.
247 -- max_level ($)
249 The maximum logging level this obejct will accept. See the
250 Log::Dispatch documentation for more information. This is not
251 required. By default the maximum is the highest possible level
252 (which means functionally that the object has no maximum).
253 -- filename ($)
255 The filename to be opened for writing. This is the base name.
256 Rotated log files will be renamed filename.1 thru to file‐
257 name."max". Where max is the paramater defined above.
258 -- mode ($)
260 The mode the file should be opened with. Valid options are
261 'write', '>', 'append', '>>', or the relevant constants from Fcntl.
262 The default is 'write'.
263 -- autoflush ($)
265 Whether or not the file should be autoflushed. This defaults to
266 true.
267 -- callbacks( \& or [ \&, \&, ... ] )
269 This parameter may be a single subroutine reference or an array
270 reference of subroutine references. These callbacks will be called
271 in the order they are given and passed a hash containing the fol‐
272 lowing keys:
273 ( message => $log_message, level => $log_level )
275 The callbacks are expected to modify the message and then return a
277 single scalar containing that modified message. These callbacks
278 will be called when either the "log" or "log_to" methods are called
279 and will only be applied to a given message once.
280 -- DEBUG ($)
282 Turn on lots of warning messages to STDERR about what this module
283 is doing if set to 1. Really only useful to me.
284 * log_message( message => $ )
286 Sends a message to the appropriate output. Generally this
287 shouldn't be called directly but should be called through the
288 "log()" method (in Log::Dispatch::Output).
289 * setDatePattern( $ or [ $, $, ... ] )
291 Set a new suite of recurrances for file rotation. You can pass in a
292 single string or a reference to an array of strings. Multiple
293 recurrences can also be define within a single string by seperating
294 them with a semi-colon (;)
295 See the discussion above regarding the setDatePattern paramater for
297 more details.
298
300 compression, signal based rotates, proper test suite
301 Could possibly use Logfile::Rotate as well/instead.
303
305 Mark Pfeiffer, <markpf at mlp-consulting dot com dot au> inspired by
306 Dave Rolsky's, <autarch at urth dot org>, code :-)
307 Kevin Goess <cpan at goess dot org> suggested multiple writers should
309 be supported. He also conned me into doing the time based stuff.
310 Thanks Kevin! :-)
311 Thanks also to Dan Waldheim for helping with some of the locking issues
313 in a forked environment.
314 And thanks to Stephen Gordon for his more portable code on lockfile
316 naming.
317
319 Copyright 2005-2006, Mark Pfeiffer
320 This code may be copied only under the terms of the Artistic License,
322 or GPL License which may be found in the Perl 5 source kit.
323 Use 'perldoc perlartistic' to see the Artistic License. Use 'perldoc
325 perlgpl' to see the GNU General Public License.
326 Complete documentation for Perl, including FAQ lists, should be found
328 on this system using `man perl' or `perldoc perl'. If you have access
329 to the Internet, point your browser at http://www.perl.org/, the Perl
330 Home Page.
331perl v5.8.8 2006-11-17 FileRotate(3)