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.24 by root, Sun Aug 21 03:24:59 2011 UTC vs.
Revision 1.49 by root, Thu Mar 22 01:03:57 2012 UTC

… …
2 2
3AnyEvent::Log - simple logging "framework" 3AnyEvent::Log - simple logging "framework"
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 # simple use: 7Simple uses:
8 8
9 use AnyEvent; 9 use AnyEvent;
10 10
11 AE::log debug => "hit my knee"; 11 AE::log trace => "going to call function abc";
12 AE::log warn => "it's a bit too hot"; 12 AE::log debug => "the function returned 3";
13 AE::log error => "the flag was false!"; 13 AE::log info => "file soandso successfully deleted";
14 AE::log fatal => "the bit toggled! run!"; # never returns 14 AE::log note => "wanted to create config, but config was already created";
15 AE::log warn => "couldn't delete the file";
16 AE::log error => "failed to retrieve data";
17 AE::log crit => "the battery temperature is too hot";
18 AE::log alert => "the battery died";
19 AE::log fatal => "no config found, cannot continue"; # never returns
15 20
16 # "complex" use (for speed sensitive code): 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
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
25 # configuration: 43Configuration (also look at the EXAMPLES section):
26 44
27 # set logging for the current package to errors and higher only 45 # set logging for the current package to errors and higher only
28 AnyEvent::Log::ctx->level ("error"); 46 AnyEvent::Log::ctx->level ("error");
29 47
30 # set logging level to suppress anything below "notice" 48 # set logging level to suppress anything below "notice"
… …
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
40 # see also EXAMPLES, below
41 57
42=head1 DESCRIPTION 58=head1 DESCRIPTION
43 59
44This module implements a relatively simple "logging framework". It doesn't 60This module implements a relatively simple "logging framework". It doesn't
45attempt to be "the" logging solution or even "a" logging solution for 61attempt to be "the" logging solution or even "a" logging solution for
46AnyEvent - AnyEvent simply creates logging messages internally, and this 62AnyEvent - AnyEvent simply creates logging messages internally, and this
47module 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
48using it from other modules as well. 64using it from other modules as well.
49 65
50Remember that the default verbosity level is C<0> (C<off>), so nothing 66Remember that the default verbosity level is C<3> (C<critical>), so little
51will be logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number 67will be logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number
52before starting your program, or change the logging level at runtime with 68before starting your program, or change the logging level at runtime with
53something like: 69something like:
54 70
55 use AnyEvent::Log; 71 use AnyEvent::Log;
56 AnyEvent::Log::FILTER->level ("info"); 72 $AnyEvent::Log::FILTER->level ("info");
57 73
58The design goal behind this module was to keep it simple (and small), 74The design goal behind this module was to keep it simple (and small),
59but make it powerful enough to be potentially useful for any module, and 75but make it powerful enough to be potentially useful for any module, and
60extensive enough for the most common tasks, such as logging to multiple 76extensive enough for the most common tasks, such as logging to multiple
61targets, or being able to log into a database. 77targets, or being able to log into a database.
62 78
79The module is also usable before AnyEvent itself is initialised, in which
80case some of the functionality might be reduced.
81
63The amount of documentation might indicate otherwise, but the module is 82The amount of documentation might indicate otherwise, but the runtime part
64still just below 300 lines of code. 83of the module is still just below 300 lines of code.
65 84
66=head1 LOGGING LEVELS 85=head1 LOGGING LEVELS
67 86
68Logging levels in this module range from C<1> (highest priority) to C<9> 87Logging levels in this module range from C<1> (highest priority) to C<9>
69(lowest priority). Note that the lowest numerical value is the highest 88(lowest priority). Note that the lowest numerical value is the highest
… …
71numerical value". 90numerical value".
72 91
73Instead of specifying levels by name you can also specify them by aliases: 92Instead of specifying levels by name you can also specify them by aliases:
74 93
75 LVL NAME SYSLOG PERL NOTE 94 LVL NAME SYSLOG PERL NOTE
76 1 fatal emerg exit aborts program! 95 1 fatal emerg exit system unusable, aborts program!
77 2 alert 96 2 alert failure in primary system
78 3 critical crit 97 3 critical crit failure in backup system
79 4 error err die 98 4 error err die non-urgent program errors, a bug
80 5 warn warning 99 5 warn warning possible problem, not necessarily error
81 6 note notice 100 6 note notice unusual conditions
82 7 info 101 7 info normal messages, no action required
83 8 debug 102 8 debug debugging messages for development
84 9 trace 103 9 trace copious tracing output
85 104
86As you can see, some logging levels have multiple aliases - the first one 105As you can see, some logging levels have multiple aliases - the first one
87is the "official" name, the second one the "syslog" name (if it differs) 106is the "official" name, the second one the "syslog" name (if it differs)
88and the third one the "perl" name, suggesting that you log C<die> messages 107and the third one the "perl" name, suggesting (only!) that you log C<die>
89at C<error> priority. 108messages at C<error> priority. The NOTE column tries to provide some
109rationale on how to chose a logging level.
90 110
111As a rough guideline, levels 1..3 are primarily meant for users of the
112program (admins, staff), and are the only ones logged to STDERR by
113default. Levels 4..6 are meant for users and developers alike, while
114levels 7..9 are usually meant for developers.
115
91You can normally only log a single message at highest priority level 116You can normally only log a message once at highest priority level (C<1>,
92(C<1>, C<fatal>), because logging a fatal message will also quit the 117C<fatal>), because logging a fatal message will also quit the program - so
93program - so use it sparingly :) 118use it sparingly :)
94 119
95Some methods also offer some extra levels, such as C<0>, C<off>, C<none> 120Some methods also offer some extra levels, such as C<0>, C<off>, C<none>
96or C<all> - these are only valid in the methods they are documented for. 121or C<all> - these are only valid for the methods that documented them.
97 122
98=head1 LOGGING FUNCTIONS 123=head1 LOGGING FUNCTIONS
99 124
100These functions allow you to log messages. They always use the caller's 125The following functions allow you to log messages. They always use the
101package as a "logging context". Also, the main logging function C<log> is 126caller's package as a "logging context". Also, the main logging function,
102callable as C<AnyEvent::log> or C<AE::log> when the C<AnyEvent> module is 127C<log>, is aliased to C<AnyEvent::log> and C<AE::log> when the C<AnyEvent>
103loaded. 128module is loaded.
104 129
105=over 4 130=over 4
106 131
107=cut 132=cut
108 133
109package AnyEvent::Log; 134package AnyEvent::Log;
110 135
111use Carp (); 136use Carp ();
112use POSIX (); 137use POSIX ();
113 138
139# layout of a context
140# 0 1 2 3 4, 5
141# [$title, $level, %$slaves, &$logcb, &$fmtcb, $cap]
142
114use AnyEvent (); BEGIN { AnyEvent::common_sense } 143use AnyEvent (); BEGIN { AnyEvent::common_sense }
115use AnyEvent::Util (); 144#use AnyEvent::Util (); need to load this in a delayed fashion, as it uses AE::log
116 145
117our $VERSION = $AnyEvent::VERSION; 146our $VERSION = $AnyEvent::VERSION;
118 147
119our ($COLLECT, $FILTER, $LOG); 148our ($COLLECT, $FILTER, $LOG);
120 149
… …
150=item AnyEvent::Log::log $level, $msg[, @args] 179=item AnyEvent::Log::log $level, $msg[, @args]
151 180
152Requests logging of the given C<$msg> with the given log level, and 181Requests logging of the given C<$msg> with the given log level, and
153returns true if the message was logged I<somewhere>. 182returns true if the message was logged I<somewhere>.
154 183
155For C<fatal> log levels, the program will abort. 184For loglevel C<fatal>, the program will abort.
156 185
157If only a C<$msg> is given, it is logged as-is. With extra C<@args>, the 186If only a C<$msg> is given, it is logged as-is. With extra C<@args>, the
158C<$msg> is interpreted as an sprintf format string. 187C<$msg> is interpreted as an sprintf format string.
159 188
160The C<$msg> should not end with C<\n>, but may if that is convenient for 189The C<$msg> should not end with C<\n>, but may if that is convenient for
… …
162 191
163Last not least, C<$msg> might be a code reference, in which case it is 192Last not least, C<$msg> might be a code reference, in which case it is
164supposed to return the message. It will be called only then the message 193supposed to return the message. It will be called only then the message
165actually gets logged, which is useful if it is costly to create the 194actually gets logged, which is useful if it is costly to create the
166message in the first place. 195message in the first place.
196
197This function takes care of saving and restoring C<$!> and C<$@>, so you
198don't have to.
167 199
168Whether the given message will be logged depends on the maximum log level 200Whether the given message will be logged depends on the maximum log level
169and the caller's package. The return value can be used to ensure that 201and the caller's package. The return value can be used to ensure that
170messages or not "lost" - for example, when L<AnyEvent::Debug> detects a 202messages or not "lost" - for example, when L<AnyEvent::Debug> detects a
171runtime error it tries to log it at C<die> level, but if that message is 203runtime error it tries to log it at C<die> level, but if that message is
… …
205 info => 7, 237 info => 7,
206 debug => 8, 238 debug => 8,
207 trace => 9, 239 trace => 9,
208); 240);
209 241
210sub now () { time } 242our $TIME_EXACT;
243
244sub exact_time($) {
245 $TIME_EXACT = shift;
246 *_ts = $AnyEvent::MODEL
247 ? $TIME_EXACT ? \&AE::now : \&AE::time
248 : sub () { $TIME_EXACT ? do { require Time::HiRes; Time::HiRes::time () } : time };
249}
250
251BEGIN {
252 exact_time 0;
253}
211 254
212AnyEvent::post_detect { 255AnyEvent::post_detect {
213 *now = \&AE::now; 256 exact_time $TIME_EXACT;
214}; 257};
215 258
216our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace); 259our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace);
217 260
218# time, ctx, level, msg 261# time, ctx, level, msg
… …
228 } 271 }
229 272
230 join "", @res 273 join "", @res
231} 274}
232 275
276sub fatal_exit() {
277 exit 1;
278}
279
233sub _log { 280sub _log {
234 my ($ctx, $level, $format, @args) = @_; 281 my ($ctx, $level, $format, @args) = @_;
235 282
236 $level = $level > 0 && $level <= 9 283 $level = $level > 0 && $level <= 9
237 ? $level+0 284 ? $level+0
238 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught"; 285 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught";
239 286
240 my $mask = 1 << $level; 287 my $mask = 1 << $level;
241 288
242 my ($success, %seen, @ctx, $now, $fmt); 289 my ($success, %seen, @ctx, $now, @fmt);
243 290
244 do 291 do
245 { 292 {
246 # skip if masked 293 # if !ref, then it's a level number
294 if (!ref $ctx) {
295 $level = $ctx;
247 if ($ctx->[1] & $mask && !$seen{$ctx+0}++) { 296 } elsif ($ctx->[1] & $mask and !$seen{$ctx+0}++) {
297 # logging/recursing into this context
298
299 # level cap
300 if ($ctx->[5] > $level) {
301 push @ctx, $level; # restore level when going up in tree
302 $level = $ctx->[5];
303 }
304
305 # log if log cb
248 if ($ctx->[3]) { 306 if ($ctx->[3]) {
249 # logging target found 307 # logging target found
308
309 local ($!, $@);
250 310
251 # now get raw message, unless we have it already 311 # now get raw message, unless we have it already
252 unless ($now) { 312 unless ($now) {
253 $format = $format->() if ref $format; 313 $format = $format->() if ref $format;
254 $format = sprintf $format, @args if @args; 314 $format = sprintf $format, @args if @args;
255 $format =~ s/\n$//; 315 $format =~ s/\n$//;
256 $now = AE::now; 316 $now = _ts;
257 }; 317 };
258 318
259 # format msg 319 # format msg
260 my $str = $ctx->[4] 320 my $str = $ctx->[4]
261 ? $ctx->[4]($now, $_[0], $level, $format) 321 ? $ctx->[4]($now, $_[0], $level, $format)
262 : ($fmt ||= _format $now, $_[0], $level, $format); 322 : ($fmt[$level] ||= _format $now, $_[0], $level, $format);
263 323
264 $success = 1; 324 $success = 1;
265 325
266 $ctx->[3]($str) 326 $ctx->[3]($str)
267 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate 327 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate
… …
270 } 330 }
271 } 331 }
272 } 332 }
273 while $ctx = pop @ctx; 333 while $ctx = pop @ctx;
274 334
275 exit 1 if $level <= 1; 335 fatal_exit if $level <= 1;
276 336
277 $success 337 $success
278} 338}
279 339
280sub log($$;@) { 340sub log($$;@) {
281 _log 341 _log
282 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 342 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
283 @_; 343 @_;
284} 344}
285 345
286*AnyEvent::log = *AE::log = \&log;
287
288=item $logger = AnyEvent::Log::logger $level[, \$enabled] 346=item $logger = AnyEvent::Log::logger $level[, \$enabled]
289 347
290Creates a code reference that, when called, acts as if the 348Creates a code reference that, when called, acts as if the
291C<AnyEvent::Log::log> function was called at this point with the given 349C<AnyEvent::Log::log> function was called at this point with the given
292level. C<$logger> is passed a C<$msg> and optional C<@args>, just as with 350level. C<$logger> is passed a C<$msg> and optional C<@args>, just as with
… …
356 414
357 $LOGGER{$logger+0} = $logger; 415 $LOGGER{$logger+0} = $logger;
358 416
359 _reassess $logger+0; 417 _reassess $logger+0;
360 418
419 require AnyEvent::Util unless $AnyEvent::Util::VERSION;
361 my $guard = AnyEvent::Util::guard { 420 my $guard = AnyEvent::Util::guard (sub {
362 # "clean up" 421 # "clean up"
363 delete $LOGGER{$logger+0}; 422 delete $LOGGER{$logger+0};
364 }; 423 });
365 424
366 sub { 425 sub {
367 $guard if 0; # keep guard alive, but don't cause runtime overhead 426 $guard if 0; # keep guard alive, but don't cause runtime overhead
368 427
369 _log $ctx, $level, @_ 428 _log $ctx, $level, @_
… …
374sub logger($;$) { 433sub logger($;$) {
375 _logger 434 _logger
376 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 435 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
377 @_ 436 @_
378} 437}
438
439=item AnyEvent::Log::exact_time $on
440
441By default, C<AnyEvent::Log> will use C<AE::now>, i.e. the cached
442eventloop time, for the log timestamps. After calling this function with a
443true value it will instead resort to C<AE::time>, i.e. fetch the current
444time on each log message. This only makes a difference for event loops
445that actually cache the time (such as L<EV> or L<AnyEvent::Loop>).
446
447This setting can be changed at any time by calling this function.
448
449Since C<AnyEvent::Log> has to work even before the L<AnyEvent> has been
450initialised, this switch will also decide whether to use C<CORE::time> or
451C<Time::HiRes::time> when logging a message before L<AnyEvent> becomes
452available.
379 453
380=back 454=back
381 455
382=head1 LOGGING CONTEXTS 456=head1 LOGGING CONTEXTS
383 457
… …
503This can be used to implement config-file (re-)loading: before loading a 577This can be used to implement config-file (re-)loading: before loading a
504configuration, reset all contexts. 578configuration, reset all contexts.
505 579
506=cut 580=cut
507 581
582our $ORIG_VERBOSE = $AnyEvent::VERBOSE;
583$AnyEvent::VERBOSE = 9;
584
508sub reset { 585sub reset {
509 # hard to kill complex data structures 586 # hard to kill complex data structures
510 # we "recreate" all package loggers and reset the hierarchy 587 # we "recreate" all package loggers and reset the hierarchy
511 while (my ($k, $v) = each %CTX) { 588 while (my ($k, $v) = each %CTX) {
512 @$v = ($k, (1 << 10) - 1 - 1, { }); 589 @$v = ($k, (1 << 10) - 1 - 1, { });
… …
515 } 592 }
516 593
517 @$_ = ($_->[0], (1 << 10) - 1 - 1) 594 @$_ = ($_->[0], (1 << 10) - 1 - 1)
518 for $LOG, $FILTER, $COLLECT; 595 for $LOG, $FILTER, $COLLECT;
519 596
520 $LOG->slaves; 597 #$LOG->slaves;
521 $LOG->title ('$AnyEvent::Log::LOG'); 598 $LOG->title ('$AnyEvent::Log::LOG');
522 $LOG->log_cb (sub { 599 $LOG->log_to_warn;
523 warn shift;
524 0
525 });
526 600
527 $FILTER->slaves ($LOG); 601 $FILTER->slaves ($LOG);
528 $FILTER->title ('$AnyEvent::Log::FILTER'); 602 $FILTER->title ('$AnyEvent::Log::FILTER');
529 $FILTER->level ($AnyEvent::VERBOSE); 603 $FILTER->level ($ORIG_VERBOSE);
530 604
531 $COLLECT->slaves ($FILTER); 605 $COLLECT->slaves ($FILTER);
532 $COLLECT->title ('$AnyEvent::Log::COLLECT'); 606 $COLLECT->title ('$AnyEvent::Log::COLLECT');
533 607
534 _reassess; 608 _reassess;
535} 609}
610
611# override AE::log/logger
612*AnyEvent::log = *AE::log = \&log;
613*AnyEvent::logger = *AE::logger = \&logger;
614
615# convert AnyEvent loggers to AnyEvent::Log loggers
616$_->[0] = ctx $_->[0] # convert "pkg" to "ctx"
617 for values %LOGGER;
536 618
537# create the default logger contexts 619# create the default logger contexts
538$LOG = ctx undef; 620$LOG = ctx undef;
539$FILTER = ctx undef; 621$FILTER = ctx undef;
540$COLLECT = ctx undef; 622$COLLECT = ctx undef;
… …
549package AnyEvent::Log::COLLECT; 631package AnyEvent::Log::COLLECT;
550package AE::Log::COLLECT; 632package AE::Log::COLLECT;
551 633
552package AnyEvent::Log::Ctx; 634package AnyEvent::Log::Ctx;
553 635
554# 0 1 2 3 4
555# [$title, $level, %$slaves, &$logcb, &$fmtcb]
556
557=item $ctx = new AnyEvent::Log::Ctx methodname => param... 636=item $ctx = new AnyEvent::Log::Ctx methodname => param...
558 637
559This is a convenience constructor that makes it simpler to construct 638This is a convenience constructor that makes it simpler to construct
560anonymous logging contexts. 639anonymous logging contexts.
561 640
… …
648 727
649=item $ctx->disable ($level[, $level...]) 728=item $ctx->disable ($level[, $level...])
650 729
651Disables logging for the given levels, leaving all others unchanged. 730Disables logging for the given levels, leaving all others unchanged.
652 731
732=item $ctx->cap ($level)
733
734Caps the maximum priority to the given level, for all messages logged
735to, or passing through, this context. That is, while this doesn't affect
736whether a message is logged or passed on, the maximum priority of messages
737will be limited to the specified level - messages with a higher priority
738will be set to the specified priority.
739
740Another way to view this is that C<< ->level >> filters out messages with
741a too low priority, while C<< ->cap >> modifies messages with a too high
742priority.
743
744This is useful when different log targets have different interpretations
745of priority. For example, for a specific command line program, a wrong
746command line switch might well result in a C<fatal> log message, while the
747same message, logged to syslog, is likely I<not> fatal to the system or
748syslog facility as a whole, but more likely a mere C<error>.
749
750This can be modeled by having a stderr logger that logs messages "as-is"
751and a syslog logger that logs messages with a level cap of, say, C<error>,
752or, for truly system-critical components, actually C<critical>.
753
653=cut 754=cut
654 755
655sub _lvl_lst { 756sub _lvl_lst {
656 map { 757 map {
657 $_ > 0 && $_ <= 9 ? $_+0 758 $_ > 0 && $_ <= 9 ? $_+0
658 : $_ eq "all" ? (1 .. 9) 759 : $_ eq "all" ? (1 .. 9)
659 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught" 760 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught"
660 } @_ 761 } @_
661} 762}
662 763
764sub _lvl {
765 $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1]
766}
767
663our $NOP_CB = sub { 0 }; 768our $NOP_CB = sub { 0 };
664 769
665sub levels { 770sub levels {
666 my $ctx = shift; 771 my $ctx = shift;
667 $ctx->[1] = 0; 772 $ctx->[1] = 0;
… …
670 AnyEvent::Log::_reassess; 775 AnyEvent::Log::_reassess;
671} 776}
672 777
673sub level { 778sub level {
674 my $ctx = shift; 779 my $ctx = shift;
675 my $lvl = $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1];
676
677 $ctx->[1] = ((1 << $lvl) - 1) << 1; 780 $ctx->[1] = ((1 << &_lvl) - 1) << 1;
678 AnyEvent::Log::_reassess; 781 AnyEvent::Log::_reassess;
679} 782}
680 783
681sub enable { 784sub enable {
682 my $ctx = shift; 785 my $ctx = shift;
… …
690 $ctx->[1] &= ~(1 << $_) 793 $ctx->[1] &= ~(1 << $_)
691 for &_lvl_lst; 794 for &_lvl_lst;
692 AnyEvent::Log::_reassess; 795 AnyEvent::Log::_reassess;
693} 796}
694 797
798sub cap {
799 my $ctx = shift;
800 $ctx->[5] = &_lvl;
801}
802
695=back 803=back
696 804
697=head3 SLAVE CONTEXTS 805=head3 SLAVE CONTEXTS
698 806
699The following methods attach and detach another logging context to a 807The following methods attach and detach another logging context to a
… …
791logging context, the (numeric) logging level and the raw message string 899logging context, the (numeric) logging level and the raw message string
792and needs to return a formatted log message. In most cases this will be a 900and needs to return a formatted log message. In most cases this will be a
793string, but it could just as well be an array reference that just stores 901string, but it could just as well be an array reference that just stores
794the values. 902the values.
795 903
796If, for some reaosn, you want to use C<caller> to find out more baout the 904If, for some reason, you want to use C<caller> to find out more about the
797logger then you should walk up the call stack until you are no longer 905logger then you should walk up the call stack until you are no longer
798inside the C<AnyEvent::Log> package. 906inside the C<AnyEvent::Log> package.
799 907
800Example: format just the raw message, with numeric log level in angle 908Example: format just the raw message, with numeric log level in angle
801brackets. 909brackets.
… …
820 "$msg->[3]"; 928 "$msg->[3]";
821 929
822 0 930 0
823 }); 931 });
824 932
933=item $ctx->log_to_warn
934
935Sets the C<log_cb> to simply use C<CORE::warn> to report any messages
936(usually this logs to STDERR).
937
825=item $ctx->log_to_file ($path) 938=item $ctx->log_to_file ($path)
826 939
827Sets the C<log_cb> to log to a file (by appending), unbuffered. 940Sets the C<log_cb> to log to a file (by appending), unbuffered.
828 941
829=item $ctx->log_to_path ($path) 942=item $ctx->log_to_path ($path)
830 943
831Same as C<< ->log_to_file >>, but opens the file for each message. This 944Same 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 945is much slower, but allows you to change/move/rename/delete the file at
833basically any time. 946basically any time.
834 947
948Needless(?) to say, if you do not want to be bitten by some evil person
949calling C<chdir>, the path should be absolute. Doesn't help with
950C<chroot>, but hey...
951
835=item $ctx->log_to_syslog ([$log_flags]) 952=item $ctx->log_to_syslog ([$facility])
836 953
837Logs all messages via L<Sys::Syslog>, mapping C<trace> to C<debug> and all 954Logs all messages via L<Sys::Syslog>, mapping C<trace> to C<debug> and
838the others in the obvious way. If specified, then the C<$log_flags> are 955all the others in the obvious way. If specified, then the C<$facility> is
839simply or'ed onto the priority argument and can contain any C<LOG_xxx> 956used as the facility (C<user>, C<auth>, C<local0> and so on). The default
840flags valid for Sys::Syslog::syslog, except for the priority levels. 957facility is C<user>.
841 958
842Note that this function also sets a C<fmt_cb> - the logging part requires 959Note that this function also sets a C<fmt_cb> - the logging part requires
843an array reference with [$level, $str] as input. 960an array reference with [$level, $str] as input.
844 961
845=cut 962=cut
… …
852 969
853sub fmt_cb { 970sub fmt_cb {
854 my ($ctx, $cb) = @_; 971 my ($ctx, $cb) = @_;
855 972
856 $ctx->[4] = $cb; 973 $ctx->[4] = $cb;
974}
975
976sub log_to_warn {
977 my ($ctx, $path) = @_;
978
979 $ctx->log_cb (sub {
980 warn shift;
981 0
982 });
857} 983}
858 984
859sub log_to_file { 985sub log_to_file {
860 my ($ctx, $path) = @_; 986 my ($ctx, $path) = @_;
861 987
… …
866 syswrite $fh, shift; 992 syswrite $fh, shift;
867 0 993 0
868 }); 994 });
869} 995}
870 996
871sub log_to_file { 997sub log_to_path {
872 my ($ctx, $path) = @_; 998 my ($ctx, $path) = @_;
873 999
874 $ctx->log_cb (sub { 1000 $ctx->log_cb (sub {
875 open my $fh, ">>", $path 1001 open my $fh, ">>", $path
876 or die "$path: $!"; 1002 or die "$path: $!";
… …
879 0 1005 0
880 }); 1006 });
881} 1007}
882 1008
883sub log_to_syslog { 1009sub log_to_syslog {
884 my ($ctx, $flags) = @_; 1010 my ($ctx, $facility) = @_;
885 1011
886 require Sys::Syslog; 1012 require Sys::Syslog;
887 1013
888 $ctx->fmt_cb (sub { 1014 $ctx->fmt_cb (sub {
889 my $str = $_[3]; 1015 my $str = $_[3];
890 $str =~ s/\n(?=.)/\n+ /g; 1016 $str =~ s/\n(?=.)/\n+ /g;
891 1017
892 [$_[2], "($_[1][0]) $str"] 1018 [$_[2], "($_[1][0]) $str"]
893 }); 1019 });
894 1020
1021 $facility ||= "user";
1022
895 $ctx->log_cb (sub { 1023 $ctx->log_cb (sub {
896 my $lvl = $_[0][0] < 9 ? $_[0][0] : 8; 1024 my $lvl = $_[0][0] < 9 ? $_[0][0] : 8;
897 1025
898 Sys::Syslog::syslog ($flags | ($lvl - 1), $_) 1026 Sys::Syslog::syslog ("$facility|" . ($lvl - 1), $_)
899 for split /\n/, $_[0][1]; 1027 for split /\n/, $_[0][1];
900 1028
901 0 1029 0
902 }); 1030 });
903} 1031}
… …
923=cut 1051=cut
924 1052
925*log = \&AnyEvent::Log::_log; 1053*log = \&AnyEvent::Log::_log;
926*logger = \&AnyEvent::Log::_logger; 1054*logger = \&AnyEvent::Log::_logger;
927 1055
1056=back
1057
1058=cut
1059
1060package AnyEvent::Log;
1061
1062=head1 CONFIGURATION VIA $ENV{PERL_ANYEVENT_LOG}
1063
1064Logging can also be configured by setting the environment variable
1065C<PERL_ANYEVENT_LOG> (or C<AE_LOG>).
1066
1067The value consists of one or more logging context specifications separated
1068by C<:> or whitespace. Each logging specification in turn starts with a
1069context name, followed by C<=>, followed by zero or more comma-separated
1070configuration directives, here are some examples:
1071
1072 # set default logging level
1073 filter=warn
1074
1075 # log to file instead of to stderr
1076 log=file=/tmp/mylog
1077
1078 # log to file in addition to stderr
1079 log=+%file:%file=file=/tmp/mylog
1080
1081 # enable debug log messages, log warnings and above to syslog
1082 filter=debug:log=+%warnings:%warnings=warn,syslog=LOG_LOCAL0
1083
1084 # log trace messages (only) from AnyEvent::Debug to file
1085 AnyEvent::Debug=+%trace:%trace=only,trace,file=/tmp/tracelog
1086
1087A context name in the log specification can be any of the following:
1088
1089=over 4
1090
1091=item C<collect>, C<filter>, C<log>
1092
1093Correspond to the three predefined C<$AnyEvent::Log::COLLECT>,
1094C<AnyEvent::Log::FILTER> and C<$AnyEvent::Log::LOG> contexts.
1095
1096=item C<%name>
1097
1098Context names starting with a C<%> are anonymous contexts created when the
1099name is first mentioned. The difference to package contexts is that by
1100default they have no attached slaves.
1101
1102=item a perl package name
1103
1104Any other string references the logging context associated with the given
1105Perl C<package>. In the unlikely case where you want to specify a package
1106context that matches on of the other context name forms, you can add a
1107C<::> to the package name to force interpretation as a package.
1108
1109=back
1110
1111The configuration specifications can be any number of the following:
1112
1113=over 4
1114
1115=item C<stderr>
1116
1117Configures the context to use Perl's C<warn> function (which typically
1118logs to C<STDERR>). Works like C<log_to_warn>.
1119
1120=item C<file=>I<path>
1121
1122Configures the context to log to a file with the given path. Works like
1123C<log_to_file>.
1124
1125=item C<path=>I<path>
1126
1127Configures the context to log to a file with the given path. Works like
1128C<log_to_path>.
1129
1130=item C<syslog> or C<syslog=>I<expr>
1131
1132Configures the context to log to syslog. If I<expr> is given, then it is
1133evaluated in the L<Sys::Syslog> package, so you could use:
1134
1135 log=syslog=LOG_LOCAL0
1136
1137=item C<nolog>
1138
1139Configures the context to not log anything by itself, which is the
1140default. Same as C<< $ctx->log_cb (undef) >>.
1141
1142=item C<cap=>I<level>
1143
1144Caps logging messages entering this context at the given level, i.e.
1145reduces the priority of messages with higher priority than this level. The
1146default is C<0> (or C<off>), meaning the priority will not be touched.
1147
1148=item C<0> or C<off>
1149
1150Sets the logging level of the context to C<0>, i.e. all messages will be
1151filtered out.
1152
1153=item C<all>
1154
1155Enables all logging levels, i.e. filtering will effectively be switched
1156off (the default).
1157
1158=item C<only>
1159
1160Disables all logging levels, and changes the interpretation of following
1161level specifications to enable the specified level only.
1162
1163Example: only enable debug messages for a context.
1164
1165 context=only,debug
1166
1167=item C<except>
1168
1169Enables all logging levels, and changes the interpretation of following
1170level specifications to disable that level. Rarely used.
1171
1172Example: enable all logging levels except fatal and trace (this is rather
1173nonsensical).
1174
1175 filter=exept,fatal,trace
1176
1177=item C<level>
1178
1179Enables all logging levels, and changes the interpretation of following
1180level specifications to be "that level or any higher priority
1181message". This is the default.
1182
1183Example: log anything at or above warn level.
1184
1185 filter=warn
1186
1187 # or, more verbose
1188 filter=only,level,warn
1189
1190=item C<1>..C<9> or a logging level name (C<error>, C<debug> etc.)
1191
1192A numeric loglevel or the name of a loglevel will be interpreted according
1193to the most recent C<only>, C<except> or C<level> directive. By default,
1194specifying a logging level enables that and any higher priority messages.
1195
1196=item C<+>I<context>
1197
1198Attaches the named context as slave to the context.
1199
1200=item C<+>
1201
1202A lone C<+> detaches all contexts, i.e. clears the slave list from the
1203context. Anonymous (C<%name>) contexts have no attached slaves by default,
1204but package contexts have the parent context as slave by default.
1205
1206Example: log messages from My::Module to a file, do not send them to the
1207default log collector.
1208
1209 My::Module=+,file=/tmp/mymodulelog
1210
1211=back
1212
1213Any character can be escaped by prefixing it with a C<\> (backslash), as
1214usual, so to log to a file containing a comma, colon, backslash and some
1215spaces in the filename, you would do this:
1216
1217 PERL_ANYEVENT_LOG='log=file=/some\ \:file\ with\,\ \\-escapes'
1218
1219Since whitespace (which includes newlines) is allowed, it is fine to
1220specify multiple lines in C<PERL_ANYEVENT_LOG>, e.g.:
1221
1222 PERL_ANYEVENT_LOG="
1223 filter=warn
1224 AnyEvent::Debug=+%trace
1225 %trace=only,trace,+log
1226 " myprog
1227
1228Also, in the unlikely case when you want to concatenate specifications,
1229use whitespace as separator, as C<::> will be interpreted as part of a
1230module name, an empty spec with two separators:
1231
1232 PERL_ANYEVENT_LOG="$PERL_ANYEVENT_LOG MyMod=debug"
1233
1234=cut
1235
1236for (my $spec = $ENV{PERL_ANYEVENT_LOG}) {
1237 my %anon;
1238
1239 my $pkg = sub {
1240 $_[0] eq "log" ? $LOG
1241 : $_[0] eq "filter" ? $FILTER
1242 : $_[0] eq "collect" ? $COLLECT
1243 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= do { my $ctx = ctx undef; $ctx->[0] = $_[0]; $ctx })
1244 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/
1245 : die # never reached?
1246 };
1247
1248 /\G[[:space:]]+/gc; # skip initial whitespace
1249
1250 while (/\G((?:[^:=[:space:]]+|::|\\.)+)=/gc) {
1251 my $ctx = $pkg->($1);
1252 my $level = "level";
1253
1254 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) {
1255 for ("$1") {
1256 if ($_ eq "stderr" ) { $ctx->log_to_warn;
1257 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1");
1258 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1");
1259 } elsif (/^syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog ("$1");
1260 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef);
1261 } elsif (/^cap=(.+)/ ) { $ctx->cap ("$1");
1262 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1"));
1263 } elsif ($_ eq "+" ) { $ctx->slaves;
1264 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0);
1265 } elsif ($_ eq "all" ) { $ctx->level ("all");
1266 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level";
1267 } elsif ($_ eq "only" ) { $ctx->level ("off"); $level = "enable";
1268 } elsif ($_ eq "except" ) { $ctx->level ("all"); $level = "disable";
1269 } elsif (/^\d$/ ) { $ctx->$level ($_);
1270 } elsif (exists $STR2LEVEL{$_} ) { $ctx->$level ($_);
1271 } else { die "PERL_ANYEVENT_LOG ($spec): parse error at '$_'\n";
1272 }
1273 }
1274
1275 /\G,/gc or last;
1276 }
1277
1278 /\G[:[:space:]]+/gc or last;
1279 }
1280
1281 /\G[[:space:]]+/gc; # skip trailing whitespace
1282
1283 if (/\G(.+)/g) {
1284 die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n";
1285 }
1286}
1287
9281; 12881;
929 1289
930=back
931
932=head1 EXAMPLES 1290=head1 EXAMPLES
933 1291
934This section shows some common configurations. 1292This section shows some common configurations, both as code, and as
1293C<PERL_ANYEVENT_LOG> string.
935 1294
936=over 4 1295=over 4
937 1296
938=item Setting the global logging level. 1297=item Setting the global logging level.
939 1298
940Either put PERL_ANYEVENT_VERBOSE=<number> into your environment before 1299Either put C<PERL_ANYEVENT_VERBOSE=><number> into your environment before
941running your program, or modify the log level of the root context: 1300running your program, use C<PERL_ANYEVENT_LOG> or modify the log level of
1301the root context at runtime:
942 1302
943 PERL_ANYEVENT_VERBOSE=5 ./myprog 1303 PERL_ANYEVENT_VERBOSE=5 ./myprog
944 1304
1305 PERL_ANYEVENT_LOG=log=warn
1306
945 $AnyEvent::Log::FILTER->level ("warn"); 1307 $AnyEvent::Log::FILTER->level ("warn");
946 1308
947=item Append all messages to a file instead of sending them to STDERR. 1309=item Append all messages to a file instead of sending them to STDERR.
948 1310
949This is affected by the global logging level. 1311This is affected by the global logging level.
950 1312
951 $AnyEvent::Log::LOG->log_to_file ($path); (sub { 1313 $AnyEvent::Log::LOG->log_to_file ($path);
1314
1315 PERL_ANYEVENT_LOG=log=file=/some/path
952 1316
953=item Write all messages with priority C<error> and higher to a file. 1317=item Write all messages with priority C<error> and higher to a file.
954 1318
955This writes them only when the global logging level allows it, because 1319This writes them only when the global logging level allows it, because
956it is attached to the default context which is invoked I<after> global 1320it is attached to the default context which is invoked I<after> global
957filtering. 1321filtering.
958 1322
959 $AnyEvent::Log::FILTER->attach 1323 $AnyEvent::Log::FILTER->attach (
960 new AnyEvent::Log::Ctx log_to_file => $path); 1324 new AnyEvent::Log::Ctx log_to_file => $path);
1325
1326 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
961 1327
962This writes them regardless of the global logging level, because it is 1328This writes them regardless of the global logging level, because it is
963attached to the toplevel context, which receives all messages I<before> 1329attached to the toplevel context, which receives all messages I<before>
964the global filtering. 1330the global filtering.
965 1331
966 $AnyEvent::Log::COLLECT->attach ( 1332 $AnyEvent::Log::COLLECT->attach (
967 new AnyEvent::Log::Ctx log_to_file => $path); 1333 new AnyEvent::Log::Ctx log_to_file => $path);
968 1334
1335 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
1336
969In both cases, messages are still written to STDERR. 1337In both cases, messages are still written to STDERR.
1338
1339=item Additionally log all messages with C<warn> and higher priority to
1340C<syslog>, but cap at C<error>.
1341
1342This logs all messages to the default log target, but also logs messages
1343with priority C<warn> or higher (and not filtered otherwise) to syslog
1344facility C<user>. Messages with priority higher than C<error> will be
1345logged with level C<error>.
1346
1347 $AnyEvent::Log::LOG->attach (
1348 new AnyEvent::Log::Ctx
1349 level => "warn",
1350 cap => "error",
1351 syslog => "user",
1352 );
1353
1354 PERL_ANYEVENT_LOG=log=+%syslog:%syslog=warn,cap=error,syslog
970 1355
971=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s). 1356=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s).
972 1357
973Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug> 1358Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug>
974context - this simply circumvents the global filtering for trace messages. 1359context - this simply circumvents the global filtering for trace messages.
975 1360
976 my $debug = AnyEvent::Debug->AnyEvent::Log::ctx; 1361 my $debug = AnyEvent::Debug->AnyEvent::Log::ctx;
977 $debug->attach ($AnyEvent::Log::LOG); 1362 $debug->attach ($AnyEvent::Log::LOG);
1363
1364 PERL_ANYEVENT_LOG=AnyEvent::Debug=+log
978 1365
979This of course works for any package, not just L<AnyEvent::Debug>, but 1366This of course works for any package, not just L<AnyEvent::Debug>, but
980assumes the log level for AnyEvent::Debug hasn't been changed from the 1367assumes the log level for AnyEvent::Debug hasn't been changed from the
981default. 1368default.
982 1369
… …
986 1373
987 Marc Lehmann <schmorp@schmorp.de> 1374 Marc Lehmann <schmorp@schmorp.de>
988 http://home.schmorp.de/ 1375 http://home.schmorp.de/
989 1376
990=cut 1377=cut
1378

Diff Legend

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