1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
NAME
Log::Dispatch::Dir - Log messages to separate files in a directory, with
rotate options
VERSION
This document describes version 0.160 of Log::Dispatch::Dir (from Perl
distribution Log-Dispatch-Dir), released on 2019-01-09.
SYNOPSIS
use Log::Dispatch::Dir;
my $dir = Log::Dispatch::Dir->new(
name => 'dir1',
min_level => 'info',
dirname => 'somedir.log',
filename_pattern => '%Y-%m-%d-%H%M%S.%{ext}',
);
$dir->log( level => 'info', message => 'your comment\n" );
# limit total size
my $dir = Log::Dispatch::Dir->new(
# ...
max_size => 10*1024*1024, # 10MB
);
# limit number of files
my $dir = Log::Dispatch::Dir->new(
# ...
max_files => 1000,
);
# limit oldest file
my $dir = Log::Dispatch::Dir->new(
# ...
max_age => 10*24*3600, # 10 days
);
DESCRIPTION
This module provides a simple object for logging to directories under
the Log::Dispatch::* system, and automatically rotating them according
to different constraints. Each message will be logged to a separate file
the directory.
Logging to separate files can be useful for example when dumping whole
network responses (like HTTP::Response content).
METHODS
new(%p)
This method takes a hash of parameters. The following options are valid:
* name ($)
The name of the object (not the dirname!). Required.
* min_level ($)
The minimum logging level this object will accept. See the
Log::Dispatch documentation on Log Levels for more information.
Required.
* max_level ($)
The maximum logging level this obejct will accept. See the
Log::Dispatch documentation on Log Levels for more information. This
is not required. By default the maximum is the highest possible
level (which means functionally that the object has no maximum).
* dirname ($)
The directory to write to.
* permissions ($)
If the directory does not already exist, the permissions that it
should be created with. Optional. The argument passed must be a
valid octal value, such as 0700 or the constants available from
Fcntl, like S_IRUSR|S_IWUSR|S_IXUSR.
See "chmod" in perlfunc for more on potential traps when passing
octal values around. Most importantly, remember that if you pass a
string that looks like an octal value, like this:
my $mode = '0644';
Then the resulting directory will end up with permissions like this:
--w----r-T
which is probably not what you want.
* callbacks( \& or [ \&, \&, ... ] )
This parameter may be a single subroutine reference or an array
reference of subroutine references. These callbacks will be called
in the order they are given and passed a hash containing the
following keys:
( message => $log_message, level => $log_level )
The callbacks are expected to modify the message and then return a
single scalar containing that modified message. These callbacks will
be called when either the "log" or "log_to" methods are called and
will only be applied to a given message once.
* filename_pattern ($)
Names to give to each file, expressed in pattern a la strftime()'s.
Optional. Default is '%Y-%m-%d-%H%M%S.pid-%{pid}.%{ext}'. Time is
expressed in local time.
If file of the same name already exists, a suffix ".1", ".2", and so
on will be appended.
Available pattern:
%Y - 4-digit year number, e.g. 2009
%y - 2-digit year number, e.g. 09 for year 2009
%m - 2-digit month, e.g. 04 for April
%d - 2-digit day of month, e.g. 28
%H - 2-digit hour, e.g. 01
%M - 2-digit minute, e.g. 57
%S - 2-digit second, e.g. 59
%z - the time zone as hour offset from GMT
%Z - the time zone or name or abbreviation
%{pid} - Process ID
%{ext} - Guessed file extension
Try to detect appropriate file extension using
File::LibMagic. For example, if log message looks like an
HTML document, then 'html'. If File::LibMagic is not
available or type cannot be detected, defaults to 'log'.
%% - literal '%' character
* filename_sub (\&)
A more generic mechanism for filename_pattern. If filename_sub is
given, filename_pattern will be ignored. The code will be called
with the same arguments as log_message() and is expected to return a
filename. Will die if code returns undef.
* max_size ($)
Maximum total size of files, in bytes. After the size is surpassed,
oldest files (based on ctime) will be deleted. Optional. Default is
undefined, which means unlimited.
* max_files ($)
Maximum number of files. After this number is surpassed, oldest
files (based on ctime) will be deleted. Optional. Default is
undefined, which means unlimited.
* max_age ($)
Maximum age of files (based on ctime), in seconds. After the age is
surpassed, files older than this age will be deleted. Optional.
Default is undefined, which means unlimited.
* rotate_probability ($)
A number between 0 and 1 which specifies the probability that
rotate() will be called after each log_message(). This is a balance
between performance and rotate size accuracy. 1 means always rotate,
0 means never rotate. Optional. Default is 0.25.
log_message(message => $)
Sends a message to the appropriate output. Generally this shouldn't be
called directly but should be called through the "log()" method (in
Log::Dispatch::Output).
HOMEPAGE
Please visit the project's homepage at
<https://metacpan.org/release/Log-Dispatch-Dir>.
SOURCE
Source repository is at
<https://github.com/perlancar/perl-Log-Dispatch-Dir>.
BUGS
Please report any bugs or feature requests on the bugtracker website
<https://rt.cpan.org/Public/Dist/Display.html?Name=Log-Dispatch-Dir>
When submitting a bug or request, please include a test-file or a patch
to an existing test-file that illustrates the bug or desired feature.
SEE ALSO
Log::Dispatch
AUTHOR
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2019, 2017, 2015, 2014, 2013, 2011 by
perlancar@cpan.org.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
|
