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.54 by root, Tue Mar 27 23:47: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 fatal => "No config found, cannot continue!"; # never returns
12 AE::log warn => "it's a bit too hot"; 12 AE::log alert => "The battery died!";
13 AE::log error => "the flag was false!"; 13 AE::log crit => "The battery temperature is too hot!";
14 AE::log fatal => "the bit toggled! run!"; # never returns 14 AE::log error => "Division by zero attempted.";
15 AE::log warn => "Couldn't delete the file.";
16 AE::log note => "Wanted to create config, but config already exists.";
17 AE::log info => "File soandso successfully deleted.";
18 AE::log debug => "the function returned 3";
19 AE::log trace => "going to call function abc";
15 20
21Log level overview:
22
23 LVL NAME SYSLOG PERL NOTE
24 1 fatal emerg exit system unusable, aborts program!
25 2 alert failure in primary system
26 3 critical crit failure in backup system
27 4 error err die non-urgent program errors, a bug
28 5 warn warning possible problem, not necessarily error
29 6 note notice unusual conditions
30 7 info normal messages, no action required
31 8 debug debugging messages for development
32 9 trace copious tracing output
33
16"Complex" uses (for speed sensitive code): 34"Complex" uses (for speed sensitive code, e.g. trace/debug messages):
17 35
18 use AnyEvent::Log; 36 use AnyEvent::Log;
19 37
20 my $tracer = AnyEvent::Log::logger trace => \$my $trace; 38 my $tracer = AnyEvent::Log::logger trace => \$my $trace;
21 39
… …
32 50
33 # send all critical and higher priority messages to syslog, 51 # send all critical and higher priority messages to syslog,
34 # regardless of (most) other settings 52 # regardless of (most) other settings
35 $AnyEvent::Log::COLLECT->attach (new AnyEvent::Log::Ctx 53 $AnyEvent::Log::COLLECT->attach (new AnyEvent::Log::Ctx
36 level => "critical", 54 level => "critical",
37 log_to_syslog => 0, 55 log_to_syslog => "user",
38 ); 56 );
39 57
40=head1 DESCRIPTION 58=head1 DESCRIPTION
41 59
42This module implements a relatively simple "logging framework". It doesn't 60This module implements a relatively simple "logging framework". It doesn't
43attempt to be "the" logging solution or even "a" logging solution for 61attempt to be "the" logging solution or even "a" logging solution for
44AnyEvent - AnyEvent simply creates logging messages internally, and this 62AnyEvent - AnyEvent simply creates logging messages internally, and this
45module more or less exposes the mechanism, with some extra spiff to allow 63module more or less exposes the mechanism, with some extra spiff to allow
46using it from other modules as well. 64using it from other modules as well.
47 65
48Remember that the default verbosity level is C<0> (C<off>), so nothing 66Remember that the default verbosity level is C<4> (C<error>), so only
49will be logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number 67errors and more important messages will be logged, unless you set
50before starting your program, or change the logging level at runtime with 68C<PERL_ANYEVENT_VERBOSE> to a higher number before starting your program
51something like: 69(C<AE_VERBOSE=5> is recommended during development), or change the logging
70level at runtime with something like:
52 71
53 use AnyEvent::Log; 72 use AnyEvent::Log;
54 AnyEvent::Log::FILTER->level ("info"); 73 $AnyEvent::Log::FILTER->level ("info");
55 74
56The design goal behind this module was to keep it simple (and small), 75The design goal behind this module was to keep it simple (and small),
57but make it powerful enough to be potentially useful for any module, and 76but make it powerful enough to be potentially useful for any module, and
58extensive enough for the most common tasks, such as logging to multiple 77extensive enough for the most common tasks, such as logging to multiple
59targets, or being able to log into a database. 78targets, or being able to log into a database.
60 79
80The module is also usable before AnyEvent itself is initialised, in which
81case some of the functionality might be reduced.
82
61The amount of documentation might indicate otherwise, but the module is 83The amount of documentation might indicate otherwise, but the runtime part
62still just below 300 lines of code. 84of the module is still just below 300 lines of code.
63 85
64=head1 LOGGING LEVELS 86=head1 LOGGING LEVELS
65 87
66Logging levels in this module range from C<1> (highest priority) to C<9> 88Logging levels in this module range from C<1> (highest priority) to C<9>
67(lowest priority). Note that the lowest numerical value is the highest 89(lowest priority). Note that the lowest numerical value is the highest
… …
69numerical value". 91numerical value".
70 92
71Instead of specifying levels by name you can also specify them by aliases: 93Instead of specifying levels by name you can also specify them by aliases:
72 94
73 LVL NAME SYSLOG PERL NOTE 95 LVL NAME SYSLOG PERL NOTE
74 1 fatal emerg exit aborts program! 96 1 fatal emerg exit system unusable, aborts program!
75 2 alert 97 2 alert failure in primary system
76 3 critical crit 98 3 critical crit failure in backup system
77 4 error err die 99 4 error err die non-urgent program errors, a bug
78 5 warn warning 100 5 warn warning possible problem, not necessarily error
79 6 note notice 101 6 note notice unusual conditions
80 7 info 102 7 info normal messages, no action required
81 8 debug 103 8 debug debugging messages for development
82 9 trace 104 9 trace copious tracing output
83 105
84As you can see, some logging levels have multiple aliases - the first one 106As you can see, some logging levels have multiple aliases - the first one
85is the "official" name, the second one the "syslog" name (if it differs) 107is the "official" name, the second one the "syslog" name (if it differs)
86and the third one the "perl" name, suggesting that you log C<die> messages 108and the third one the "perl" name, suggesting (only!) that you log C<die>
87at C<error> priority. 109messages at C<error> priority. The NOTE column tries to provide some
110rationale on how to chose a logging level.
88 111
112As a rough guideline, levels 1..3 are primarily meant for users of the
113program (admins, staff), and are the only ones logged to STDERR by
114default. Levels 4..6 are meant for users and developers alike, while
115levels 7..9 are usually meant for developers.
116
89You can normally only log a single message at highest priority level 117You can normally only log a message once at highest priority level (C<1>,
90(C<1>, C<fatal>), because logging a fatal message will also quit the 118C<fatal>), because logging a fatal message will also quit the program - so
91program - so use it sparingly :) 119use it sparingly :)
120
121For example, a program that finds an unknown switch on the commandline
122might well use a fatal logging level to tell users about it - the "system"
123in this case would be the program, or module.
92 124
93Some methods also offer some extra levels, such as C<0>, C<off>, C<none> 125Some methods also offer some extra levels, such as C<0>, C<off>, C<none>
94or C<all> - these are only valid in the methods they are documented for. 126or C<all> - these are only valid for the methods that documented them.
95 127
96=head1 LOGGING FUNCTIONS 128=head1 LOGGING FUNCTIONS
97 129
98These functions allow you to log messages. They always use the caller's 130The following functions allow you to log messages. They always use the
99package as a "logging context". Also, the main logging function C<log> is 131caller's package as a "logging context". Also, the main logging function,
100callable as C<AnyEvent::log> or C<AE::log> when the C<AnyEvent> module is 132C<log>, is aliased to C<AnyEvent::log> and C<AE::log> when the C<AnyEvent>
101loaded. 133module is loaded.
102 134
103=over 4 135=over 4
104 136
105=cut 137=cut
106 138
107package AnyEvent::Log; 139package AnyEvent::Log;
108 140
109use Carp (); 141use Carp ();
110use POSIX (); 142use POSIX ();
111 143
144# layout of a context
145# 0 1 2 3 4, 5
146# [$title, $level, %$slaves, &$logcb, &$fmtcb, $cap]
147
112use AnyEvent (); BEGIN { AnyEvent::common_sense } 148use AnyEvent (); BEGIN { AnyEvent::common_sense }
113use AnyEvent::Util (); 149#use AnyEvent::Util (); need to load this in a delayed fashion, as it uses AE::log
114 150
115our $VERSION = $AnyEvent::VERSION; 151our $VERSION = $AnyEvent::VERSION;
116 152
117our ($COLLECT, $FILTER, $LOG); 153our ($COLLECT, $FILTER, $LOG);
118 154
… …
148=item AnyEvent::Log::log $level, $msg[, @args] 184=item AnyEvent::Log::log $level, $msg[, @args]
149 185
150Requests logging of the given C<$msg> with the given log level, and 186Requests logging of the given C<$msg> with the given log level, and
151returns true if the message was logged I<somewhere>. 187returns true if the message was logged I<somewhere>.
152 188
153For C<fatal> log levels, the program will abort. 189For loglevel C<fatal>, the program will abort.
154 190
155If only a C<$msg> is given, it is logged as-is. With extra C<@args>, the 191If only a C<$msg> is given, it is logged as-is. With extra C<@args>, the
156C<$msg> is interpreted as an sprintf format string. 192C<$msg> is interpreted as an sprintf format string.
157 193
158The C<$msg> should not end with C<\n>, but may if that is convenient for 194The C<$msg> should not end with C<\n>, but may if that is convenient for
… …
160 196
161Last not least, C<$msg> might be a code reference, in which case it is 197Last not least, C<$msg> might be a code reference, in which case it is
162supposed to return the message. It will be called only then the message 198supposed to return the message. It will be called only then the message
163actually gets logged, which is useful if it is costly to create the 199actually gets logged, which is useful if it is costly to create the
164message in the first place. 200message in the first place.
201
202This function takes care of saving and restoring C<$!> and C<$@>, so you
203don't have to.
165 204
166Whether the given message will be logged depends on the maximum log level 205Whether the given message will be logged depends on the maximum log level
167and the caller's package. The return value can be used to ensure that 206and the caller's package. The return value can be used to ensure that
168messages or not "lost" - for example, when L<AnyEvent::Debug> detects a 207messages or not "lost" - for example, when L<AnyEvent::Debug> detects a
169runtime error it tries to log it at C<die> level, but if that message is 208runtime error it tries to log it at C<die> level, but if that message is
… …
203 info => 7, 242 info => 7,
204 debug => 8, 243 debug => 8,
205 trace => 9, 244 trace => 9,
206); 245);
207 246
208sub now () { time } 247our $TIME_EXACT;
248
249sub exact_time($) {
250 $TIME_EXACT = shift;
251 *_ts = $AnyEvent::MODEL
252 ? $TIME_EXACT ? \&AE::now : \&AE::time
253 : sub () { $TIME_EXACT ? do { require Time::HiRes; Time::HiRes::time () } : time };
254}
255
256BEGIN {
257 exact_time 0;
258}
209 259
210AnyEvent::post_detect { 260AnyEvent::post_detect {
211 *now = \&AE::now; 261 exact_time $TIME_EXACT;
212}; 262};
213 263
214our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace); 264our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace);
215 265
216# time, ctx, level, msg 266# time, ctx, level, msg
… …
226 } 276 }
227 277
228 join "", @res 278 join "", @res
229} 279}
230 280
281sub fatal_exit() {
282 exit 1;
283}
284
231sub _log { 285sub _log {
232 my ($ctx, $level, $format, @args) = @_; 286 my ($ctx, $level, $format, @args) = @_;
233 287
234 $level = $level > 0 && $level <= 9 288 $level = $level > 0 && $level <= 9
235 ? $level+0 289 ? $level+0
236 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught"; 290 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught";
237 291
238 my $mask = 1 << $level; 292 my $mask = 1 << $level;
239 293
240 my ($success, %seen, @ctx, $now, $fmt); 294 my ($success, %seen, @ctx, $now, @fmt);
241 295
242 do 296 do
243 { 297 {
244 # skip if masked 298 # if !ref, then it's a level number
299 if (!ref $ctx) {
300 $level = $ctx;
245 if ($ctx->[1] & $mask && !$seen{$ctx+0}++) { 301 } elsif ($ctx->[1] & $mask and !$seen{$ctx+0}++) {
302 # logging/recursing into this context
303
304 # level cap
305 if ($ctx->[5] > $level) {
306 push @ctx, $level; # restore level when going up in tree
307 $level = $ctx->[5];
308 }
309
310 # log if log cb
246 if ($ctx->[3]) { 311 if ($ctx->[3]) {
247 # logging target found 312 # logging target found
313
314 local ($!, $@);
248 315
249 # now get raw message, unless we have it already 316 # now get raw message, unless we have it already
250 unless ($now) { 317 unless ($now) {
251 $format = $format->() if ref $format; 318 $format = $format->() if ref $format;
252 $format = sprintf $format, @args if @args; 319 $format = sprintf $format, @args if @args;
253 $format =~ s/\n$//; 320 $format =~ s/\n$//;
254 $now = AE::now; 321 $now = _ts;
255 }; 322 };
256 323
257 # format msg 324 # format msg
258 my $str = $ctx->[4] 325 my $str = $ctx->[4]
259 ? $ctx->[4]($now, $_[0], $level, $format) 326 ? $ctx->[4]($now, $_[0], $level, $format)
260 : ($fmt ||= _format $now, $_[0], $level, $format); 327 : ($fmt[$level] ||= _format $now, $_[0], $level, $format);
261 328
262 $success = 1; 329 $success = 1;
263 330
264 $ctx->[3]($str) 331 $ctx->[3]($str)
265 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate 332 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate
… …
268 } 335 }
269 } 336 }
270 } 337 }
271 while $ctx = pop @ctx; 338 while $ctx = pop @ctx;
272 339
273 exit 1 if $level <= 1; 340 fatal_exit if $level <= 1;
274 341
275 $success 342 $success
276} 343}
277 344
278sub log($$;@) { 345sub log($$;@) {
279 _log 346 _log
280 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 347 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
281 @_; 348 @_;
282} 349}
283 350
284*AnyEvent::log = *AE::log = \&log;
285
286=item $logger = AnyEvent::Log::logger $level[, \$enabled] 351=item $logger = AnyEvent::Log::logger $level[, \$enabled]
287 352
288Creates a code reference that, when called, acts as if the 353Creates a code reference that, when called, acts as if the
289C<AnyEvent::Log::log> function was called at this point with the given 354C<AnyEvent::Log::log> function was called at this point with the given
290level. C<$logger> is passed a C<$msg> and optional C<@args>, just as with 355level. C<$logger> is passed a C<$msg> and optional C<@args>, just as with
… …
354 419
355 $LOGGER{$logger+0} = $logger; 420 $LOGGER{$logger+0} = $logger;
356 421
357 _reassess $logger+0; 422 _reassess $logger+0;
358 423
424 require AnyEvent::Util unless $AnyEvent::Util::VERSION;
359 my $guard = AnyEvent::Util::guard { 425 my $guard = AnyEvent::Util::guard (sub {
360 # "clean up" 426 # "clean up"
361 delete $LOGGER{$logger+0}; 427 delete $LOGGER{$logger+0};
362 }; 428 });
363 429
364 sub { 430 sub {
365 $guard if 0; # keep guard alive, but don't cause runtime overhead 431 $guard if 0; # keep guard alive, but don't cause runtime overhead
366 432
367 _log $ctx, $level, @_ 433 _log $ctx, $level, @_
… …
372sub logger($;$) { 438sub logger($;$) {
373 _logger 439 _logger
374 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 440 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
375 @_ 441 @_
376} 442}
443
444=item AnyEvent::Log::exact_time $on
445
446By default, C<AnyEvent::Log> will use C<AE::now>, i.e. the cached
447eventloop time, for the log timestamps. After calling this function with a
448true value it will instead resort to C<AE::time>, i.e. fetch the current
449time on each log message. This only makes a difference for event loops
450that actually cache the time (such as L<EV> or L<AnyEvent::Loop>).
451
452This setting can be changed at any time by calling this function.
453
454Since C<AnyEvent::Log> has to work even before the L<AnyEvent> has been
455initialised, this switch will also decide whether to use C<CORE::time> or
456C<Time::HiRes::time> when logging a message before L<AnyEvent> becomes
457available.
377 458
378=back 459=back
379 460
380=head1 LOGGING CONTEXTS 461=head1 LOGGING CONTEXTS
381 462
… …
501This can be used to implement config-file (re-)loading: before loading a 582This can be used to implement config-file (re-)loading: before loading a
502configuration, reset all contexts. 583configuration, reset all contexts.
503 584
504=cut 585=cut
505 586
587our $ORIG_VERBOSE = $AnyEvent::VERBOSE;
588$AnyEvent::VERBOSE = 9;
589
506sub reset { 590sub reset {
507 # hard to kill complex data structures 591 # hard to kill complex data structures
508 # we "recreate" all package loggers and reset the hierarchy 592 # we "recreate" all package loggers and reset the hierarchy
509 while (my ($k, $v) = each %CTX) { 593 while (my ($k, $v) = each %CTX) {
510 @$v = ($k, (1 << 10) - 1 - 1, { }); 594 @$v = ($k, (1 << 10) - 1 - 1, { });
… …
513 } 597 }
514 598
515 @$_ = ($_->[0], (1 << 10) - 1 - 1) 599 @$_ = ($_->[0], (1 << 10) - 1 - 1)
516 for $LOG, $FILTER, $COLLECT; 600 for $LOG, $FILTER, $COLLECT;
517 601
518 $LOG->slaves; 602 #$LOG->slaves;
519 $LOG->title ('$AnyEvent::Log::LOG'); 603 $LOG->title ('$AnyEvent::Log::LOG');
520 $LOG->log_to_warn; 604 $LOG->log_to_warn;
521 605
522 $FILTER->slaves ($LOG); 606 $FILTER->slaves ($LOG);
523 $FILTER->title ('$AnyEvent::Log::FILTER'); 607 $FILTER->title ('$AnyEvent::Log::FILTER');
524 $FILTER->level ($AnyEvent::VERBOSE); 608 $FILTER->level ($ORIG_VERBOSE);
525 609
526 $COLLECT->slaves ($FILTER); 610 $COLLECT->slaves ($FILTER);
527 $COLLECT->title ('$AnyEvent::Log::COLLECT'); 611 $COLLECT->title ('$AnyEvent::Log::COLLECT');
528 612
529 _reassess; 613 _reassess;
530} 614}
615
616# override AE::log/logger
617*AnyEvent::log = *AE::log = \&log;
618*AnyEvent::logger = *AE::logger = \&logger;
619
620# convert AnyEvent loggers to AnyEvent::Log loggers
621$_->[0] = ctx $_->[0] # convert "pkg" to "ctx"
622 for values %LOGGER;
531 623
532# create the default logger contexts 624# create the default logger contexts
533$LOG = ctx undef; 625$LOG = ctx undef;
534$FILTER = ctx undef; 626$FILTER = ctx undef;
535$COLLECT = ctx undef; 627$COLLECT = ctx undef;
… …
544package AnyEvent::Log::COLLECT; 636package AnyEvent::Log::COLLECT;
545package AE::Log::COLLECT; 637package AE::Log::COLLECT;
546 638
547package AnyEvent::Log::Ctx; 639package AnyEvent::Log::Ctx;
548 640
549# 0 1 2 3 4
550# [$title, $level, %$slaves, &$logcb, &$fmtcb]
551
552=item $ctx = new AnyEvent::Log::Ctx methodname => param... 641=item $ctx = new AnyEvent::Log::Ctx methodname => param...
553 642
554This is a convenience constructor that makes it simpler to construct 643This is a convenience constructor that makes it simpler to construct
555anonymous logging contexts. 644anonymous logging contexts.
556 645
… …
643 732
644=item $ctx->disable ($level[, $level...]) 733=item $ctx->disable ($level[, $level...])
645 734
646Disables logging for the given levels, leaving all others unchanged. 735Disables logging for the given levels, leaving all others unchanged.
647 736
737=item $ctx->cap ($level)
738
739Caps the maximum priority to the given level, for all messages logged
740to, or passing through, this context. That is, while this doesn't affect
741whether a message is logged or passed on, the maximum priority of messages
742will be limited to the specified level - messages with a higher priority
743will be set to the specified priority.
744
745Another way to view this is that C<< ->level >> filters out messages with
746a too low priority, while C<< ->cap >> modifies messages with a too high
747priority.
748
749This is useful when different log targets have different interpretations
750of priority. For example, for a specific command line program, a wrong
751command line switch might well result in a C<fatal> log message, while the
752same message, logged to syslog, is likely I<not> fatal to the system or
753syslog facility as a whole, but more likely a mere C<error>.
754
755This can be modeled by having a stderr logger that logs messages "as-is"
756and a syslog logger that logs messages with a level cap of, say, C<error>,
757or, for truly system-critical components, actually C<critical>.
758
648=cut 759=cut
649 760
650sub _lvl_lst { 761sub _lvl_lst {
651 map { 762 map {
652 $_ > 0 && $_ <= 9 ? $_+0 763 $_ > 0 && $_ <= 9 ? $_+0
653 : $_ eq "all" ? (1 .. 9) 764 : $_ eq "all" ? (1 .. 9)
654 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught" 765 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught"
655 } @_ 766 } @_
656} 767}
657 768
769sub _lvl {
770 $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1]
771}
772
658our $NOP_CB = sub { 0 }; 773our $NOP_CB = sub { 0 };
659 774
660sub levels { 775sub levels {
661 my $ctx = shift; 776 my $ctx = shift;
662 $ctx->[1] = 0; 777 $ctx->[1] = 0;
… …
665 AnyEvent::Log::_reassess; 780 AnyEvent::Log::_reassess;
666} 781}
667 782
668sub level { 783sub level {
669 my $ctx = shift; 784 my $ctx = shift;
670 my $lvl = $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1];
671
672 $ctx->[1] = ((1 << $lvl) - 1) << 1; 785 $ctx->[1] = ((1 << &_lvl) - 1) << 1;
673 AnyEvent::Log::_reassess; 786 AnyEvent::Log::_reassess;
674} 787}
675 788
676sub enable { 789sub enable {
677 my $ctx = shift; 790 my $ctx = shift;
… …
685 $ctx->[1] &= ~(1 << $_) 798 $ctx->[1] &= ~(1 << $_)
686 for &_lvl_lst; 799 for &_lvl_lst;
687 AnyEvent::Log::_reassess; 800 AnyEvent::Log::_reassess;
688} 801}
689 802
803sub cap {
804 my $ctx = shift;
805 $ctx->[5] = &_lvl;
806}
807
690=back 808=back
691 809
692=head3 SLAVE CONTEXTS 810=head3 SLAVE CONTEXTS
693 811
694The following methods attach and detach another logging context to a 812The following methods attach and detach another logging context to a
… …
781 899
782Replaces the formatting callback on the context (C<undef> restores the 900Replaces the formatting callback on the context (C<undef> restores the
783default formatter). 901default formatter).
784 902
785The callback is passed the (possibly fractional) timestamp, the original 903The callback is passed the (possibly fractional) timestamp, the original
786logging context, the (numeric) logging level and the raw message string 904logging context (object, not title), the (numeric) logging level and
787and needs to return a formatted log message. In most cases this will be a 905the raw message string and needs to return a formatted log message. In
788string, but it could just as well be an array reference that just stores 906most cases this will be a string, but it could just as well be an array
789the values. 907reference that just stores the values.
790 908
791If, for some reason, you want to use C<caller> to find out more baout the 909If, 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 910logger then you should walk up the call stack until you are no longer
793inside the C<AnyEvent::Log> package. 911inside the C<AnyEvent::Log> package.
794 912
795Example: format just the raw message, with numeric log level in angle 913Example: format just the raw message, with numeric log level in angle
796brackets. 914brackets.
… …
800 918
801 "<$lvl>$msg\n" 919 "<$lvl>$msg\n"
802 }); 920 });
803 921
804Example: return an array reference with just the log values, and use 922Example: return an array reference with just the log values, and use
805C<PApp::SQL::sql_exec> to store the emssage in a database. 923C<PApp::SQL::sql_exec> to store the message in a database.
806 924
807 $ctx->fmt_cb (sub { \@_ }); 925 $ctx->fmt_cb (sub { \@_ });
808 $ctx->log_cb (sub { 926 $ctx->log_cb (sub {
809 my ($msg) = @_; 927 my ($msg) = @_;
810 928
… …
834 952
835Needless(?) to say, if you do not want to be bitten by some evil person 953Needless(?) 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 954calling C<chdir>, the path should be absolute. Doesn't help with
837C<chroot>, but hey... 955C<chroot>, but hey...
838 956
839=item $ctx->log_to_syslog ([$log_flags]) 957=item $ctx->log_to_syslog ([$facility])
840 958
841Logs all messages via L<Sys::Syslog>, mapping C<trace> to C<debug> and all 959Logs 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 960all 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> 961used 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. 962facility is C<user>.
845 963
846Note that this function also sets a C<fmt_cb> - the logging part requires 964Note that this function also sets a C<fmt_cb> - the logging part requires
847an array reference with [$level, $str] as input. 965an array reference with [$level, $str] as input.
848 966
849=cut 967=cut
… …
892 0 1010 0
893 }); 1011 });
894} 1012}
895 1013
896sub log_to_syslog { 1014sub log_to_syslog {
897 my ($ctx, $flags) = @_; 1015 my ($ctx, $facility) = @_;
898 1016
899 require Sys::Syslog; 1017 require Sys::Syslog;
900 1018
901 $ctx->fmt_cb (sub { 1019 $ctx->fmt_cb (sub {
902 my $str = $_[3]; 1020 my $str = $_[3];
903 $str =~ s/\n(?=.)/\n+ /g; 1021 $str =~ s/\n(?=.)/\n+ /g;
904 1022
905 [$_[2], "($_[1][0]) $str"] 1023 [$_[2], "($_[1][0]) $str"]
906 }); 1024 });
907 1025
1026 $facility ||= "user";
1027
908 $ctx->log_cb (sub { 1028 $ctx->log_cb (sub {
909 my $lvl = $_[0][0] < 9 ? $_[0][0] : 8; 1029 my $lvl = $_[0][0] < 9 ? $_[0][0] : 8;
910 1030
911 Sys::Syslog::syslog ($flags | ($lvl - 1), $_) 1031 Sys::Syslog::syslog ("$facility|" . ($lvl - 1), $_)
912 for split /\n/, $_[0][1]; 1032 for split /\n/, $_[0][1];
913 1033
914 0 1034 0
915 }); 1035 });
916} 1036}
… …
925=over 4 1045=over 4
926 1046
927=item $ctx->log ($level, $msg[, @params]) 1047=item $ctx->log ($level, $msg[, @params])
928 1048
929Same as C<AnyEvent::Log::log>, but uses the given context as log context. 1049Same as C<AnyEvent::Log::log>, but uses the given context as log context.
1050
1051Example: log a message in the context of another package.
1052
1053 (AnyEvent::Log::ctx "Other::Package")->log (warn => "heely bo");
930 1054
931=item $logger = $ctx->logger ($level[, \$enabled]) 1055=item $logger = $ctx->logger ($level[, \$enabled])
932 1056
933Same as C<AnyEvent::Log::logger>, but uses the given context as log 1057Same as C<AnyEvent::Log::logger>, but uses the given context as log
934context. 1058context.
… …
966 # enable debug log messages, log warnings and above to syslog 1090 # enable debug log messages, log warnings and above to syslog
967 filter=debug:log=+%warnings:%warnings=warn,syslog=LOG_LOCAL0 1091 filter=debug:log=+%warnings:%warnings=warn,syslog=LOG_LOCAL0
968 1092
969 # log trace messages (only) from AnyEvent::Debug to file 1093 # log trace messages (only) from AnyEvent::Debug to file
970 AnyEvent::Debug=+%trace:%trace=only,trace,file=/tmp/tracelog 1094 AnyEvent::Debug=+%trace:%trace=only,trace,file=/tmp/tracelog
1095
1096A context name in the log specification can be any of the following:
1097
1098=over 4
1099
1100=item C<collect>, C<filter>, C<log>
1101
1102Correspond to the three predefined C<$AnyEvent::Log::COLLECT>,
1103C<AnyEvent::Log::FILTER> and C<$AnyEvent::Log::LOG> contexts.
1104
1105=item C<%name>
1106
1107Context names starting with a C<%> are anonymous contexts created when the
1108name is first mentioned. The difference to package contexts is that by
1109default they have no attached slaves.
1110
1111=item a perl package name
1112
1113Any other string references the logging context associated with the given
1114Perl C<package>. In the unlikely case where you want to specify a package
1115context that matches on of the other context name forms, you can add a
1116C<::> to the package name to force interpretation as a package.
1117
1118=back
1119
1120The configuration specifications can be any number of the following:
1121
1122=over 4
1123
1124=item C<stderr>
1125
1126Configures the context to use Perl's C<warn> function (which typically
1127logs to C<STDERR>). Works like C<log_to_warn>.
1128
1129=item C<file=>I<path>
1130
1131Configures the context to log to a file with the given path. Works like
1132C<log_to_file>.
1133
1134=item C<path=>I<path>
1135
1136Configures the context to log to a file with the given path. Works like
1137C<log_to_path>.
1138
1139=item C<syslog> or C<syslog=>I<expr>
1140
1141Configures the context to log to syslog. If I<expr> is given, then it is
1142evaluated in the L<Sys::Syslog> package, so you could use:
1143
1144 log=syslog=LOG_LOCAL0
1145
1146=item C<nolog>
1147
1148Configures the context to not log anything by itself, which is the
1149default. Same as C<< $ctx->log_cb (undef) >>.
1150
1151=item C<cap=>I<level>
1152
1153Caps logging messages entering this context at the given level, i.e.
1154reduces the priority of messages with higher priority than this level. The
1155default is C<0> (or C<off>), meaning the priority will not be touched.
1156
1157=item C<0> or C<off>
1158
1159Sets the logging level of the context to C<0>, i.e. all messages will be
1160filtered out.
1161
1162=item C<all>
1163
1164Enables all logging levels, i.e. filtering will effectively be switched
1165off (the default).
1166
1167=item C<only>
1168
1169Disables all logging levels, and changes the interpretation of following
1170level specifications to enable the specified level only.
1171
1172Example: only enable debug messages for a context.
1173
1174 context=only,debug
1175
1176=item C<except>
1177
1178Enables all logging levels, and changes the interpretation of following
1179level specifications to disable that level. Rarely used.
1180
1181Example: enable all logging levels except fatal and trace (this is rather
1182nonsensical).
1183
1184 filter=exept,fatal,trace
1185
1186=item C<level>
1187
1188Enables all logging levels, and changes the interpretation of following
1189level specifications to be "that level or any higher priority
1190message". This is the default.
1191
1192Example: log anything at or above warn level.
1193
1194 filter=warn
1195
1196 # or, more verbose
1197 filter=only,level,warn
1198
1199=item C<1>..C<9> or a logging level name (C<error>, C<debug> etc.)
1200
1201A numeric loglevel or the name of a loglevel will be interpreted according
1202to the most recent C<only>, C<except> or C<level> directive. By default,
1203specifying a logging level enables that and any higher priority messages.
1204
1205=item C<+>I<context>
1206
1207Attaches the named context as slave to the context.
1208
1209=item C<+>
1210
1211A lone C<+> detaches all contexts, i.e. clears the slave list from the
1212context. Anonymous (C<%name>) contexts have no attached slaves by default,
1213but package contexts have the parent context as slave by default.
1214
1215Example: log messages from My::Module to a file, do not send them to the
1216default log collector.
1217
1218 My::Module=+,file=/tmp/mymodulelog
1219
1220=back
1221
1222Any character can be escaped by prefixing it with a C<\> (backslash), as
1223usual, so to log to a file containing a comma, colon, backslash and some
1224spaces in the filename, you would do this:
1225
1226 PERL_ANYEVENT_LOG='log=file=/some\ \:file\ with\,\ \\-escapes'
971 1227
972Since whitespace (which includes newlines) is allowed, it is fine to 1228Since whitespace (which includes newlines) is allowed, it is fine to
973specify multiple lines in C<PERL_ANYEVENT_LOG>, e.g.: 1229specify multiple lines in C<PERL_ANYEVENT_LOG>, e.g.:
974 1230
975 PERL_ANYEVENT_LOG=" 1231 PERL_ANYEVENT_LOG="
976 filter=warn 1232 filter=warn
977 AnyEvent::Debug=+%trace 1233 AnyEvent::Debug=+%trace
978 %trace=only,trace,+log 1234 %trace=only,trace,+log
979 " myprog 1235 " myprog
980 1236
981A context name in the log specification can be any of the following: 1237Also, in the unlikely case when you want to concatenate specifications,
1238use whitespace as separator, as C<::> will be interpreted as part of a
1239module name, an empty spec with two separators:
982 1240
983=over 4 1241 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 1242
1101=cut 1243=cut
1102 1244
1103for (my $spec = $ENV{PERL_ANYEVENT_LOG}) { 1245for (my $spec = $ENV{PERL_ANYEVENT_LOG}) {
1104 my %anon; 1246 my %anon;
1105 1247
1106 my $pkg = sub { 1248 my $pkg = sub {
1107 $_[0] eq "log" ? $LOG 1249 $_[0] eq "log" ? $LOG
1108 : $_[0] eq "filter" ? $FILTER 1250 : $_[0] eq "filter" ? $FILTER
1109 : $_[0] eq "collect" ? $COLLECT 1251 : $_[0] eq "collect" ? $COLLECT
1110 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= ctx undef) 1252 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= do { my $ctx = ctx undef; $ctx->[0] = $_[0]; $ctx })
1111 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/ 1253 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/
1112 : die # never reached? 1254 : die # never reached?
1113 }; 1255 };
1114 1256
1115 /\G[[:space:]]+/gc; # skip initial whitespace 1257 /\G[[:space:]]+/gc; # skip initial whitespace
… …
1121 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) { 1263 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) {
1122 for ("$1") { 1264 for ("$1") {
1123 if ($_ eq "stderr" ) { $ctx->log_to_warn; 1265 if ($_ eq "stderr" ) { $ctx->log_to_warn;
1124 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1"); 1266 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1");
1125 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1"); 1267 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1");
1126 } elsif (/syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog (eval "package Sys::Syslog; $1"); 1268 } elsif (/^syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog ("$1");
1127 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef); 1269 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef);
1270 } elsif (/^cap=(.+)/ ) { $ctx->cap ("$1");
1128 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1")); 1271 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1"));
1129 } elsif ($_ eq "+" ) { $ctx->slaves; 1272 } elsif ($_ eq "+" ) { $ctx->slaves;
1130 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0); 1273 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0);
1131 } elsif ($_ eq "all" ) { $ctx->level ("all"); 1274 } elsif ($_ eq "all" ) { $ctx->level ("all");
1132 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level"; 1275 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level";
… …
1149 if (/\G(.+)/g) { 1292 if (/\G(.+)/g) {
1150 die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n"; 1293 die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n";
1151 } 1294 }
1152} 1295}
1153 1296
11541;
1155
1156=head1 EXAMPLES 1297=head1 EXAMPLES
1157 1298
1158This section shows some common configurations, both as code, and as 1299This section shows some common configurations, both as code, and as
1159C<PERL_ANYEVENT_LOG> string. 1300C<PERL_ANYEVENT_LOG> string.
1160 1301
… …
1184 1325
1185This writes them only when the global logging level allows it, because 1326This writes them only when the global logging level allows it, because
1186it is attached to the default context which is invoked I<after> global 1327it is attached to the default context which is invoked I<after> global
1187filtering. 1328filtering.
1188 1329
1189 $AnyEvent::Log::FILTER->attach 1330 $AnyEvent::Log::FILTER->attach (
1190 new AnyEvent::Log::Ctx log_to_file => $path); 1331 new AnyEvent::Log::Ctx log_to_file => $path);
1191 1332
1192 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path 1333 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
1193 1334
1194This writes them regardless of the global logging level, because it is 1335This writes them regardless of the global logging level, because it is
… …
1200 1341
1201 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger 1342 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
1202 1343
1203In both cases, messages are still written to STDERR. 1344In both cases, messages are still written to STDERR.
1204 1345
1346=item Additionally log all messages with C<warn> and higher priority to
1347C<syslog>, but cap at C<error>.
1348
1349This logs all messages to the default log target, but also logs messages
1350with priority C<warn> or higher (and not filtered otherwise) to syslog
1351facility C<user>. Messages with priority higher than C<error> will be
1352logged with level C<error>.
1353
1354 $AnyEvent::Log::LOG->attach (
1355 new AnyEvent::Log::Ctx
1356 level => "warn",
1357 cap => "error",
1358 syslog => "user",
1359 );
1360
1361 PERL_ANYEVENT_LOG=log=+%syslog:%syslog=warn,cap=error,syslog
1362
1205=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s). 1363=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s).
1206 1364
1207Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug> 1365Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug>
1208context - this simply circumvents the global filtering for trace messages. 1366context - this simply circumvents the global filtering for trace messages.
1209 1367
… …
1223 Marc Lehmann <schmorp@schmorp.de> 1381 Marc Lehmann <schmorp@schmorp.de>
1224 http://home.schmorp.de/ 1382 http://home.schmorp.de/
1225 1383
1226=cut 1384=cut
1227 1385
13861
1387

Diff Legend

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