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.29 by root, Thu Aug 25 00:14:32 2011 UTC vs.
Revision 1.49 by root, Thu Mar 22 01:03:57 2012 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 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
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
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<3> (C<critical>), so little
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.
88 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
89You 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>,
90(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
91program - so use it sparingly :) 118use it sparingly :)
92 119
93Some 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>
94or 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.
95 122
96=head1 LOGGING FUNCTIONS 123=head1 LOGGING FUNCTIONS
97 124
98These functions allow you to log messages. They always use the caller's 125The following functions allow you to log messages. They always use the
99package as a "logging context". Also, the main logging function C<log> is 126caller'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 127C<log>, is aliased to C<AnyEvent::log> and C<AE::log> when the C<AnyEvent>
101loaded. 128module is loaded.
102 129
103=over 4 130=over 4
104 131
105=cut 132=cut
106 133
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
… …
160 191
161Last 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
162supposed 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
163actually 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
164message 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.
165 199
166Whether 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
167and 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
168messages or not "lost" - for example, when L<AnyEvent::Debug> detects a 202messages 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 203runtime error it tries to log it at C<die> level, but if that message is
… …
203 info => 7, 237 info => 7,
204 debug => 8, 238 debug => 8,
205 trace => 9, 239 trace => 9,
206); 240);
207 241
208sub 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}
209 254
210AnyEvent::post_detect { 255AnyEvent::post_detect {
211 *now = \&AE::now; 256 exact_time $TIME_EXACT;
212}; 257};
213 258
214our @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);
215 260
216# time, ctx, level, msg 261# time, ctx, level, msg
… …
226 } 271 }
227 272
228 join "", @res 273 join "", @res
229} 274}
230 275
276sub fatal_exit() {
277 exit 1;
278}
279
231sub _log { 280sub _log {
232 my ($ctx, $level, $format, @args) = @_; 281 my ($ctx, $level, $format, @args) = @_;
233 282
234 $level = $level > 0 && $level <= 9 283 $level = $level > 0 && $level <= 9
235 ? $level+0 284 ? $level+0
236 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught"; 285 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught";
237 286
238 my $mask = 1 << $level; 287 my $mask = 1 << $level;
239 288
240 my ($success, %seen, @ctx, $now, $fmt); 289 my ($success, %seen, @ctx, $now, @fmt);
241 290
242 do 291 do
243 { 292 {
244 # skip if masked 293 # if !ref, then it's a level number
294 if (!ref $ctx) {
295 $level = $ctx;
245 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
246 if ($ctx->[3]) { 306 if ($ctx->[3]) {
247 # logging target found 307 # logging target found
308
309 local ($!, $@);
248 310
249 # now get raw message, unless we have it already 311 # now get raw message, unless we have it already
250 unless ($now) { 312 unless ($now) {
251 $format = $format->() if ref $format; 313 $format = $format->() if ref $format;
252 $format = sprintf $format, @args if @args; 314 $format = sprintf $format, @args if @args;
253 $format =~ s/\n$//; 315 $format =~ s/\n$//;
254 $now = AE::now; 316 $now = _ts;
255 }; 317 };
256 318
257 # format msg 319 # format msg
258 my $str = $ctx->[4] 320 my $str = $ctx->[4]
259 ? $ctx->[4]($now, $_[0], $level, $format) 321 ? $ctx->[4]($now, $_[0], $level, $format)
260 : ($fmt ||= _format $now, $_[0], $level, $format); 322 : ($fmt[$level] ||= _format $now, $_[0], $level, $format);
261 323
262 $success = 1; 324 $success = 1;
263 325
264 $ctx->[3]($str) 326 $ctx->[3]($str)
265 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate 327 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate
… …
268 } 330 }
269 } 331 }
270 } 332 }
271 while $ctx = pop @ctx; 333 while $ctx = pop @ctx;
272 334
273 exit 1 if $level <= 1; 335 fatal_exit if $level <= 1;
274 336
275 $success 337 $success
276} 338}
277 339
278sub log($$;@) { 340sub log($$;@) {
279 _log 341 _log
280 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 342 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
281 @_; 343 @_;
282} 344}
283 345
284*AnyEvent::log = *AE::log = \&log;
285
286=item $logger = AnyEvent::Log::logger $level[, \$enabled] 346=item $logger = AnyEvent::Log::logger $level[, \$enabled]
287 347
288Creates a code reference that, when called, acts as if the 348Creates a code reference that, when called, acts as if the
289C<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
290level. 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
… …
354 414
355 $LOGGER{$logger+0} = $logger; 415 $LOGGER{$logger+0} = $logger;
356 416
357 _reassess $logger+0; 417 _reassess $logger+0;
358 418
419 require AnyEvent::Util unless $AnyEvent::Util::VERSION;
359 my $guard = AnyEvent::Util::guard { 420 my $guard = AnyEvent::Util::guard (sub {
360 # "clean up" 421 # "clean up"
361 delete $LOGGER{$logger+0}; 422 delete $LOGGER{$logger+0};
362 }; 423 });
363 424
364 sub { 425 sub {
365 $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
366 427
367 _log $ctx, $level, @_ 428 _log $ctx, $level, @_
… …
372sub logger($;$) { 433sub logger($;$) {
373 _logger 434 _logger
374 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 435 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
375 @_ 436 @_
376} 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.
377 453
378=back 454=back
379 455
380=head1 LOGGING CONTEXTS 456=head1 LOGGING CONTEXTS
381 457
… …
501This 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
502configuration, reset all contexts. 578configuration, reset all contexts.
503 579
504=cut 580=cut
505 581
582our $ORIG_VERBOSE = $AnyEvent::VERBOSE;
583$AnyEvent::VERBOSE = 9;
584
506sub reset { 585sub reset {
507 # hard to kill complex data structures 586 # hard to kill complex data structures
508 # we "recreate" all package loggers and reset the hierarchy 587 # we "recreate" all package loggers and reset the hierarchy
509 while (my ($k, $v) = each %CTX) { 588 while (my ($k, $v) = each %CTX) {
510 @$v = ($k, (1 << 10) - 1 - 1, { }); 589 @$v = ($k, (1 << 10) - 1 - 1, { });
… …
513 } 592 }
514 593
515 @$_ = ($_->[0], (1 << 10) - 1 - 1) 594 @$_ = ($_->[0], (1 << 10) - 1 - 1)
516 for $LOG, $FILTER, $COLLECT; 595 for $LOG, $FILTER, $COLLECT;
517 596
518 $LOG->slaves; 597 #$LOG->slaves;
519 $LOG->title ('$AnyEvent::Log::LOG'); 598 $LOG->title ('$AnyEvent::Log::LOG');
520 $LOG->log_to_warn; 599 $LOG->log_to_warn;
521 600
522 $FILTER->slaves ($LOG); 601 $FILTER->slaves ($LOG);
523 $FILTER->title ('$AnyEvent::Log::FILTER'); 602 $FILTER->title ('$AnyEvent::Log::FILTER');
524 $FILTER->level ($AnyEvent::VERBOSE); 603 $FILTER->level ($ORIG_VERBOSE);
525 604
526 $COLLECT->slaves ($FILTER); 605 $COLLECT->slaves ($FILTER);
527 $COLLECT->title ('$AnyEvent::Log::COLLECT'); 606 $COLLECT->title ('$AnyEvent::Log::COLLECT');
528 607
529 _reassess; 608 _reassess;
530} 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;
531 618
532# create the default logger contexts 619# create the default logger contexts
533$LOG = ctx undef; 620$LOG = ctx undef;
534$FILTER = ctx undef; 621$FILTER = ctx undef;
535$COLLECT = ctx undef; 622$COLLECT = ctx undef;
… …
544package AnyEvent::Log::COLLECT; 631package AnyEvent::Log::COLLECT;
545package AE::Log::COLLECT; 632package AE::Log::COLLECT;
546 633
547package AnyEvent::Log::Ctx; 634package AnyEvent::Log::Ctx;
548 635
549# 0 1 2 3 4
550# [$title, $level, %$slaves, &$logcb, &$fmtcb]
551
552=item $ctx = new AnyEvent::Log::Ctx methodname => param... 636=item $ctx = new AnyEvent::Log::Ctx methodname => param...
553 637
554This is a convenience constructor that makes it simpler to construct 638This is a convenience constructor that makes it simpler to construct
555anonymous logging contexts. 639anonymous logging contexts.
556 640
… …
643 727
644=item $ctx->disable ($level[, $level...]) 728=item $ctx->disable ($level[, $level...])
645 729
646Disables logging for the given levels, leaving all others unchanged. 730Disables logging for the given levels, leaving all others unchanged.
647 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
648=cut 754=cut
649 755
650sub _lvl_lst { 756sub _lvl_lst {
651 map { 757 map {
652 $_ > 0 && $_ <= 9 ? $_+0 758 $_ > 0 && $_ <= 9 ? $_+0
653 : $_ eq "all" ? (1 .. 9) 759 : $_ eq "all" ? (1 .. 9)
654 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught" 760 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught"
655 } @_ 761 } @_
656} 762}
657 763
764sub _lvl {
765 $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1]
766}
767
658our $NOP_CB = sub { 0 }; 768our $NOP_CB = sub { 0 };
659 769
660sub levels { 770sub levels {
661 my $ctx = shift; 771 my $ctx = shift;
662 $ctx->[1] = 0; 772 $ctx->[1] = 0;
… …
665 AnyEvent::Log::_reassess; 775 AnyEvent::Log::_reassess;
666} 776}
667 777
668sub level { 778sub level {
669 my $ctx = shift; 779 my $ctx = shift;
670 my $lvl = $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1];
671
672 $ctx->[1] = ((1 << $lvl) - 1) << 1; 780 $ctx->[1] = ((1 << &_lvl) - 1) << 1;
673 AnyEvent::Log::_reassess; 781 AnyEvent::Log::_reassess;
674} 782}
675 783
676sub enable { 784sub enable {
677 my $ctx = shift; 785 my $ctx = shift;
… …
685 $ctx->[1] &= ~(1 << $_) 793 $ctx->[1] &= ~(1 << $_)
686 for &_lvl_lst; 794 for &_lvl_lst;
687 AnyEvent::Log::_reassess; 795 AnyEvent::Log::_reassess;
688} 796}
689 797
798sub cap {
799 my $ctx = shift;
800 $ctx->[5] = &_lvl;
801}
802
690=back 803=back
691 804
692=head3 SLAVE CONTEXTS 805=head3 SLAVE CONTEXTS
693 806
694The following methods attach and detach another logging context to a 807The following methods attach and detach another logging context to a
… …
786logging context, the (numeric) logging level and the raw message string 899logging context, the (numeric) logging level and the raw message string
787and 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
788string, 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
789the values. 902the values.
790 903
791If, for some reason, 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
792logger 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
793inside the C<AnyEvent::Log> package. 906inside the C<AnyEvent::Log> package.
794 907
795Example: format just the raw message, with numeric log level in angle 908Example: format just the raw message, with numeric log level in angle
796brackets. 909brackets.
… …
834 947
835Needless(?) to say, if you do not want to be bitten by some evil person 948Needless(?) 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 949calling C<chdir>, the path should be absolute. Doesn't help with
837C<chroot>, but hey... 950C<chroot>, but hey...
838 951
839=item $ctx->log_to_syslog ([$log_flags]) 952=item $ctx->log_to_syslog ([$facility])
840 953
841Logs 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
842the 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
843simply 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
844flags valid for Sys::Syslog::syslog, except for the priority levels. 957facility is C<user>.
845 958
846Note 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
847an array reference with [$level, $str] as input. 960an array reference with [$level, $str] as input.
848 961
849=cut 962=cut
… …
892 0 1005 0
893 }); 1006 });
894} 1007}
895 1008
896sub log_to_syslog { 1009sub log_to_syslog {
897 my ($ctx, $flags) = @_; 1010 my ($ctx, $facility) = @_;
898 1011
899 require Sys::Syslog; 1012 require Sys::Syslog;
900 1013
901 $ctx->fmt_cb (sub { 1014 $ctx->fmt_cb (sub {
902 my $str = $_[3]; 1015 my $str = $_[3];
903 $str =~ s/\n(?=.)/\n+ /g; 1016 $str =~ s/\n(?=.)/\n+ /g;
904 1017
905 [$_[2], "($_[1][0]) $str"] 1018 [$_[2], "($_[1][0]) $str"]
906 }); 1019 });
907 1020
1021 $facility ||= "user";
1022
908 $ctx->log_cb (sub { 1023 $ctx->log_cb (sub {
909 my $lvl = $_[0][0] < 9 ? $_[0][0] : 8; 1024 my $lvl = $_[0][0] < 9 ? $_[0][0] : 8;
910 1025
911 Sys::Syslog::syslog ($flags | ($lvl - 1), $_) 1026 Sys::Syslog::syslog ("$facility|" . ($lvl - 1), $_)
912 for split /\n/, $_[0][1]; 1027 for split /\n/, $_[0][1];
913 1028
914 0 1029 0
915 }); 1030 });
916} 1031}
… …
966 # enable debug log messages, log warnings and above to syslog 1081 # enable debug log messages, log warnings and above to syslog
967 filter=debug:log=+%warnings:%warnings=warn,syslog=LOG_LOCAL0 1082 filter=debug:log=+%warnings:%warnings=warn,syslog=LOG_LOCAL0
968 1083
969 # log trace messages (only) from AnyEvent::Debug to file 1084 # log trace messages (only) from AnyEvent::Debug to file
970 AnyEvent::Debug=+%trace:%trace=only,trace,file=/tmp/tracelog 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'
971 1218
972Since whitespace (which includes newlines) is allowed, it is fine to 1219Since whitespace (which includes newlines) is allowed, it is fine to
973specify multiple lines in C<PERL_ANYEVENT_LOG>, e.g.: 1220specify multiple lines in C<PERL_ANYEVENT_LOG>, e.g.:
974 1221
975 PERL_ANYEVENT_LOG=" 1222 PERL_ANYEVENT_LOG="
976 filter=warn 1223 filter=warn
977 AnyEvent::Debug=+%trace 1224 AnyEvent::Debug=+%trace
978 %trace=only,trace,+log 1225 %trace=only,trace,+log
979 " myprog 1226 " myprog
980 1227
981A context name in the log specification can be any of the following: 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:
982 1231
983=over 4 1232 PERL_ANYEVENT_LOG="$PERL_ANYEVENT_LOG MyMod=debug"
984
985=item C<collect>, C<filter>, C<log>
986
987Correspond to the three predefined C<$AnyEvent::Log::COLLECT>,
988C<AnyEvent::Log::FILTER> and C<$AnyEvent::Log::LOG> contexts.
989
990=item C<%name>
991
992Context names starting with a C<%> are anonymous contexts created when the
993name is first mentioned. The difference to package contexts is that by
994default they have no attached slaves.
995
996=item a perl package name
997
998Any other string references the logging context associated with the given
999Perl C<package>. In the unlikely case where you want to specify a package
1000context that matches on of the other context name forms, you can add a
1001C<::> to the package name to force interpretation as a package.
1002
1003=back
1004
1005The configuration specifications can be any number of the following:
1006
1007=over 4
1008
1009=item C<stderr>
1010
1011Configures the context to use Perl's C<warn> function (which typically
1012logs to C<STDERR>). Works like C<log_to_warn>.
1013
1014=item C<file=>I<path>
1015
1016Configures the context to log to a file with the given path. Works like
1017C<log_to_file>.
1018
1019=item C<path=>I<path>
1020
1021Configures the context to log to a file with the given path. Works like
1022C<log_to_path>.
1023
1024=item C<syslog> or C<syslog=>I<expr>
1025
1026Configured the context to log to syslog. If I<expr> is given, then it is
1027evaluated in the L<Sys::Syslog> package, so you could use:
1028
1029 log=syslog=LOG_LOCAL0
1030
1031=item C<nolog>
1032
1033Configures the context to not log anything by itself, which is the
1034default. Same as C<< $ctx->log_cb (undef) >>.
1035
1036=item C<0> or C<off>
1037
1038Sets the logging level of the context ot C<0>, i.e. all messages will be
1039filtered out.
1040
1041=item C<all>
1042
1043Enables all logging levels, i.e. filtering will effectively be switched
1044off (the default).
1045
1046=item C<only>
1047
1048Disables all logging levels, and changes the interpretation of following
1049level specifications to enable the specified level only.
1050
1051Example: only enable debug messages for a context.
1052
1053 context=only,debug
1054
1055=item C<except>
1056
1057Enables all logging levels, and changes the interpretation of following
1058level specifications to disable that level. Rarely used.
1059
1060Example: enable all logging levels except fatal and trace (this is rather
1061nonsensical).
1062
1063 filter=exept,fatal,trace
1064
1065=item C<level>
1066
1067Enables all logging levels, and changes the interpretation of following
1068level specifications to be "that level or any higher priority
1069message". This is the default.
1070
1071Example: log anything at or above warn level.
1072
1073 filter=warn
1074
1075 # or, more verbose
1076 filter=only,level,warn
1077
1078=item C<1>..C<9>, a logging level name (C<error>, C<debug> etc.)
1079
1080A numeric loglevel or the name of a loglevel will be interpreted according
1081to the most recent C<only>, C<except> or C<level> directive. By default,
1082specifying a logging level enables that and any higher priority messages.
1083
1084=item C<+>I<context>
1085
1086Adds/attaches the named context as slave to the context.
1087
1088=item C<+>
1089
1090A line C<+> clears the slave list form the context. Anonymous (C<%name>)
1091contexts have no slaves by default, but package contexts have the parent
1092context as slave by default.
1093
1094Example: log messages from My::Module to a file, do not send them to the
1095default log collector.
1096
1097 My::Module=+,file=/tmp/mymodulelog
1098
1099=back
1100 1233
1101=cut 1234=cut
1102 1235
1103for (my $spec = $ENV{PERL_ANYEVENT_LOG}) { 1236for (my $spec = $ENV{PERL_ANYEVENT_LOG}) {
1104 my %anon; 1237 my %anon;
1105 1238
1106 my $pkg = sub { 1239 my $pkg = sub {
1107 $_[0] eq "log" ? $LOG 1240 $_[0] eq "log" ? $LOG
1108 : $_[0] eq "filter" ? $FILTER 1241 : $_[0] eq "filter" ? $FILTER
1109 : $_[0] eq "collect" ? $COLLECT 1242 : $_[0] eq "collect" ? $COLLECT
1110 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= ctx undef) 1243 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= do { my $ctx = ctx undef; $ctx->[0] = $_[0]; $ctx })
1111 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/ 1244 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/
1112 : die # never reached? 1245 : die # never reached?
1113 }; 1246 };
1114 1247
1115 /\G[[:space:]]+/gc; # skip initial whitespace 1248 /\G[[:space:]]+/gc; # skip initial whitespace
… …
1121 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) { 1254 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) {
1122 for ("$1") { 1255 for ("$1") {
1123 if ($_ eq "stderr" ) { $ctx->log_to_warn; 1256 if ($_ eq "stderr" ) { $ctx->log_to_warn;
1124 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1"); 1257 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1");
1125 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1"); 1258 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1");
1126 } elsif (/syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog (eval "package Sys::Syslog; $1"); 1259 } elsif (/^syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog ("$1");
1127 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef); 1260 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef);
1261 } elsif (/^cap=(.+)/ ) { $ctx->cap ("$1");
1128 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1")); 1262 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1"));
1129 } elsif ($_ eq "+" ) { $ctx->slaves; 1263 } elsif ($_ eq "+" ) { $ctx->slaves;
1130 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0); 1264 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0);
1131 } elsif ($_ eq "all" ) { $ctx->level ("all"); 1265 } elsif ($_ eq "all" ) { $ctx->level ("all");
1132 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level"; 1266 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level";
… …
1184 1318
1185This writes them only when the global logging level allows it, because 1319This writes them only when the global logging level allows it, because
1186it 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
1187filtering. 1321filtering.
1188 1322
1189 $AnyEvent::Log::FILTER->attach 1323 $AnyEvent::Log::FILTER->attach (
1190 new AnyEvent::Log::Ctx log_to_file => $path); 1324 new AnyEvent::Log::Ctx log_to_file => $path);
1191 1325
1192 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path 1326 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
1193 1327
1194This writes them regardless of the global logging level, because it is 1328This writes them regardless of the global logging level, because it is
… …
1200 1334
1201 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger 1335 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
1202 1336
1203In both cases, messages are still written to STDERR. 1337In both cases, messages are still written to STDERR.
1204 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
1355
1205=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).
1206 1357
1207Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug> 1358Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug>
1208context - this simply circumvents the global filtering for trace messages. 1359context - this simply circumvents the global filtering for trace messages.
1209 1360

Diff Legend

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