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.38
10

SYNOPSIS

12         use Log::Dispatch::FileRotate;
13
14         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
22         # or for a time based rotation
23
24         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
32         # and attach to Log::Dispatch
33         my $dispatcher = Log::Dispatch->new;
34         $dispatcher->add($logger);
35
36         $dispatcher->log( level => 'info', message => "your comment\n" );
37

DESCRIPTION

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
44   Rotation
45       There are three different constraints which decide when a file must be
46       rotated.
47
48       The first is by size: when the log file grows more than a specified
49       size, then it's rotated.
50
51       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
60       You can also check both constraints together by using the "check_both"
61       parameter.
62
63       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
67       All check are made before logging. The "rotate" method leaves us check
68       these constraints without logging anything.
69
70       To let more power at the user, a "post_rotate" callback it'll call
71       after every rotation.
72
73   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
78       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
82       Within this restricted area we:
83
84       •   check the size constraint
85
86       •   eventually rotate the log file
87
88       •   if it's defined, call the "post_rotate" function
89
90       •   write the log message
91

METHODS

93   new(%p)
94       The constructor takes the following parameters in addition to
95       parameters documented in Log::Dispatch::File:
96
97       max ($)
98           The maximum number of log files to create. Default 1.
99
100       size ($)
101           The maximum (or close to) size the log file can grow too. Default
102           10M.
103
104       DatePattern ($)
105           The "DatePattern" as defined above.
106
107       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
112       check_both ($)
113           1 for checking "DatePattern" and size concurrently, 0 otherwise.
114           Default 0.
115
116       user_constraint (\&)
117           If this callback is defined and returns true, a rotation will
118           happen unconditionally.
119
120       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
125           "filename"
126               the path of the rotated file
127
128           "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
132           "fileRotate"
133               a object reference to this instance
134
135           With this, you can have infinite files renaming each time the
136           rotated file log. E.g:
137
138             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
154           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
159       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
163   filename()
164       Returns the log filename.
165
166   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
172       See the discussion above regarding the setDatePattern paramater for
173       more details.
174
175   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
180   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
184       Returns 1 if a rotation was done, 0 otherwise. "undef" on error.
185
186   debug($)
187       If "DEBUG" is true, prints a standard warning message.
188

Tip

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

DatePattern

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
211       DatePattern can therefore take forms like:
212
213             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
218             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
226       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
230       This says we want to rotate every day AND every 2 days at 12:30. Put in
231       as many as you like.
232
233       A complete description of Date::Manip recurrences is beyond us here
234       except to quote (from the man page):
235
236                  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
241                  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
249                  This is best illustrated by example.
250
251                    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

TODO

262       compression, signal based rotates, proper test suite
263
264       Could possibly use Logfile::Rotate as well/instead.
265

SEE ALSO

267       •   Log::Dispatch::File::Stamped
268
269           Log directly to timestamped files.
270

HISTORY

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

SOURCE

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

BUGS

292       Please report any bugs or feature requests on the bugtracker website
293       <https://github.com/mschout/perl-log-dispatch-filerotate/issues>
294
295       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

AUTHOR

299       Michael Schout <mschout@cpan.org>
300
302       This software is copyright (c) 2005 by Mark Pfeiffer.
303
304       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.
306
307
308
309perl v5.38.0                      2023-07-20      Log::Dispatch::FileRotate(3)
Impressum