1Log::Dispatch::FileRotaUtsee(r3)Contributed Perl DocumenLtoagt:i:oDnispatch::FileRotate(3)
2
3
4

NAME

6       Log::Dispatch::FileRotate - Log to Files that Archive/Rotate Themselves
7

VERSION

9       version 1.36
10

SYNOPSIS

12         use Log::Dispatch::FileRotate;
13
14         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
22         # or for a time based rotation
23
24         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
32         $file->log( level => 'info', message => "your comment\n" );
33

DESCRIPTION

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
40   Rotation
41       There are three different constraints which decide when a file must be
42       rotated.
43
44       The first is by size: when the log file grows more the a specified
45       size, then it's rotated.
46
47       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
56       You can also check both constraints together by using the "check_both"
57       parameter.
58
59       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
63       All check are made before logging. The "rotate" method leaves us check
64       these constraints without logging anything.
65
66       To let more power at the user, a "post_rotate" callback it'll call
67       after every rotation.
68
69   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
74       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
78       Within this restricted area we:
79
80       ·   check the size constraint
81
82       ·   eventually rotate the log file
83
84       ·   if it's defined, call the "post_rotate" function
85
86       ·   write the log message
87

METHODS

89   new(%p)
90       The constructor takes the following parameters in addition to
91       parameters documented in Log::Dispatch::File:
92
93       max ($)
94           The maximum number of log files to create. Default 1.
95
96       size ($)
97           The maximum (or close to) size the log file can grow too. Default
98           10M.
99
100       DatePattern ($)
101           The "DatePattern" as defined above.
102
103       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
108       check_both ($)
109           1 for checking "DatePattern" and size concurrently, 0 otherwise.
110           Default 0.
111
112       user_constraint (\&)
113           If this callback is defined and returns true, a rotation will
114           happen unconditionally.
115
116       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
121           "filename"
122               the path of the rotated file
123
124           "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
128           "fileRotate"
129               a object reference to this instance
130
131           With this, you can have infinite files renaming each time the
132           rotated file log. E.g:
133
134             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
150           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
155       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
159   filename()
160       Returns the log filename.
161
162   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
168       See the discussion above regarding the setDatePattern paramater for
169       more details.
170
171   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
176   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
180       Returns 1 if a rotation was done, 0 otherwise. "undef" on error.
181
182   debug($)
183       If "DEBUG" is true, prints a standard warning message.
184

Tip

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
194       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

DatePattern

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
207       DatePattern can therefore take forms like:
208
209             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
214             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
222       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
226       This says we want to rotate every day AND every 2 days at 12:30. Put in
227       as many as you like.
228
229       A complete description of Date::Manip recurrences is beyond us here
230       except to quote (from the man page):
231
232                  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
237                  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
245                  This is best illustrated by example.
246
247                    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

TODO

258       compression, signal based rotates, proper test suite
259
260       Could possibly use Logfile::Rotate as well/instead.
261

SEE ALSO

263       ·   Log::Dispatch::File::Stamped
264
265           Log directly to timestamped files.
266

HISTORY

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
271       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
275       Thanks also to Dan Waldheim for helping with some of the locking issues
276       in a forked environment.
277
278       And thanks to Stephen Gordon for his more portable code on lockfile
279       naming.
280

SOURCE

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

BUGS

288       Please report any bugs or feature requests on the bugtracker website
289       <https://github.com/mschout/perl-log-dispatch-filerotate/issues>
290
291       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

AUTHOR

295       Michael Schout <mschout@cpan.org>
296
298       This software is copyright (c) 2005 by Mark Pfeiffer.
299
300       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.
302
303
304
305perl v5.28.0                      2018-07-29      Log::Dispatch::FileRotate(3)
Impressum