Debian Codegraph @

README

raw
1 NAME
2
3 Log::Fast - Fast and flexible logger
4
5 VERSION
6
7 This document describes Log::Fast version v2.0.1
8
9 SYNOPSIS
10
11 use Log::Fast;
12
13 $LOG = Log::Fast->global();
14 $LOG = Log::Fast->new({
15 level => 'WARN',
16 prefix => '%D %T [%L] ',
17 type => 'fh',
18 fh => \*STDOUT,
19 });
20
21 use Sys::Syslog qw( LOG_DAEMON );
22 $LOG->config({
23 prefix => '',
24 type => 'unix',
25 path => '/dev/log',
26 facility => LOG_DAEMON,
27 add_timestamp => 1,
28 add_hostname => 1,
29 hostname => 'somehost',
30 ident => 'someapp',
31 add_pid => 1,
32 pid => $$,
33 });
34
35 $LOG->ident('anotherapp');
36 $LOG->level('INFO');
37
38 $LOG->ERR('Some error');
39 $LOG->WARN('Some warning');
40 $LOG->NOTICE('user %s logged in', $user);
41 $LOG->INFO('data loaded');
42 $LOG->DEBUG('user %s have %d things', $user, sub {
43 return SlowOperation_GetAmountOfThingsFor($user);
44 });
45
46 DESCRIPTION
47
48 This is very fast logger, designed for use in applications with
49 thousands high-level events/operations per second (like network servers
50 with thousands clients or web spiders which download hundreds url per
51 second).
52
53 For example, on Core2Duo sending about 5000 messages to log on enabled
54 log levels or 20000 messages on disabled log levels in one second will
55 slow down your application only by 2-3%.
56
57 Comparing to some other CPAN modules, this one (in average): faster
58 than Log::Dispatch in about 45 times, faster than Log::Handler in about
59 15 times, faster than Sys::Syslog in about 7 times, and slower than
60 Log::Syslog::Fast in about 2 times.
61
62 FEATURES
63
64 * Global and local logger objects
65
66 * Output to any open filehandle or local syslog
67
68 * 5 log levels: ERR, WARN, NOTICE, INFO, DEBUG
69
70 * Configurable prefix (log level, date/time, caller function name)
71
72 * sprintf() support
73
74 * Unicode support (UTF8)
75
76 * Can avoid calculating log message content on disabled log levels
77
78 INTERFACE
79
80 global
81
82 $LOG = Log::Fast->global();
83
84 When called first time will create global log object using default
85 options (you can reconfigure it using config() later).
86
87 Global log object is useful if your application consists of several
88 independent modules which should share same logging options configured
89 outside of these modules. In this case all these modules should use
90 same global() log object instead of creating new() independent log
91 objects in each module.
92
93 Return global log object.
94
95 new
96
97 $LOG = Log::Fast->new();
98 $LOG = Log::Fast->new( \%opt );
99
100 Create new log object, configured using defaults and user-provided
101 options, if any.
102
103 Return created log object.
104
105 config
106
107 $LOG->config( \%opt );
108
109 Reconfigure log object. Any options (see "OPTIONS") can be changed at
110 any time, including changing output {type} or setting options useless
111 with current output type (new values for these options will be used
112 later, if output type will be changed).
113
114 If you need to change only log {level} or syslog's {ident} you should
115 use level() or ident() methods because they are much faster than more
116 general config().
117
118 Return nothing. Throw exception if unable to connect to syslog.
119
120 level
121
122 $level = $LOG->level();
123 $level = $LOG->level( $new_level );
124
125 If $new_level given will change current log level. This is same as call
126 config({ level=>$new_level }) but much faster.
127
128 Return previous log level.
129
130 ident
131
132 $ident = $LOG->ident();
133 $ident = $LOG->ident( $new_ident );
134
135 If $new_ident given will change current syslog's ident. This is same as
136 call config({ ident=>$new_ident }) but much faster.
137
138 Return previous syslog's ident.
139
140 ERR
141
142 WARN
143
144 NOTICE
145
146 INFO
147
148 DEBUG
149
150 $LOG->ERR( $message )
151 $LOG->ERR( $format, @list )
152 $LOG->WARN( $message )
153 $LOG->WARN( $format, @list )
154 $LOG->NOTICE( $message )
155 $LOG->NOTICE( $format, @list )
156 $LOG->INFO( $message )
157 $LOG->INFO( $format, @list )
158 $LOG->DEBUG( $message )
159 $LOG->DEBUG( $format, @list )
160
161 Output $message to log using different log levels.
162
163 If $format, @list used instead of $message, then use sprintf($format,
164 @list) to calculate log message.
165
166 If @list will contain CODEREF, they will be called (in LIST context)
167 and returned values will be placed inside @list inplace of CODEREF.
168 This can be used to avoid calculating log message (or it part) on
169 disabled log levels - these CODEREF will be executed only on enabled
170 log levels. Example available in "SYNOPSIS".
171
172 If $message or items in @list will be Unicode strings, they will be
173 converted to UTF8 before sending to log.
174
175 Return nothing. Throw exception if fail to write message to log.
176
177 OPTIONS
178
179 Defaults for all options are:
180
181 level => 'DEBUG',
182 prefix => q{},
183
184 type => 'fh',
185 fh => \*STDERR,
186
187 # these will be used if you will call config({ type=>'unix' })
188 path => Sys::Syslog::_PATH_LOG() || '/dev/log',
189 facility => LOG_USER,
190 add_timestamp => 1,
191 add_hostname => 0,
192 hostname => Sys::Hostname::hostname(),
193 ident => ..., # calculated from $0
194 add_pid => 1,
195 pid => $$,
196
197 level
198
199 Current log level. Possible values are: 'ERR', 'WARN', 'NOTICE',
200 'INFO', 'DEBUG'.
201
202 Only messages on current or higher levels will be sent to log.
203
204 prefix
205
206 String, which will be output at beginning of each log message. May
207 contain these placeholders:
208
209 %L - log level of current message
210 %S - hi-resolution time (seconds.microseconds)
211 %D - current date in format YYYY-MM-DD
212 %T - current time in format HH:MM:SS
213 %P - caller's function package ('main' or 'My::Module')
214 %F - caller's function name
215 %_ - X spaces, where X is current stack depth
216 %% - % character
217
218 Example output with prefix '%D %T [%L]%_%P::%F() ':
219
220 2010-11-17 18:06:20 [INFO] main::() something from main script
221 2010-11-17 18:06:53 [INFO] main::a() something from a
222 2010-11-17 18:09:09 [INFO] main::b2() something from b1->b2
223 2010-11-17 18:06:56 [INFO] main::c() something from c
224
225 If it will be Unicode string, it will be converted to UTF8.
226
227 type
228
229 Output type. Possible values are: 'fh' (output to any already open
230 filehandle) and 'unix' (output to syslog using UNIX socket).
231
232 When {type} set to 'fh' you have to also set {fh} to any open
233 filehandle (like \*STDERR).
234
235 When {type} set to 'unix' you have to also set {path} to path to
236 existing UNIX socket (typically it's '/dev/log').
237
238 Luckily, default values for both {fh} and {path} are already
239 provided, so usually it's enough to just set {type}.
240
241 fh
242
243 File handle to write log messages if {type} set to 'fh'.
244
245 path
246
247 Syslog's UNIX socket path to write log messages if {type} set to
248 'unix'.
249
250 facility
251
252 Syslog's facility (see "Facilities" in Sys::Syslog for a list of
253 well-known facilities).
254
255 This module doesn't export any constants, so if you wanna change it
256 from default LOG_USER value, you should import facility constants
257 from Sys::Syslog module. Example available in "SYNOPSIS".
258
259 add_timestamp
260
261 If TRUE will include timestamp in syslog messages.
262
263 add_hostname
264
265 If TRUE will include hostname in syslog messages.
266
267 hostname
268
269 Host name which will be included in syslog messages if {add_hostname}
270 is TRUE.
271
272 ident
273
274 Syslog's ident (application name) field.
275
276 If it will be Unicode string, it will be converted to UTF8. Using
277 non-ASCII ALPHANUMERIC ident isn't allowed by RFC, but usually works.
278
279 add_pid
280
281 If TRUE will include PID in syslog messages.
282
283 pid
284
285 PID which will be included in syslog messages if {add_pid} is TRUE.
286
287 SPEED HINTS
288
289 Empty prefix is fastest. Prefixes %L, %P and %% are fast enough, %D and
290 %T has average speed, %S, %F and %_ are slowest.
291
292 Output to file is about 4 times faster than to syslog.
293
294 Calling log with single parameter is faster than with many parameters
295 (because in second case sprintf() have to be used).
296
297 SUPPORT
298
299 Bugs / Feature Requests
300
301 Please report any bugs or feature requests through the issue tracker at
302 https://github.com/powerman/perl-Log-Fast/issues. You will be notified
303 automatically of any progress on your issue.
304
305 Source Code
306
307 This is open source software. The code repository is available for
308 public review and contribution under the terms of the license. Feel
309 free to fork the repository and submit pull requests.
310
311 https://github.com/powerman/perl-Log-Fast
312
313 git clone https://github.com/powerman/perl-Log-Fast.git
314
315 Resources
316
317 * MetaCPAN Search
318
319 https://metacpan.org/search?q=Log-Fast
320
321 * CPAN Ratings
322
323 http://cpanratings.perl.org/dist/Log-Fast
324
325 * AnnoCPAN: Annotated CPAN documentation
326
327 http://annocpan.org/dist/Log-Fast
328
329 * CPAN Testers Matrix
330
331 http://matrix.cpantesters.org/?dist=Log-Fast
332
333 * CPANTS: A CPAN Testing Service (Kwalitee)
334
335 http://cpants.cpanauthors.org/dist/Log-Fast
336
337 AUTHOR
338
339 Alex Efros <[email protected]>
340
341 COPYRIGHT AND LICENSE
342
343 This software is Copyright (c) 2010- by Alex Efros <[email protected]>.
344
345 This is free software, licensed under:
346
347 The MIT (X11) License
348