ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent/Log.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.31 by root, Thu Aug 25 03:08:48 2011 UTC vs.
Revision 1.65 by root, Sat Sep 2 00:21:32 2017 UTC

… …
6 6
7Simple uses: 7Simple uses:
8 8
9 use AnyEvent; 9 use AnyEvent;
10 10
11 AE::log debug => "hit my knee"; 11 AE::log fatal => "No config found, cannot continue!"; # never returns
12 AE::log warn => "it's a bit too hot"; 12 AE::log alert => "The battery died!";
13 AE::log error => "the flag was false!"; 13 AE::log crit => "The battery temperature is too hot!";
14 AE::log fatal => "the bit toggled! run!"; # never returns 14 AE::log error => "Division by zero attempted.";
15 AE::log warn => "Couldn't delete the file.";
16 AE::log note => "Wanted to create config, but config already exists.";
17 AE::log info => "File soandso successfully deleted.";
18 AE::log debug => "the function returned 3";
19 AE::log trace => "going to call function abc";
15 20
21Log level overview:
22
23 LVL NAME SYSLOG PERL NOTE
24 1 fatal emerg exit system unusable, aborts program!
25 2 alert failure in primary system
26 3 critical crit failure in backup system
27 4 error err die non-urgent program errors, a bug
28 5 warn warning possible problem, not necessarily error
29 6 note notice unusual conditions
30 7 info normal messages, no action required
31 8 debug debugging messages for development
32 9 trace copious tracing output
33
16"Complex" uses (for speed sensitive code): 34"Complex" uses (for speed sensitive code, e.g. trace/debug messages):
17 35
18 use AnyEvent::Log; 36 use AnyEvent::Log;
19 37
20 my $tracer = AnyEvent::Log::logger trace => \$my $trace; 38 my $tracer = AnyEvent::Log::logger trace => \my $trace;
21 39
22 $tracer->("i am here") if $trace; 40 $tracer->("i am here") if $trace;
23 $tracer->(sub { "lots of data: " . Dumper $self }) if $trace; 41 $tracer->(sub { "lots of data: " . Dumper $self }) if $trace;
24 42
25Configuration (also look at the EXAMPLES section): 43Configuration (also look at the EXAMPLES section):
… …
32 50
33 # send all critical and higher priority messages to syslog, 51 # send all critical and higher priority messages to syslog,
34 # regardless of (most) other settings 52 # regardless of (most) other settings
35 $AnyEvent::Log::COLLECT->attach (new AnyEvent::Log::Ctx 53 $AnyEvent::Log::COLLECT->attach (new AnyEvent::Log::Ctx
36 level => "critical", 54 level => "critical",
37 log_to_syslog => 0, 55 log_to_syslog => "user",
38 ); 56 );
39 57
40=head1 DESCRIPTION 58=head1 DESCRIPTION
41 59
42This module implements a relatively simple "logging framework". It doesn't 60This module implements a relatively simple "logging framework". It doesn't
43attempt to be "the" logging solution or even "a" logging solution for 61attempt to be "the" logging solution or even "a" logging solution for
44AnyEvent - AnyEvent simply creates logging messages internally, and this 62AnyEvent - AnyEvent simply creates logging messages internally, and this
45module more or less exposes the mechanism, with some extra spiff to allow 63module more or less exposes the mechanism, with some extra spiff to allow
46using it from other modules as well. 64using it from other modules as well.
47 65
48Remember that the default verbosity level is C<0> (C<off>), so nothing 66Remember that the default verbosity level is C<4> (C<error>), so only
49will be logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number 67errors and more important messages will be logged, unless you set
50before starting your program, or change the logging level at runtime with 68C<PERL_ANYEVENT_VERBOSE> to a higher number before starting your program
51something like: 69(C<AE_VERBOSE=5> is recommended during development), or change the logging
70level at runtime with something like:
52 71
53 use AnyEvent::Log; 72 use AnyEvent::Log;
54 AnyEvent::Log::FILTER->level ("info"); 73 $AnyEvent::Log::FILTER->level ("info");
55 74
56The design goal behind this module was to keep it simple (and small), 75The design goal behind this module was to keep it simple (and small),
57but make it powerful enough to be potentially useful for any module, and 76but make it powerful enough to be potentially useful for any module,
58extensive enough for the most common tasks, such as logging to multiple 77and extensive enough for the most common tasks, such as logging to
59targets, or being able to log into a database. 78multiple targets, or being able to log into a database.
60 79
80The module is also usable before AnyEvent itself is initialised, in which
81case some of the functionality might be reduced.
82
61The amount of documentation might indicate otherwise, but the module is 83The amount of documentation might indicate otherwise, but the runtime part
62still just below 300 lines of code. 84of the module is still just below 300 lines of code.
63 85
64=head1 LOGGING LEVELS 86=head1 LOGGING LEVELS
65 87
66Logging levels in this module range from C<1> (highest priority) to C<9> 88Logging levels in this module range from C<1> (highest priority) to C<9>
67(lowest priority). Note that the lowest numerical value is the highest 89(lowest priority). Note that the lowest numerical value is the highest
… …
69numerical value". 91numerical value".
70 92
71Instead of specifying levels by name you can also specify them by aliases: 93Instead of specifying levels by name you can also specify them by aliases:
72 94
73 LVL NAME SYSLOG PERL NOTE 95 LVL NAME SYSLOG PERL NOTE
74 1 fatal emerg exit aborts program! 96 1 fatal emerg exit system unusable, aborts program!
75 2 alert 97 2 alert failure in primary system
76 3 critical crit 98 3 critical crit failure in backup system
77 4 error err die 99 4 error err die non-urgent program errors, a bug
78 5 warn warning 100 5 warn warning possible problem, not necessarily error
79 6 note notice 101 6 note notice unusual conditions
80 7 info 102 7 info normal messages, no action required
81 8 debug 103 8 debug debugging messages for development
82 9 trace 104 9 trace copious tracing output
83 105
84As you can see, some logging levels have multiple aliases - the first one 106As you can see, some logging levels have multiple aliases - the first one
85is the "official" name, the second one the "syslog" name (if it differs) 107is the "official" name, the second one the "syslog" name (if it differs)
86and the third one the "perl" name, suggesting that you log C<die> messages 108and the third one the "perl" name, suggesting (only!) that you log C<die>
87at C<error> priority. 109messages at C<error> priority. The NOTE column tries to provide some
110rationale on how to chose a logging level.
88 111
112As a rough guideline, levels 1..3 are primarily meant for users of the
113program (admins, staff), and are the only ones logged to STDERR by
114default. Levels 4..6 are meant for users and developers alike, while
115levels 7..9 are usually meant for developers.
116
89You can normally only log a single message at highest priority level 117You can normally only log a message once at highest priority level (C<1>,
90(C<1>, C<fatal>), because logging a fatal message will also quit the 118C<fatal>), because logging a fatal message will also quit the program - so
91program - so use it sparingly :) 119use it sparingly :)
120
121For example, a program that finds an unknown switch on the commandline
122might well use a fatal logging level to tell users about it - the "system"
123in this case would be the program, or module.
92 124
93Some methods also offer some extra levels, such as C<0>, C<off>, C<none> 125Some methods also offer some extra levels, such as C<0>, C<off>, C<none>
94or C<all> - these are only valid in the methods they are documented for. 126or C<all> - these are only valid for the methods that documented them.
95 127
96=head1 LOGGING FUNCTIONS 128=head1 LOGGING FUNCTIONS
97 129
98These functions allow you to log messages. They always use the caller's 130The following functions allow you to log messages. They always use the
99package as a "logging context". Also, the main logging function C<log> is 131caller's package as a "logging context". Also, the main logging function,
100callable as C<AnyEvent::log> or C<AE::log> when the C<AnyEvent> module is 132C<log>, is aliased to C<AnyEvent::log> and C<AE::log> when the C<AnyEvent>
101loaded. 133module is loaded.
102 134
103=over 4 135=over 4
104 136
105=cut 137=cut
106 138
107package AnyEvent::Log; 139package AnyEvent::Log;
108 140
109use Carp (); 141use Carp ();
110use POSIX (); 142use POSIX ();
111 143
144# layout of a context
145# 0 1 2 3 4, 5
146# [$title, $level, %$slaves, &$logcb, &$fmtcb, $cap]
147
112use AnyEvent (); BEGIN { AnyEvent::common_sense } 148use AnyEvent (); BEGIN { AnyEvent::common_sense }
113use AnyEvent::Util (); 149#use AnyEvent::Util (); need to load this in a delayed fashion, as it uses AE::log
114 150
115our $VERSION = $AnyEvent::VERSION; 151our $VERSION = $AnyEvent::VERSION;
116 152
117our ($COLLECT, $FILTER, $LOG); 153our ($COLLECT, $FILTER, $LOG);
118 154
119our ($now_int, $now_str1, $now_str2); 155our ($now_int, $now_str1, $now_str2);
120 156
121# Format Time, not public - yet? 157# Format Time, not public - yet?
122sub ft($) { 158sub format_time($) {
123 my $i = int $_[0]; 159 my $i = int $_[0];
124 my $f = sprintf "%06d", 1e6 * ($_[0] - $i); 160 my $f = sprintf "%06d", 1e6 * ($_[0] - $i);
125 161
126 ($now_int, $now_str1, $now_str2) = ($i, split /\x01/, POSIX::strftime "%Y-%m-%d %H:%M:%S.\x01 %z", localtime $i) 162 ($now_int, $now_str1, $now_str2) = ($i, split /\x01/, POSIX::strftime "%Y-%m-%d %H:%M:%S.\x01 %z", localtime $i)
127 if $now_int != $i; 163 if $now_int != $i;
… …
148=item AnyEvent::Log::log $level, $msg[, @args] 184=item AnyEvent::Log::log $level, $msg[, @args]
149 185
150Requests logging of the given C<$msg> with the given log level, and 186Requests logging of the given C<$msg> with the given log level, and
151returns true if the message was logged I<somewhere>. 187returns true if the message was logged I<somewhere>.
152 188
153For C<fatal> log levels, the program will abort. 189For loglevel C<fatal>, the program will abort.
154 190
155If only a C<$msg> is given, it is logged as-is. With extra C<@args>, the 191If only a C<$msg> is given, it is logged as-is. With extra C<@args>, the
156C<$msg> is interpreted as an sprintf format string. 192C<$msg> is interpreted as an sprintf format string.
157 193
158The C<$msg> should not end with C<\n>, but may if that is convenient for 194The C<$msg> should not end with C<\n>, but may if that is convenient for
… …
160 196
161Last not least, C<$msg> might be a code reference, in which case it is 197Last not least, C<$msg> might be a code reference, in which case it is
162supposed to return the message. It will be called only then the message 198supposed to return the message. It will be called only then the message
163actually gets logged, which is useful if it is costly to create the 199actually gets logged, which is useful if it is costly to create the
164message in the first place. 200message in the first place.
201
202This function takes care of saving and restoring C<$!> and C<$@>, so you
203don't have to.
165 204
166Whether the given message will be logged depends on the maximum log level 205Whether the given message will be logged depends on the maximum log level
167and the caller's package. The return value can be used to ensure that 206and the caller's package. The return value can be used to ensure that
168messages or not "lost" - for example, when L<AnyEvent::Debug> detects a 207messages or not "lost" - for example, when L<AnyEvent::Debug> detects a
169runtime error it tries to log it at C<die> level, but if that message is 208runtime error it tries to log it at C<die> level, but if that message is
… …
203 info => 7, 242 info => 7,
204 debug => 8, 243 debug => 8,
205 trace => 9, 244 trace => 9,
206); 245);
207 246
208sub now () { time } 247our $TIME_EXACT;
248
249sub exact_time($) {
250 $TIME_EXACT = shift;
251 *_ts = $AnyEvent::MODEL
252 ? $TIME_EXACT ? \&AE::now : \&AE::time
253 : sub () { $TIME_EXACT ? do { require Time::HiRes; Time::HiRes::time () } : time };
254}
255
256BEGIN {
257 exact_time 0;
258}
209 259
210AnyEvent::post_detect { 260AnyEvent::post_detect {
211 *now = \&AE::now; 261 exact_time $TIME_EXACT;
212}; 262};
213 263
214our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace); 264our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace);
215 265
216# time, ctx, level, msg 266# time, ctx, level, msg
217sub _format($$$$) { 267sub default_format($$$$) {
218 my $ts = ft $_[0]; 268 my $ts = format_time $_[0];
219 my $ct = " "; 269 my $ct = " ";
220 270
221 my @res; 271 my @res;
222 272
223 for (split /\n/, sprintf "%-5s %s: %s", $LEVEL2STR[$_[2]], $_[1][0], $_[3]) { 273 for (split /\n/, sprintf "%-5s %s: %s", $LEVEL2STR[$_[2]], $_[1][0], $_[3]) {
… …
226 } 276 }
227 277
228 join "", @res 278 join "", @res
229} 279}
230 280
281sub fatal_exit() {
282 exit 1;
283}
284
231sub _log { 285sub _log {
232 my ($ctx, $level, $format, @args) = @_; 286 my ($ctx, $level, $format, @args) = @_;
233 287
234 $level = $level > 0 && $level <= 9 288 $level = $level > 0 && $level <= 9
235 ? $level+0 289 ? $level+0
236 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught"; 290 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught";
237 291
238 my $mask = 1 << $level; 292 my $mask = 1 << $level;
239 293
240 my ($success, %seen, @ctx, $now, $fmt); 294 my ($success, %seen, @ctx, $now, @fmt);
241 295
242 do 296 do
243 { 297 {
244 # skip if masked 298 # if !ref, then it's a level number
299 if (!ref $ctx) {
300 $level = $ctx;
245 if ($ctx->[1] & $mask && !$seen{$ctx+0}++) { 301 } elsif ($ctx->[1] & $mask and !$seen{$ctx+0}++) {
302 # logging/recursing into this context
303
304 # level cap
305 if ($ctx->[5] > $level) {
306 push @ctx, $level; # restore level when going up in tree
307 $level = $ctx->[5];
308 }
309
310 # log if log cb
246 if ($ctx->[3]) { 311 if ($ctx->[3]) {
247 # logging target found 312 # logging target found
313
314 local ($!, $@);
248 315
249 # now get raw message, unless we have it already 316 # now get raw message, unless we have it already
250 unless ($now) { 317 unless ($now) {
251 $format = $format->() if ref $format; 318 $format = $format->() if ref $format;
252 $format = sprintf $format, @args if @args; 319 $format = sprintf $format, @args if @args;
253 $format =~ s/\n$//; 320 $format =~ s/\n$//;
254 $now = now; 321 $now = _ts;
255 }; 322 };
256 323
257 # format msg 324 # format msg
258 my $str = $ctx->[4] 325 my $str = $ctx->[4]
259 ? $ctx->[4]($now, $_[0], $level, $format) 326 ? $ctx->[4]($now, $_[0], $level, $format)
260 : ($fmt ||= _format $now, $_[0], $level, $format); 327 : ($fmt[$level] ||= default_format $now, $_[0], $level, $format);
261 328
262 $success = 1; 329 $success = 1;
263 330
264 $ctx->[3]($str) 331 $ctx->[3]($str)
265 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate 332 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate
… …
268 } 335 }
269 } 336 }
270 } 337 }
271 while $ctx = pop @ctx; 338 while $ctx = pop @ctx;
272 339
273 exit 1 if $level <= 1; 340 fatal_exit if $level <= 1;
274 341
275 $success 342 $success
276} 343}
277 344
278sub log($$;@) { 345sub log($$;@) {
279 _log 346 _log
280 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 347 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
281 @_; 348 @_;
282} 349}
283 350
284*AnyEvent::log = *AE::log = \&log;
285
286=item $logger = AnyEvent::Log::logger $level[, \$enabled] 351=item $logger = AnyEvent::Log::logger $level[, \$enabled]
287 352
288Creates a code reference that, when called, acts as if the 353Creates a code reference that, when called, acts as if the
289C<AnyEvent::Log::log> function was called at this point with the given 354C<AnyEvent::Log::log> function was called at this point with the given
290level. C<$logger> is passed a C<$msg> and optional C<@args>, just as with 355level. C<$logger> is passed a C<$msg> and optional C<@args>, just as with
… …
354 419
355 $LOGGER{$logger+0} = $logger; 420 $LOGGER{$logger+0} = $logger;
356 421
357 _reassess $logger+0; 422 _reassess $logger+0;
358 423
424 require AnyEvent::Util unless $AnyEvent::Util::VERSION;
359 my $guard = AnyEvent::Util::guard { 425 my $guard = AnyEvent::Util::guard (sub {
360 # "clean up" 426 # "clean up"
361 delete $LOGGER{$logger+0}; 427 delete $LOGGER{$logger+0};
362 }; 428 });
363 429
364 sub { 430 sub {
365 $guard if 0; # keep guard alive, but don't cause runtime overhead 431 $guard if 0; # keep guard alive, but don't cause runtime overhead
366 432
367 _log $ctx, $level, @_ 433 _log $ctx, $level, @_
… …
372sub logger($;$) { 438sub logger($;$) {
373 _logger 439 _logger
374 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 440 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
375 @_ 441 @_
376} 442}
443
444=item AnyEvent::Log::exact_time $on
445
446By default, C<AnyEvent::Log> will use C<AE::now>, i.e. the cached
447eventloop time, for the log timestamps. After calling this function with a
448true value it will instead resort to C<AE::time>, i.e. fetch the current
449time on each log message. This only makes a difference for event loops
450that actually cache the time (such as L<EV> or L<AnyEvent::Loop>).
451
452This setting can be changed at any time by calling this function.
453
454Since C<AnyEvent::Log> has to work even before the L<AnyEvent> has been
455initialised, this switch will also decide whether to use C<CORE::time> or
456C<Time::HiRes::time> when logging a message before L<AnyEvent> becomes
457available.
458
459=item AnyEvent::Log::format_time $timestamp
460
461Formats a timestamp as returned by C<< AnyEvent->now >> or C<<
462AnyEvent->time >> or many other functions in the same way as
463C<AnyEvent::Log> does.
464
465In your main program (as opposed to in your module) you can override
466the default timestamp display format by loading this module and then
467redefining this function.
468
469Most commonly, this function can be used in formatting callbacks.
470
471=item AnyEvent::Log::default_format $time, $ctx, $level, $msg
472
473Format a log message using the given timestamp, logging context, log level
474and log message.
475
476This is the formatting function used to format messages when no custom
477function is provided.
478
479In your main program (as opposed to in your module) you can override the
480default message format by loading this module and then redefining this
481function.
482
483=item AnyEvent::Log::fatal_exit
484
485This is the function that is called after logging a C<fatal> log
486message. It must not return.
487
488The default implementation simply calls C<exit 1>.
489
490In your main program (as opposed to in your module) you can override
491the fatal exit function by loading this module and then redefining this
492function. Make sure you don't return.
377 493
378=back 494=back
379 495
380=head1 LOGGING CONTEXTS 496=head1 LOGGING CONTEXTS
381 497
… …
501This can be used to implement config-file (re-)loading: before loading a 617This can be used to implement config-file (re-)loading: before loading a
502configuration, reset all contexts. 618configuration, reset all contexts.
503 619
504=cut 620=cut
505 621
622our $ORIG_VERBOSE = $AnyEvent::VERBOSE;
623$AnyEvent::VERBOSE = 9;
624
506sub reset { 625sub reset {
507 # hard to kill complex data structures 626 # hard to kill complex data structures
508 # we "recreate" all package loggers and reset the hierarchy 627 # we "recreate" all package loggers and reset the hierarchy
509 while (my ($k, $v) = each %CTX) { 628 while (my ($k, $v) = each %CTX) {
510 @$v = ($k, (1 << 10) - 1 - 1, { }); 629 @$v = ($k, (1 << 10) - 1 - 1, { });
… …
513 } 632 }
514 633
515 @$_ = ($_->[0], (1 << 10) - 1 - 1) 634 @$_ = ($_->[0], (1 << 10) - 1 - 1)
516 for $LOG, $FILTER, $COLLECT; 635 for $LOG, $FILTER, $COLLECT;
517 636
518 $LOG->slaves; 637 #$LOG->slaves;
519 $LOG->title ('$AnyEvent::Log::LOG'); 638 $LOG->title ('$AnyEvent::Log::LOG');
520 $LOG->log_to_warn; 639 $LOG->log_to_warn;
521 640
522 $FILTER->slaves ($LOG); 641 $FILTER->slaves ($LOG);
523 $FILTER->title ('$AnyEvent::Log::FILTER'); 642 $FILTER->title ('$AnyEvent::Log::FILTER');
524 $FILTER->level ($AnyEvent::VERBOSE); 643 $FILTER->level ($ORIG_VERBOSE);
525 644
526 $COLLECT->slaves ($FILTER); 645 $COLLECT->slaves ($FILTER);
527 $COLLECT->title ('$AnyEvent::Log::COLLECT'); 646 $COLLECT->title ('$AnyEvent::Log::COLLECT');
528 647
529 _reassess; 648 _reassess;
530} 649}
650
651# override AE::log/logger
652*AnyEvent::log = *AE::log = \&log;
653*AnyEvent::logger = *AE::logger = \&logger;
654
655# convert AnyEvent loggers to AnyEvent::Log loggers
656$_->[0] = ctx $_->[0] # convert "pkg" to "ctx"
657 for values %LOGGER;
531 658
532# create the default logger contexts 659# create the default logger contexts
533$LOG = ctx undef; 660$LOG = ctx undef;
534$FILTER = ctx undef; 661$FILTER = ctx undef;
535$COLLECT = ctx undef; 662$COLLECT = ctx undef;
… …
544package AnyEvent::Log::COLLECT; 671package AnyEvent::Log::COLLECT;
545package AE::Log::COLLECT; 672package AE::Log::COLLECT;
546 673
547package AnyEvent::Log::Ctx; 674package AnyEvent::Log::Ctx;
548 675
549# 0 1 2 3 4
550# [$title, $level, %$slaves, &$logcb, &$fmtcb]
551
552=item $ctx = new AnyEvent::Log::Ctx methodname => param... 676=item $ctx = new AnyEvent::Log::Ctx methodname => param...
553 677
554This is a convenience constructor that makes it simpler to construct 678This is a convenience constructor that makes it simpler to construct
555anonymous logging contexts. 679anonymous logging contexts.
556 680
… …
643 767
644=item $ctx->disable ($level[, $level...]) 768=item $ctx->disable ($level[, $level...])
645 769
646Disables logging for the given levels, leaving all others unchanged. 770Disables logging for the given levels, leaving all others unchanged.
647 771
772=item $ctx->cap ($level)
773
774Caps the maximum priority to the given level, for all messages logged
775to, or passing through, this context. That is, while this doesn't affect
776whether a message is logged or passed on, the maximum priority of messages
777will be limited to the specified level - messages with a higher priority
778will be set to the specified priority.
779
780Another way to view this is that C<< ->level >> filters out messages with
781a too low priority, while C<< ->cap >> modifies messages with a too high
782priority.
783
784This is useful when different log targets have different interpretations
785of priority. For example, for a specific command line program, a wrong
786command line switch might well result in a C<fatal> log message, while the
787same message, logged to syslog, is likely I<not> fatal to the system or
788syslog facility as a whole, but more likely a mere C<error>.
789
790This can be modeled by having a stderr logger that logs messages "as-is"
791and a syslog logger that logs messages with a level cap of, say, C<error>,
792or, for truly system-critical components, actually C<critical>.
793
648=cut 794=cut
649 795
650sub _lvl_lst { 796sub _lvl_lst {
651 map { 797 map {
652 $_ > 0 && $_ <= 9 ? $_+0 798 $_ > 0 && $_ <= 9 ? $_+0
653 : $_ eq "all" ? (1 .. 9) 799 : $_ eq "all" ? (1 .. 9)
654 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught" 800 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught"
655 } @_ 801 } @_
656} 802}
657 803
804sub _lvl {
805 $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1]
806}
807
658our $NOP_CB = sub { 0 }; 808our $NOP_CB = sub { 0 };
659 809
660sub levels { 810sub levels {
661 my $ctx = shift; 811 my $ctx = shift;
662 $ctx->[1] = 0; 812 $ctx->[1] = 0;
… …
665 AnyEvent::Log::_reassess; 815 AnyEvent::Log::_reassess;
666} 816}
667 817
668sub level { 818sub level {
669 my $ctx = shift; 819 my $ctx = shift;
670 my $lvl = $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1];
671
672 $ctx->[1] = ((1 << $lvl) - 1) << 1; 820 $ctx->[1] = ((1 << &_lvl) - 1) << 1;
673 AnyEvent::Log::_reassess; 821 AnyEvent::Log::_reassess;
674} 822}
675 823
676sub enable { 824sub enable {
677 my $ctx = shift; 825 my $ctx = shift;
… …
685 $ctx->[1] &= ~(1 << $_) 833 $ctx->[1] &= ~(1 << $_)
686 for &_lvl_lst; 834 for &_lvl_lst;
687 AnyEvent::Log::_reassess; 835 AnyEvent::Log::_reassess;
688} 836}
689 837
838sub cap {
839 my $ctx = shift;
840 $ctx->[5] = &_lvl;
841}
842
690=back 843=back
691 844
692=head3 SLAVE CONTEXTS 845=head3 SLAVE CONTEXTS
693 846
694The following methods attach and detach another logging context to a 847The following methods attach and detach another logging context to a
… …
746the logging (which consists of formatting the message and printing it or 899the logging (which consists of formatting the message and printing it or
747whatever it wants to do with it). 900whatever it wants to do with it).
748 901
749=over 4 902=over 4
750 903
751=item $ctx->log_cb ($cb->($str) 904=item $ctx->log_cb ($cb->($str))
752 905
753Replaces the logging callback on the context (C<undef> disables the 906Replaces the logging callback on the context (C<undef> disables the
754logging callback). 907logging callback).
755 908
756The logging callback is responsible for handling formatted log messages 909The logging callback is responsible for handling formatted log messages
… …
781 934
782Replaces the formatting callback on the context (C<undef> restores the 935Replaces the formatting callback on the context (C<undef> restores the
783default formatter). 936default formatter).
784 937
785The callback is passed the (possibly fractional) timestamp, the original 938The callback is passed the (possibly fractional) timestamp, the original
786logging context, the (numeric) logging level and the raw message string 939logging context (object, not title), the (numeric) logging level and
787and needs to return a formatted log message. In most cases this will be a 940the raw message string and needs to return a formatted log message. In
788string, but it could just as well be an array reference that just stores 941most cases this will be a string, but it could just as well be an array
789the values. 942reference that just stores the values.
790 943
791If, for some reason, you want to use C<caller> to find out more baout the 944If, for some reason, you want to use C<caller> to find out more about the
792logger then you should walk up the call stack until you are no longer 945logger then you should walk up the call stack until you are no longer
793inside the C<AnyEvent::Log> package. 946inside the C<AnyEvent::Log> package.
794 947
948To implement your own logging callback, you might find the
949C<AnyEvent::Log::format_time> and C<AnyEvent::Log::default_format>
950functions useful.
951
952Example: format the message just as AnyEvent::Log would, by letting
953AnyEvent::Log do the work. This is a good basis to design a formatting
954callback that only changes minor aspects of the formatting.
955
956 $ctx->fmt_cb (sub {
957 my ($time, $ctx, $lvl, $msg) = @_;
958
959 AnyEvent::Log::default_format $time, $ctx, $lvl, $msg
960 });
961
795Example: format just the raw message, with numeric log level in angle 962Example: format just the raw message, with numeric log level in angle
796brackets. 963brackets.
797 964
798 $ctx->fmt_cb (sub { 965 $ctx->fmt_cb (sub {
799 my ($time, $ctx, $lvl, $msg) = @_; 966 my ($time, $ctx, $lvl, $msg) = @_;
800 967
801 "<$lvl>$msg\n" 968 "<$lvl>$msg\n"
802 }); 969 });
803 970
804Example: return an array reference with just the log values, and use 971Example: return an array reference with just the log values, and use
805C<PApp::SQL::sql_exec> to store the emssage in a database. 972C<PApp::SQL::sql_exec> to store the message in a database.
806 973
807 $ctx->fmt_cb (sub { \@_ }); 974 $ctx->fmt_cb (sub { \@_ });
808 $ctx->log_cb (sub { 975 $ctx->log_cb (sub {
809 my ($msg) = @_; 976 my ($msg) = @_;
810 977
… …
822Sets the C<log_cb> to simply use C<CORE::warn> to report any messages 989Sets the C<log_cb> to simply use C<CORE::warn> to report any messages
823(usually this logs to STDERR). 990(usually this logs to STDERR).
824 991
825=item $ctx->log_to_file ($path) 992=item $ctx->log_to_file ($path)
826 993
827Sets the C<log_cb> to log to a file (by appending), unbuffered. 994Sets the C<log_cb> to log to a file (by appending), unbuffered. The
995function might return before the log file has been opened or created.
828 996
829=item $ctx->log_to_path ($path) 997=item $ctx->log_to_path ($path)
830 998
831Same as C<< ->log_to_file >>, but opens the file for each message. This 999Same as C<< ->log_to_file >>, but opens the file for each message. This
832is much slower, but allows you to change/move/rename/delete the file at 1000is much slower, but allows you to change/move/rename/delete the file at
… …
834 1002
835Needless(?) to say, if you do not want to be bitten by some evil person 1003Needless(?) to say, if you do not want to be bitten by some evil person
836calling C<chdir>, the path should be absolute. Doesn't help with 1004calling C<chdir>, the path should be absolute. Doesn't help with
837C<chroot>, but hey... 1005C<chroot>, but hey...
838 1006
839=item $ctx->log_to_syslog ([$log_flags]) 1007=item $ctx->log_to_syslog ([$facility])
840 1008
841Logs all messages via L<Sys::Syslog>, mapping C<trace> to C<debug> and all 1009Logs all messages via L<Sys::Syslog>, mapping C<trace> to C<debug> and
842the others in the obvious way. If specified, then the C<$log_flags> are 1010all the others in the obvious way. If specified, then the C<$facility> is
843simply or'ed onto the priority argument and can contain any C<LOG_xxx> 1011used as the facility (C<user>, C<auth>, C<local0> and so on). The default
844flags valid for Sys::Syslog::syslog, except for the priority levels. 1012facility is C<user>.
845 1013
846Note that this function also sets a C<fmt_cb> - the logging part requires 1014Note that this function also sets a C<fmt_cb> - the logging part requires
847an array reference with [$level, $str] as input. 1015an array reference with [$level, $str] as input.
848 1016
849=cut 1017=cut
… …
867 warn shift; 1035 warn shift;
868 0 1036 0
869 }); 1037 });
870} 1038}
871 1039
1040# this function is a good example of why threads are a must,
1041# simply for priority inversion.
1042sub _log_to_disk {
1043 # eval'uating this at runtime saves 220kb rss - perl has become
1044 # an insane memory waster.
1045 eval q{ # poor man's autoloading {}
1046 sub _log_to_disk {
1047 my ($ctx, $path, $keepopen) = @_;
1048
1049 my $fh;
1050 my @queue;
1051 my $delay;
1052 my $disable;
1053
1054 use AnyEvent::IO ();
1055
1056 my $kick = sub {
1057 undef $delay;
1058 return unless @queue;
1059 $delay = 1;
1060
1061 # we pass $kick to $kick, so $kick itself doesn't keep a reference to $kick.
1062 my $kick = shift;
1063
1064 # write one or more messages
1065 my $write = sub {
1066 # we write as many messages as have been queued
1067 my $data = join "", @queue;
1068 @queue = ();
1069
1070 AnyEvent::IO::aio_write $fh, $data, sub {
1071 $disable = 1;
1072 @_
1073 ? ($_[0] == length $data or AE::log 4 => "unable to write to logfile '$path': short write")
1074 : AE::log 4 => "unable to write to logfile '$path': $!";
1075 undef $disable;
1076
1077 if ($keepopen) {
1078 $kick->($kick);
1079 } else {
1080 AnyEvent::IO::aio_close ($fh, sub {
1081 undef $fh;
1082 $kick->($kick);
1083 });
1084 }
1085 };
1086 };
1087
1088 if ($fh) {
1089 $write->();
1090 } else {
1091 AnyEvent::IO::aio_open
1092 $path,
1093 AnyEvent::IO::O_CREAT | AnyEvent::IO::O_WRONLY | AnyEvent::IO::O_APPEND,
1094 0666,
1095 sub {
1096 $fh = shift
1097 or do {
1098 $disable = 1;
1099 AE::log 4 => "unable to open logfile '$path': $!";
1100 undef $disable;
1101 return;
1102 };
1103
1104 $write->();
1105 }
1106 ;
1107 }
1108 };
1109
1110 $ctx->log_cb (sub {
1111 return if $disable;
1112 push @queue, shift;
1113 $kick->($kick) unless $delay;
1114 0
1115 });
1116
1117 $kick->($kick) if $keepopen; # initial open
1118 };
1119 };
1120 die if $@;
1121 &_log_to_disk
1122}
1123
872sub log_to_file { 1124sub log_to_file {
873 my ($ctx, $path) = @_; 1125 my ($ctx, $path) = @_;
874 1126
875 open my $fh, ">>", $path 1127 _log_to_disk $ctx, $path, 1;
876 or die "$path: $!";
877
878 $ctx->log_cb (sub {
879 syswrite $fh, shift;
880 0
881 });
882} 1128}
883 1129
884sub log_to_path { 1130sub log_to_path {
885 my ($ctx, $path) = @_; 1131 my ($ctx, $path) = @_;
886 1132
887 $ctx->log_cb (sub { 1133 _log_to_disk $ctx, $path, 0;
888 open my $fh, ">>", $path
889 or die "$path: $!";
890
891 syswrite $fh, shift;
892 0
893 });
894} 1134}
895 1135
896sub log_to_syslog { 1136sub log_to_syslog {
897 my ($ctx, $flags) = @_; 1137 my ($ctx, $facility) = @_;
898 1138
899 require Sys::Syslog; 1139 require Sys::Syslog;
900 1140
901 $ctx->fmt_cb (sub { 1141 $ctx->fmt_cb (sub {
902 my $str = $_[3]; 1142 my $str = $_[3];
903 $str =~ s/\n(?=.)/\n+ /g; 1143 $str =~ s/\n(?=.)/\n+ /g;
904 1144
905 [$_[2], "($_[1][0]) $str"] 1145 [$_[2], "($_[1][0]) $str"]
906 }); 1146 });
907 1147
1148 $facility ||= "user";
1149
908 $ctx->log_cb (sub { 1150 $ctx->log_cb (sub {
909 my $lvl = $_[0][0] < 9 ? $_[0][0] : 8; 1151 my $lvl = $_[0][0] < 9 ? $_[0][0] : 8;
910 1152
911 Sys::Syslog::syslog ($flags | ($lvl - 1), $_) 1153 Sys::Syslog::syslog ("$facility|" . ($lvl - 1), $_)
912 for split /\n/, $_[0][1]; 1154 for split /\n/, $_[0][1];
913 1155
914 0 1156 0
915 }); 1157 });
916} 1158}
… …
925=over 4 1167=over 4
926 1168
927=item $ctx->log ($level, $msg[, @params]) 1169=item $ctx->log ($level, $msg[, @params])
928 1170
929Same as C<AnyEvent::Log::log>, but uses the given context as log context. 1171Same as C<AnyEvent::Log::log>, but uses the given context as log context.
1172
1173Example: log a message in the context of another package.
1174
1175 (AnyEvent::Log::ctx "Other::Package")->log (warn => "heely bo");
930 1176
931=item $logger = $ctx->logger ($level[, \$enabled]) 1177=item $logger = $ctx->logger ($level[, \$enabled])
932 1178
933Same as C<AnyEvent::Log::logger>, but uses the given context as log 1179Same as C<AnyEvent::Log::logger>, but uses the given context as log
934context. 1180context.
… …
982 1228
983Context names starting with a C<%> are anonymous contexts created when the 1229Context names starting with a C<%> are anonymous contexts created when the
984name is first mentioned. The difference to package contexts is that by 1230name is first mentioned. The difference to package contexts is that by
985default they have no attached slaves. 1231default they have no attached slaves.
986 1232
1233This makes it possible to create new log contexts that can be refered to
1234multiple times by name within the same log specification.
1235
987=item a perl package name 1236=item a perl package name
988 1237
989Any other string references the logging context associated with the given 1238Any other string references the logging context associated with the given
990Perl C<package>. In the unlikely case where you want to specify a package 1239Perl C<package>. In the unlikely case where you want to specify a package
991context that matches on of the other context name forms, you can add a 1240context that matches on of the other context name forms, you can add a
… …
1012Configures the context to log to a file with the given path. Works like 1261Configures the context to log to a file with the given path. Works like
1013C<log_to_path>. 1262C<log_to_path>.
1014 1263
1015=item C<syslog> or C<syslog=>I<expr> 1264=item C<syslog> or C<syslog=>I<expr>
1016 1265
1017Configured the context to log to syslog. If I<expr> is given, then it is 1266Configures the context to log to syslog. If I<expr> is given, then it is
1018evaluated in the L<Sys::Syslog> package, so you could use: 1267evaluated in the L<Sys::Syslog> package, so you could use:
1019 1268
1020 log=syslog=LOG_LOCAL0 1269 log=syslog=LOG_LOCAL0
1021 1270
1022=item C<nolog> 1271=item C<nolog>
1023 1272
1024Configures the context to not log anything by itself, which is the 1273Configures the context to not log anything by itself, which is the
1025default. Same as C<< $ctx->log_cb (undef) >>. 1274default. Same as C<< $ctx->log_cb (undef) >>.
1026 1275
1276=item C<cap=>I<level>
1277
1278Caps logging messages entering this context at the given level, i.e.
1279reduces the priority of messages with higher priority than this level. The
1280default is C<0> (or C<off>), meaning the priority will not be touched.
1281
1027=item C<0> or C<off> 1282=item C<0> or C<off>
1028 1283
1029Sets the logging level of the context ot C<0>, i.e. all messages will be 1284Sets the logging level of the context to C<0>, i.e. all messages will be
1030filtered out. 1285filtered out.
1031 1286
1032=item C<all> 1287=item C<all>
1033 1288
1034Enables all logging levels, i.e. filtering will effectively be switched 1289Enables all logging levels, i.e. filtering will effectively be switched
… …
1064 filter=warn 1319 filter=warn
1065 1320
1066 # or, more verbose 1321 # or, more verbose
1067 filter=only,level,warn 1322 filter=only,level,warn
1068 1323
1069=item C<1>..C<9>, a logging level name (C<error>, C<debug> etc.) 1324=item C<1>..C<9> or a logging level name (C<error>, C<debug> etc.)
1070 1325
1071A numeric loglevel or the name of a loglevel will be interpreted according 1326A numeric loglevel or the name of a loglevel will be interpreted according
1072to the most recent C<only>, C<except> or C<level> directive. By default, 1327to the most recent C<only>, C<except> or C<level> directive. By default,
1073specifying a logging level enables that and any higher priority messages. 1328specifying a logging level enables that and any higher priority messages.
1074 1329
1075=item C<+>I<context> 1330=item C<+>I<context>
1076 1331
1077Adds/attaches the named context as slave to the context. 1332Attaches the named context as slave to the context.
1078 1333
1079=item C<+> 1334=item C<+>
1080 1335
1081A line C<+> clears the slave list form the context. Anonymous (C<%name>) 1336A lone C<+> detaches all contexts, i.e. clears the slave list from the
1082contexts have no slaves by default, but package contexts have the parent 1337context. Anonymous (C<%name>) contexts have no attached slaves by default,
1083context as slave by default. 1338but package contexts have the parent context as slave by default.
1084 1339
1085Example: log messages from My::Module to a file, do not send them to the 1340Example: log messages from My::Module to a file, do not send them to the
1086default log collector. 1341default log collector.
1087 1342
1088 My::Module=+,file=/tmp/mymodulelog 1343 My::Module=+,file=/tmp/mymodulelog
1089 1344
1090=back 1345=back
1091 1346
1092Any character can be escaped by prefixing it with a C<\> (backslash), as 1347Any character can be escaped by prefixing it with a C<\> (backslash), as
1093usual, so to log to a file containing a comma, colon, backslash and space in the 1348usual, so to log to a file containing a comma, colon, backslash and some
1094filename, you would do this: 1349spaces in the filename, you would do this:
1095 1350
1096 PERL_ANYEVENT_LOG='log=file=/some\ \:file\ with\,\ \\-escapes' 1351 PERL_ANYEVENT_LOG='log=file=/some\ \:file\ with\,\ \\-escapes'
1097 1352
1098Since whitespace (which includes newlines) is allowed, it is fine to 1353Since whitespace (which includes newlines) is allowed, it is fine to
1099specify multiple lines in C<PERL_ANYEVENT_LOG>, e.g.: 1354specify multiple lines in C<PERL_ANYEVENT_LOG>, e.g.:
… …
1117 1372
1118 my $pkg = sub { 1373 my $pkg = sub {
1119 $_[0] eq "log" ? $LOG 1374 $_[0] eq "log" ? $LOG
1120 : $_[0] eq "filter" ? $FILTER 1375 : $_[0] eq "filter" ? $FILTER
1121 : $_[0] eq "collect" ? $COLLECT 1376 : $_[0] eq "collect" ? $COLLECT
1122 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= ctx undef) 1377 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= do { my $ctx = ctx undef; $ctx->[0] = $_[0]; $ctx })
1123 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/ 1378 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/
1124 : die # never reached? 1379 : die # never reached?
1125 }; 1380 };
1126 1381
1127 /\G[[:space:]]+/gc; # skip initial whitespace 1382 /\G[[:space:]]+/gc; # skip initial whitespace
… …
1133 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) { 1388 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) {
1134 for ("$1") { 1389 for ("$1") {
1135 if ($_ eq "stderr" ) { $ctx->log_to_warn; 1390 if ($_ eq "stderr" ) { $ctx->log_to_warn;
1136 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1"); 1391 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1");
1137 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1"); 1392 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1");
1138 } elsif (/syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog (eval "package Sys::Syslog; $1"); 1393 } elsif (/^syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog ("$1");
1139 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef); 1394 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef);
1395 } elsif (/^cap=(.+)/ ) { $ctx->cap ("$1");
1140 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1")); 1396 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1"));
1141 } elsif ($_ eq "+" ) { $ctx->slaves; 1397 } elsif ($_ eq "+" ) { $ctx->slaves;
1142 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0); 1398 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0);
1143 } elsif ($_ eq "all" ) { $ctx->level ("all"); 1399 } elsif ($_ eq "all" ) { $ctx->level ("all");
1144 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level"; 1400 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level";
… …
1161 if (/\G(.+)/g) { 1417 if (/\G(.+)/g) {
1162 die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n"; 1418 die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n";
1163 } 1419 }
1164} 1420}
1165 1421
11661;
1167
1168=head1 EXAMPLES 1422=head1 EXAMPLES
1169 1423
1170This section shows some common configurations, both as code, and as 1424This section shows some common configurations, both as code, and as
1171C<PERL_ANYEVENT_LOG> string. 1425C<PERL_ANYEVENT_LOG> string.
1172 1426
… …
1196 1450
1197This writes them only when the global logging level allows it, because 1451This writes them only when the global logging level allows it, because
1198it is attached to the default context which is invoked I<after> global 1452it is attached to the default context which is invoked I<after> global
1199filtering. 1453filtering.
1200 1454
1201 $AnyEvent::Log::FILTER->attach 1455 $AnyEvent::Log::FILTER->attach (
1202 new AnyEvent::Log::Ctx log_to_file => $path); 1456 new AnyEvent::Log::Ctx log_to_file => $path);
1203 1457
1204 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path 1458 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
1205 1459
1206This writes them regardless of the global logging level, because it is 1460This writes them regardless of the global logging level, because it is
… …
1212 1466
1213 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger 1467 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
1214 1468
1215In both cases, messages are still written to STDERR. 1469In both cases, messages are still written to STDERR.
1216 1470
1471=item Additionally log all messages with C<warn> and higher priority to
1472C<syslog>, but cap at C<error>.
1473
1474This logs all messages to the default log target, but also logs messages
1475with priority C<warn> or higher (and not filtered otherwise) to syslog
1476facility C<user>. Messages with priority higher than C<error> will be
1477logged with level C<error>.
1478
1479 $AnyEvent::Log::LOG->attach (
1480 new AnyEvent::Log::Ctx
1481 level => "warn",
1482 cap => "error",
1483 syslog => "user",
1484 );
1485
1486 PERL_ANYEVENT_LOG=log=+%syslog:%syslog=warn,cap=error,syslog
1487
1217=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s). 1488=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s).
1218 1489
1219Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug> 1490Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug>
1220context - this simply circumvents the global filtering for trace messages. 1491context - this simply circumvents the global filtering for trace messages.
1221 1492
… …
1228assumes the log level for AnyEvent::Debug hasn't been changed from the 1499assumes the log level for AnyEvent::Debug hasn't been changed from the
1229default. 1500default.
1230 1501
1231=back 1502=back
1232 1503
1504=head1 ASYNCHRONOUS DISK I/O
1505
1506This module uses L<AnyEvent::IO> to actually write log messages (in
1507C<log_to_file> and C<log_to_path>), so it doesn't block your program when
1508the disk is busy and a non-blocking L<AnyEvent::IO> backend is available.
1509
1233=head1 AUTHOR 1510=head1 AUTHOR
1234 1511
1235 Marc Lehmann <schmorp@schmorp.de> 1512 Marc Lehmann <schmorp@schmorp.de>
1236 http://home.schmorp.de/ 1513 http://anyevent.schmorp.de
1237 1514
1238=cut 1515=cut
1239 1516
15171
1518

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines