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
53 DatePattern 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
66 config file and update it after starting your last writer. This will
67 cause Log::Dispatch::FileRotate->new() to be called by each of the
68 writers close to the same time, and if your recurrences aren't too
69 close 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
140 valid:
141 · -- name ($)
143 The name of the object (not the filename!). Required.
145 · -- size ($)
147 The maxium (or close to) size the log file can grow too.
149 · -- max ($)
151 The maxium number of log files to create.
153 · -- TZ ($)
155 The TimeZone time based calculations should be done in. This should
157 match Date::Manip's concept of timezones and of course your
158 machines timezone.
159 · -- DatePattern ($)
161 The DatePattern as defined above.
163 · -- min_level ($)
165 The minimum logging level this object will accept. See the
167 Log::Dispatch documentation for more information. Required.
168 · -- max_level ($)
170 The maximum logging level this obejct will accept. See the
172 Log::Dispatch documentation for more information. This is not
173 required. By default the maximum is the highest possible level
174 (which means functionally that the object has no maximum).
175 · -- filename ($)
177 The filename to be opened for writing. This is the base name.
179 Rotated log files will be renamed filename.1 thru to
180 filename."max". Where max is the paramater defined above.
181 · -- mode ($)
183 The mode the file should be opened with. Valid options are
185 'write', '>', 'append', '>>', or the relevant constants from Fcntl.
186 The default is 'write'.
187 · -- autoflush ($)
189 Whether or not the file should be autoflushed. This defaults to
191 true.
192 · -- callbacks( \& or [ \&, \&, ... ] )
194 This parameter may be a single subroutine reference or an array
196 reference of subroutine references. These callbacks will be called
197 in the order they are given and passed a hash containing the
198 following keys:
199 ( message => $log_message, level => $log_level )
201 The callbacks are expected to modify the message and then return a
203 single scalar containing that modified message. These callbacks
204 will be called when either the "log" or "log_to" methods are called
205 and will only be applied to a given message once.
206 · -- DEBUG ($)
208 Turn on lots of warning messages to STDERR about what this module
210 is doing if set to 1. Really only useful to me.
211 · log_message( message => $ )
213 Sends a message to the appropriate output. Generally this
215 shouldn't be called directly but should be called through the
216 "log()" method (in Log::Dispatch::Output).
217 · setDatePattern( $ or [ $, $, ... ] )
219 Set a new suite of recurrances for file rotation. You can pass in a
221 single string or a reference to an array of strings. Multiple
222 recurrences can also be define within a single string by seperating
223 them with a semi-colon (;)
224 See the discussion above regarding the setDatePattern paramater for
226 more details.
227
229 compression, signal based rotates, proper test suite
230 Could possibly use Logfile::Rotate as well/instead.
232
234 Mark Pfeiffer, <markpf at mlp-consulting dot com dot au> inspired by
235 Dave Rolsky's, <autarch at urth dot org>, code :-)
236 Kevin Goess <cpan at goess dot org> suggested multiple writers should
238 be supported. He also conned me into doing the time based stuff.
239 Thanks Kevin! :-)
240 Thanks also to Dan Waldheim for helping with some of the locking issues
242 in a forked environment.
243 And thanks to Stephen Gordon for his more portable code on lockfile
245 naming.
246
248 Copyright 2005-2006, Mark Pfeiffer
249 This code may be copied only under the terms of the Artistic License,
251 or GPL License which may be found in the Perl 5 source kit.
252 Use 'perldoc perlartistic' to see the Artistic License. Use 'perldoc
254 perlgpl' to see the GNU General Public License.
255 Complete documentation for Perl, including FAQ lists, should be found
257 on this system using `man perl' or `perldoc perl'. If you have access
258 to the Internet, point your browser at http://www.perl.org/, the Perl
259 Home Page.
260
262 Hey! The above document had some coding errors, which are explained
263 below:
264 Around line 801:
266 Expected '=item *'
267 Around line 805:
269 Expected '=item *'
270 Around line 809:
272 Expected '=item *'
273 Around line 814:
275 Expected '=item *'
276 Around line 819:
278 Expected '=item *'
279 Around line 823:
281 Expected '=item *'
282 Around line 828:
284 Expected '=item *'
285 Around line 835:
287 Expected '=item *'
288 Around line 841:
290 Expected '=item *'
291 Around line 847:
293 Expected '=item *'
294 Around line 851:
296 Expected '=item *'
297 Around line 864:
299 Expected '=item *'
300perl v5.12.0 2008-10-20 FileRotate(3)