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.45 by root, Sun Oct 2 00:42:04 2011 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 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 alraedy 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
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
… …
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
… …
49will 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
50before starting your program, or change the logging level at runtime with 68before starting your program, or change the logging level at runtime with
51something like: 69something like:
52 70
53 use AnyEvent::Log; 71 use AnyEvent::Log;
54 AnyEvent::Log::FILTER->level ("info"); 72 $AnyEvent::Log::FILTER->level ("info");
55 73
56The 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),
57but 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
58extensive enough for the most common tasks, such as logging to multiple 76extensive enough for the most common tasks, such as logging to multiple
59targets, or being able to log into a database. 77targets, or being able to log into a database.
60 78
79The module is also usable before AnyEvent itself is initialised, in which
80case some of the functionality might be reduced.
81
61The amount of documentation might indicate otherwise, but the module is 82The amount of documentation might indicate otherwise, but the runtime part
62still just below 300 lines of code. 83of the module is still just below 300 lines of code.
63 84
64=head1 LOGGING LEVELS 85=head1 LOGGING LEVELS
65 86
66Logging 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>
67(lowest priority). Note that the lowest numerical value is the highest 88(lowest priority). Note that the lowest numerical value is the highest
… …
69numerical value". 90numerical value".
70 91
71Instead 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:
72 93
73 LVL NAME SYSLOG PERL NOTE 94 LVL NAME SYSLOG PERL NOTE
74 1 fatal emerg exit aborts program! 95 1 fatal emerg exit system unusable, aborts program!
75 2 alert 96 2 alert failure in primary system
76 3 critical crit 97 3 critical crit failure in backup system
77 4 error err die 98 4 error err die non-urgent program errors, a bug
78 5 warn warning 99 5 warn warning possible problem, not necessarily error
79 6 note notice 100 6 note notice unusual conditions
80 7 info 101 7 info normal messages, no action required
81 8 debug 102 8 debug debugging messages for development
82 9 trace 103 9 trace copious tracing output
83 104
84As 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
85is 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)
86and 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>
87at C<error> priority. 108messages at C<error> priority. The NOTE column tries to provide some
109rationale on how to chose a logging level.
110
111As a rough guideline, levels 1..3 are primarily meant for users of
112the program (admins, staff), and are the only logged to STDERR by
113default. Levels 4..6 are meant for users and developers alike, while
114levels 7..9 are usually meant for developers.
88 115
89You can normally only log a single message at highest priority level 116You can normally only log a single message at highest priority level
90(C<1>, C<fatal>), because logging a fatal message will also quit the 117(C<1>, C<fatal>), because logging a fatal message will also quit the
91program - so use it sparingly :) 118program - so use it sparingly :)
92 119
… …
107package AnyEvent::Log; 134package AnyEvent::Log;
108 135
109use Carp (); 136use Carp ();
110use POSIX (); 137use POSIX ();
111 138
139# layout of a context
140# 0 1 2 3 4, 5
141# [$title, $level, %$slaves, &$logcb, &$fmtcb, $cap]
142
112use AnyEvent (); BEGIN { AnyEvent::common_sense } 143use AnyEvent (); BEGIN { AnyEvent::common_sense }
113use AnyEvent::Util (); 144#use AnyEvent::Util (); need to load this in a delayed fashion, as it uses AE::log
114 145
115our $VERSION = $AnyEvent::VERSION; 146our $VERSION = $AnyEvent::VERSION;
116 147
117our ($COLLECT, $FILTER, $LOG); 148our ($COLLECT, $FILTER, $LOG);
118 149
… …
148=item AnyEvent::Log::log $level, $msg[, @args] 179=item AnyEvent::Log::log $level, $msg[, @args]
149 180
150Requests 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
151returns true if the message was logged I<somewhere>. 182returns true if the message was logged I<somewhere>.
152 183
153For C<fatal> log levels, the program will abort. 184For loglevel C<fatal>, the program will abort.
154 185
155If 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
156C<$msg> is interpreted as an sprintf format string. 187C<$msg> is interpreted as an sprintf format string.
157 188
158The 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
… …
203 info => 7, 234 info => 7,
204 debug => 8, 235 debug => 8,
205 trace => 9, 236 trace => 9,
206); 237);
207 238
208sub now () { time } 239our $TIME_EXACT;
240
241sub exact_time($) {
242 $TIME_EXACT = shift;
243 *_ts = $AnyEvent::MODEL
244 ? $TIME_EXACT ? \&AE::now : \&AE::time
245 : sub () { $TIME_EXACT ? do { require Time::HiRes; Time::HiRes::time () } : time };
246}
247
248BEGIN {
249 exact_time 0;
250}
209 251
210AnyEvent::post_detect { 252AnyEvent::post_detect {
211 *now = \&AE::now; 253 exact_time $TIME_EXACT;
212}; 254};
213 255
214our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace); 256our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace);
215 257
216# time, ctx, level, msg 258# time, ctx, level, msg
… …
226 } 268 }
227 269
228 join "", @res 270 join "", @res
229} 271}
230 272
273sub fatal_exit() {
274 exit 1;
275}
276
231sub _log { 277sub _log {
232 my ($ctx, $level, $format, @args) = @_; 278 my ($ctx, $level, $format, @args) = @_;
233 279
234 $level = $level > 0 && $level <= 9 280 $level = $level > 0 && $level <= 9
235 ? $level+0 281 ? $level+0
236 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught"; 282 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught";
237 283
238 my $mask = 1 << $level; 284 my $mask = 1 << $level;
239 285
240 my ($success, %seen, @ctx, $now, $fmt); 286 my ($success, %seen, @ctx, $now, @fmt);
241 287
242 do 288 do
243 { 289 {
244 # skip if masked 290 # if !ref, then it's a level number
291 if (!ref $ctx) {
292 $level = $ctx;
245 if ($ctx->[1] & $mask && !$seen{$ctx+0}++) { 293 } elsif ($ctx->[1] & $mask and !$seen{$ctx+0}++) {
294 # logging/recursing into this context
295
296 # level cap
297 if ($ctx->[5] > $level) {
298 push @ctx, $level; # restore level when going up in tree
299 $level = $ctx->[5];
300 }
301
302 # log if log cb
246 if ($ctx->[3]) { 303 if ($ctx->[3]) {
247 # logging target found 304 # logging target found
248 305
249 # now get raw message, unless we have it already 306 # now get raw message, unless we have it already
250 unless ($now) { 307 unless ($now) {
251 $format = $format->() if ref $format; 308 $format = $format->() if ref $format;
252 $format = sprintf $format, @args if @args; 309 $format = sprintf $format, @args if @args;
253 $format =~ s/\n$//; 310 $format =~ s/\n$//;
254 $now = now; 311 $now = _ts;
255 }; 312 };
256 313
257 # format msg 314 # format msg
258 my $str = $ctx->[4] 315 my $str = $ctx->[4]
259 ? $ctx->[4]($now, $_[0], $level, $format) 316 ? $ctx->[4]($now, $_[0], $level, $format)
260 : ($fmt ||= _format $now, $_[0], $level, $format); 317 : ($fmt[$level] ||= _format $now, $_[0], $level, $format);
261 318
262 $success = 1; 319 $success = 1;
263 320
264 $ctx->[3]($str) 321 $ctx->[3]($str)
265 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate 322 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate
… …
268 } 325 }
269 } 326 }
270 } 327 }
271 while $ctx = pop @ctx; 328 while $ctx = pop @ctx;
272 329
273 exit 1 if $level <= 1; 330 fatal_exit if $level <= 1;
274 331
275 $success 332 $success
276} 333}
277 334
278sub log($$;@) { 335sub log($$;@) {
279 _log 336 _log
280 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 337 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
281 @_; 338 @_;
282} 339}
283 340
284*AnyEvent::log = *AE::log = \&log;
285
286=item $logger = AnyEvent::Log::logger $level[, \$enabled] 341=item $logger = AnyEvent::Log::logger $level[, \$enabled]
287 342
288Creates a code reference that, when called, acts as if the 343Creates a code reference that, when called, acts as if the
289C<AnyEvent::Log::log> function was called at this point with the given 344C<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 345level. C<$logger> is passed a C<$msg> and optional C<@args>, just as with
… …
354 409
355 $LOGGER{$logger+0} = $logger; 410 $LOGGER{$logger+0} = $logger;
356 411
357 _reassess $logger+0; 412 _reassess $logger+0;
358 413
414 require AnyEvent::Util unless $AnyEvent::Util::VERSION;
359 my $guard = AnyEvent::Util::guard { 415 my $guard = AnyEvent::Util::guard (sub {
360 # "clean up" 416 # "clean up"
361 delete $LOGGER{$logger+0}; 417 delete $LOGGER{$logger+0};
362 }; 418 });
363 419
364 sub { 420 sub {
365 $guard if 0; # keep guard alive, but don't cause runtime overhead 421 $guard if 0; # keep guard alive, but don't cause runtime overhead
366 422
367 _log $ctx, $level, @_ 423 _log $ctx, $level, @_
… …
372sub logger($;$) { 428sub logger($;$) {
373 _logger 429 _logger
374 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 430 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
375 @_ 431 @_
376} 432}
433
434=item AnyEvent::Log::exact_time $on
435
436By default, C<AnyEvent::Log> will use C<AE::now>, i.e. the cached
437eventloop time, for the log timestamps. After calling this function with a
438true value it will instead resort to C<AE::time>, i.e. fetch the current
439time on each log message. This only makes a difference for event loops
440that actually cache the time (such as L<EV> or L<AnyEvent::Loop>).
441
442This setting can be changed at any time by calling this function.
443
444Since C<AnyEvent::Log> has to work even before the L<AnyEvent> has been
445initialised, this switch will also decide whether to use C<CORE::time> or
446C<Time::HiRes::time> when logging a message before L<AnyEvent> becomes
447available.
377 448
378=back 449=back
379 450
380=head1 LOGGING CONTEXTS 451=head1 LOGGING CONTEXTS
381 452
… …
501This can be used to implement config-file (re-)loading: before loading a 572This can be used to implement config-file (re-)loading: before loading a
502configuration, reset all contexts. 573configuration, reset all contexts.
503 574
504=cut 575=cut
505 576
577our $ORIG_VERBOSE = $AnyEvent::VERBOSE;
578$AnyEvent::VERBOSE = 9;
579
506sub reset { 580sub reset {
507 # hard to kill complex data structures 581 # hard to kill complex data structures
508 # we "recreate" all package loggers and reset the hierarchy 582 # we "recreate" all package loggers and reset the hierarchy
509 while (my ($k, $v) = each %CTX) { 583 while (my ($k, $v) = each %CTX) {
510 @$v = ($k, (1 << 10) - 1 - 1, { }); 584 @$v = ($k, (1 << 10) - 1 - 1, { });
… …
513 } 587 }
514 588
515 @$_ = ($_->[0], (1 << 10) - 1 - 1) 589 @$_ = ($_->[0], (1 << 10) - 1 - 1)
516 for $LOG, $FILTER, $COLLECT; 590 for $LOG, $FILTER, $COLLECT;
517 591
518 $LOG->slaves; 592 #$LOG->slaves;
519 $LOG->title ('$AnyEvent::Log::LOG'); 593 $LOG->title ('$AnyEvent::Log::LOG');
520 $LOG->log_to_warn; 594 $LOG->log_to_warn;
521 595
522 $FILTER->slaves ($LOG); 596 $FILTER->slaves ($LOG);
523 $FILTER->title ('$AnyEvent::Log::FILTER'); 597 $FILTER->title ('$AnyEvent::Log::FILTER');
524 $FILTER->level ($AnyEvent::VERBOSE); 598 $FILTER->level ($ORIG_VERBOSE);
525 599
526 $COLLECT->slaves ($FILTER); 600 $COLLECT->slaves ($FILTER);
527 $COLLECT->title ('$AnyEvent::Log::COLLECT'); 601 $COLLECT->title ('$AnyEvent::Log::COLLECT');
528 602
529 _reassess; 603 _reassess;
530} 604}
605
606# override AE::log/logger
607*AnyEvent::log = *AE::log = \&log;
608*AnyEvent::logger = *AE::logger = \&logger;
609
610# convert AnyEvent loggers to AnyEvent::Log loggers
611$_->[0] = ctx $_->[0] # convert "pkg" to "ctx"
612 for values %LOGGER;
531 613
532# create the default logger contexts 614# create the default logger contexts
533$LOG = ctx undef; 615$LOG = ctx undef;
534$FILTER = ctx undef; 616$FILTER = ctx undef;
535$COLLECT = ctx undef; 617$COLLECT = ctx undef;
… …
544package AnyEvent::Log::COLLECT; 626package AnyEvent::Log::COLLECT;
545package AE::Log::COLLECT; 627package AE::Log::COLLECT;
546 628
547package AnyEvent::Log::Ctx; 629package AnyEvent::Log::Ctx;
548 630
549# 0 1 2 3 4
550# [$title, $level, %$slaves, &$logcb, &$fmtcb]
551
552=item $ctx = new AnyEvent::Log::Ctx methodname => param... 631=item $ctx = new AnyEvent::Log::Ctx methodname => param...
553 632
554This is a convenience constructor that makes it simpler to construct 633This is a convenience constructor that makes it simpler to construct
555anonymous logging contexts. 634anonymous logging contexts.
556 635
… …
643 722
644=item $ctx->disable ($level[, $level...]) 723=item $ctx->disable ($level[, $level...])
645 724
646Disables logging for the given levels, leaving all others unchanged. 725Disables logging for the given levels, leaving all others unchanged.
647 726
727=item $ctx->cap ($level)
728
729Caps the maximum priority to the given level, for all messages logged
730to, or passing through, this context. That is, while this doesn't affect
731whether a message is logged or passed on, the maximum priority of messages
732will be limited to the specified level - messages with a higher priority
733will be set to the specified priority.
734
735Another way to view this is that C<< ->level >> filters out messages with
736a too low priority, while C<< ->cap >> modifies messages with a too high
737priority.
738
739This is useful when different log targets have different interpretations
740of priority. For example, for a specific command line program, a wrong
741command line switch might well result in a C<fatal> log message, while the
742same message, logged to syslog, is likely I<not> fatal to the system or
743syslog facility as a whole, but more likely a mere C<error>.
744
745This can be modeled by having a stderr logger that logs messages "as-is"
746and a syslog logger that logs messages with a level cap of, say, C<error>,
747or, for truly system-critical components, actually C<critical>.
748
648=cut 749=cut
649 750
650sub _lvl_lst { 751sub _lvl_lst {
651 map { 752 map {
652 $_ > 0 && $_ <= 9 ? $_+0 753 $_ > 0 && $_ <= 9 ? $_+0
653 : $_ eq "all" ? (1 .. 9) 754 : $_ eq "all" ? (1 .. 9)
654 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught" 755 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught"
655 } @_ 756 } @_
656} 757}
657 758
759sub _lvl {
760 $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1]
761}
762
658our $NOP_CB = sub { 0 }; 763our $NOP_CB = sub { 0 };
659 764
660sub levels { 765sub levels {
661 my $ctx = shift; 766 my $ctx = shift;
662 $ctx->[1] = 0; 767 $ctx->[1] = 0;
… …
665 AnyEvent::Log::_reassess; 770 AnyEvent::Log::_reassess;
666} 771}
667 772
668sub level { 773sub level {
669 my $ctx = shift; 774 my $ctx = shift;
670 my $lvl = $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1];
671
672 $ctx->[1] = ((1 << $lvl) - 1) << 1; 775 $ctx->[1] = ((1 << &_lvl) - 1) << 1;
673 AnyEvent::Log::_reassess; 776 AnyEvent::Log::_reassess;
674} 777}
675 778
676sub enable { 779sub enable {
677 my $ctx = shift; 780 my $ctx = shift;
… …
685 $ctx->[1] &= ~(1 << $_) 788 $ctx->[1] &= ~(1 << $_)
686 for &_lvl_lst; 789 for &_lvl_lst;
687 AnyEvent::Log::_reassess; 790 AnyEvent::Log::_reassess;
688} 791}
689 792
793sub cap {
794 my $ctx = shift;
795 $ctx->[5] = &_lvl;
796}
797
690=back 798=back
691 799
692=head3 SLAVE CONTEXTS 800=head3 SLAVE CONTEXTS
693 801
694The following methods attach and detach another logging context to a 802The following methods attach and detach another logging context to a
… …
834 942
835Needless(?) to say, if you do not want to be bitten by some evil person 943Needless(?) 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 944calling C<chdir>, the path should be absolute. Doesn't help with
837C<chroot>, but hey... 945C<chroot>, but hey...
838 946
839=item $ctx->log_to_syslog ([$log_flags]) 947=item $ctx->log_to_syslog ([$facility])
840 948
841Logs all messages via L<Sys::Syslog>, mapping C<trace> to C<debug> and all 949Logs 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 950all 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> 951used 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. 952facility is C<user>.
845 953
846Note that this function also sets a C<fmt_cb> - the logging part requires 954Note that this function also sets a C<fmt_cb> - the logging part requires
847an array reference with [$level, $str] as input. 955an array reference with [$level, $str] as input.
848 956
849=cut 957=cut
… …
892 0 1000 0
893 }); 1001 });
894} 1002}
895 1003
896sub log_to_syslog { 1004sub log_to_syslog {
897 my ($ctx, $flags) = @_; 1005 my ($ctx, $facility) = @_;
898 1006
899 require Sys::Syslog; 1007 require Sys::Syslog;
900 1008
901 $ctx->fmt_cb (sub { 1009 $ctx->fmt_cb (sub {
902 my $str = $_[3]; 1010 my $str = $_[3];
903 $str =~ s/\n(?=.)/\n+ /g; 1011 $str =~ s/\n(?=.)/\n+ /g;
904 1012
905 [$_[2], "($_[1][0]) $str"] 1013 [$_[2], "($_[1][0]) $str"]
906 }); 1014 });
907 1015
1016 $facility ||= "user";
1017
908 $ctx->log_cb (sub { 1018 $ctx->log_cb (sub {
909 my $lvl = $_[0][0] < 9 ? $_[0][0] : 8; 1019 my $lvl = $_[0][0] < 9 ? $_[0][0] : 8;
910 1020
911 Sys::Syslog::syslog ($flags | ($lvl - 1), $_) 1021 Sys::Syslog::syslog ("$facility|" . ($lvl - 1), $_)
912 for split /\n/, $_[0][1]; 1022 for split /\n/, $_[0][1];
913 1023
914 0 1024 0
915 }); 1025 });
916} 1026}
… …
1012Configures the context to log to a file with the given path. Works like 1122Configures the context to log to a file with the given path. Works like
1013C<log_to_path>. 1123C<log_to_path>.
1014 1124
1015=item C<syslog> or C<syslog=>I<expr> 1125=item C<syslog> or C<syslog=>I<expr>
1016 1126
1017Configured the context to log to syslog. If I<expr> is given, then it is 1127Configures 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: 1128evaluated in the L<Sys::Syslog> package, so you could use:
1019 1129
1020 log=syslog=LOG_LOCAL0 1130 log=syslog=LOG_LOCAL0
1021 1131
1022=item C<nolog> 1132=item C<nolog>
1023 1133
1024Configures the context to not log anything by itself, which is the 1134Configures the context to not log anything by itself, which is the
1025default. Same as C<< $ctx->log_cb (undef) >>. 1135default. Same as C<< $ctx->log_cb (undef) >>.
1026 1136
1137=item C<cap=>I<level>
1138
1139Caps logging messages entering this context at the given level, i.e.
1140reduces the priority of messages with higher priority than this level. The
1141default is C<0> (or C<off>), meaning the priority will not be touched.
1142
1027=item C<0> or C<off> 1143=item C<0> or C<off>
1028 1144
1029Sets the logging level of the context ot C<0>, i.e. all messages will be 1145Sets the logging level of the context to C<0>, i.e. all messages will be
1030filtered out. 1146filtered out.
1031 1147
1032=item C<all> 1148=item C<all>
1033 1149
1034Enables all logging levels, i.e. filtering will effectively be switched 1150Enables all logging levels, i.e. filtering will effectively be switched
… …
1064 filter=warn 1180 filter=warn
1065 1181
1066 # or, more verbose 1182 # or, more verbose
1067 filter=only,level,warn 1183 filter=only,level,warn
1068 1184
1069=item C<1>..C<9>, a logging level name (C<error>, C<debug> etc.) 1185=item C<1>..C<9> or a logging level name (C<error>, C<debug> etc.)
1070 1186
1071A numeric loglevel or the name of a loglevel will be interpreted according 1187A 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, 1188to the most recent C<only>, C<except> or C<level> directive. By default,
1073specifying a logging level enables that and any higher priority messages. 1189specifying a logging level enables that and any higher priority messages.
1074 1190
1075=item C<+>I<context> 1191=item C<+>I<context>
1076 1192
1077Adds/attaches the named context as slave to the context. 1193Attaches the named context as slave to the context.
1078 1194
1079=item C<+> 1195=item C<+>
1080 1196
1081A line C<+> clears the slave list form the context. Anonymous (C<%name>) 1197A line C<+> detaches all contexts, i.e. clears the slave list from the
1082contexts have no slaves by default, but package contexts have the parent 1198context. Anonymous (C<%name>) contexts have no attached slaves by default,
1083context as slave by default. 1199but package contexts have the parent context as slave by default.
1084 1200
1085Example: log messages from My::Module to a file, do not send them to the 1201Example: log messages from My::Module to a file, do not send them to the
1086default log collector. 1202default log collector.
1087 1203
1088 My::Module=+,file=/tmp/mymodulelog 1204 My::Module=+,file=/tmp/mymodulelog
1089 1205
1090=back 1206=back
1091 1207
1092Any character can be escaped by prefixing it with a C<\> (backslash), as 1208Any 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 1209usual, so to log to a file containing a comma, colon, backslash and some
1094filename, you would do this: 1210spaces in the filename, you would do this:
1095 1211
1096 PERL_ANYEVENT_LOG='log=file=/some\ \:file\ with\,\ \\-escapes' 1212 PERL_ANYEVENT_LOG='log=file=/some\ \:file\ with\,\ \\-escapes'
1097 1213
1098Since whitespace (which includes newlines) is allowed, it is fine to 1214Since whitespace (which includes newlines) is allowed, it is fine to
1099specify multiple lines in C<PERL_ANYEVENT_LOG>, e.g.: 1215specify multiple lines in C<PERL_ANYEVENT_LOG>, e.g.:
… …
1117 1233
1118 my $pkg = sub { 1234 my $pkg = sub {
1119 $_[0] eq "log" ? $LOG 1235 $_[0] eq "log" ? $LOG
1120 : $_[0] eq "filter" ? $FILTER 1236 : $_[0] eq "filter" ? $FILTER
1121 : $_[0] eq "collect" ? $COLLECT 1237 : $_[0] eq "collect" ? $COLLECT
1122 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= ctx undef) 1238 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= do { my $ctx = ctx undef; $ctx->[0] = $_[0]; $ctx })
1123 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/ 1239 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/
1124 : die # never reached? 1240 : die # never reached?
1125 }; 1241 };
1126 1242
1127 /\G[[:space:]]+/gc; # skip initial whitespace 1243 /\G[[:space:]]+/gc; # skip initial whitespace
… …
1133 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) { 1249 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) {
1134 for ("$1") { 1250 for ("$1") {
1135 if ($_ eq "stderr" ) { $ctx->log_to_warn; 1251 if ($_ eq "stderr" ) { $ctx->log_to_warn;
1136 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1"); 1252 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1");
1137 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1"); 1253 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1");
1138 } elsif (/syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog (eval "package Sys::Syslog; $1"); 1254 } elsif (/^syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog ("$1");
1139 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef); 1255 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef);
1256 } elsif (/^cap=(.+)/ ) { $ctx->cap ("$1");
1140 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1")); 1257 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1"));
1141 } elsif ($_ eq "+" ) { $ctx->slaves; 1258 } elsif ($_ eq "+" ) { $ctx->slaves;
1142 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0); 1259 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0);
1143 } elsif ($_ eq "all" ) { $ctx->level ("all"); 1260 } elsif ($_ eq "all" ) { $ctx->level ("all");
1144 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level"; 1261 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level";
… …
1196 1313
1197This writes them only when the global logging level allows it, because 1314This writes them only when the global logging level allows it, because
1198it is attached to the default context which is invoked I<after> global 1315it is attached to the default context which is invoked I<after> global
1199filtering. 1316filtering.
1200 1317
1201 $AnyEvent::Log::FILTER->attach 1318 $AnyEvent::Log::FILTER->attach (
1202 new AnyEvent::Log::Ctx log_to_file => $path); 1319 new AnyEvent::Log::Ctx log_to_file => $path);
1203 1320
1204 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path 1321 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
1205 1322
1206This writes them regardless of the global logging level, because it is 1323This writes them regardless of the global logging level, because it is
… …
1212 1329
1213 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger 1330 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
1214 1331
1215In both cases, messages are still written to STDERR. 1332In both cases, messages are still written to STDERR.
1216 1333
1334=item Additionally log all messages with C<warn> and higher priority to
1335C<syslog>, but cap at C<error>.
1336
1337This logs all messages to the default log target, but also logs messages
1338with priority C<warn> or higher (and not filtered otherwise) to syslog
1339facility C<user>. Messages with priority higher than C<error> will be
1340logged with level C<error>.
1341
1342 $AnyEvent::Log::LOG->attach (
1343 new AnyEvent::Log::Ctx
1344 level => "warn",
1345 cap => "error",
1346 syslog => "user",
1347 );
1348
1349 PERL_ANYEVENT_LOG=log=+%syslog:%syslog=warn,cap=error,syslog
1350
1217=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s). 1351=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s).
1218 1352
1219Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug> 1353Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug>
1220context - this simply circumvents the global filtering for trace messages. 1354context - this simply circumvents the global filtering for trace messages.
1221 1355

Diff Legend

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