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.36 by root, Thu Aug 25 05:39:47 2011 UTC vs.
Revision 1.52 by root, Thu Mar 22 19:27:30 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),
… …
72numerical value". 91numerical value".
73 92
74Instead 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:
75 94
76 LVL NAME SYSLOG PERL NOTE 95 LVL NAME SYSLOG PERL NOTE
77 1 fatal emerg exit aborts program! 96 1 fatal emerg exit system unusable, aborts program!
78 2 alert 97 2 alert failure in primary system
79 3 critical crit 98 3 critical crit failure in backup system
80 4 error err die 99 4 error err die non-urgent program errors, a bug
81 5 warn warning 100 5 warn warning possible problem, not necessarily error
82 6 note notice 101 6 note notice unusual conditions
83 7 info 102 7 info normal messages, no action required
84 8 debug 103 8 debug debugging messages for development
85 9 trace 104 9 trace copious tracing output
86 105
87As 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
88is 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)
89and 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>
90at C<error> priority. 109messages at C<error> priority. The NOTE column tries to provide some
110rationale on how to chose a logging level.
91 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
92You 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>,
93(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
94program - 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.
95 124
96Some 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>
97or 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.
98 127
99=head1 LOGGING FUNCTIONS 128=head1 LOGGING FUNCTIONS
100 129
101These functions allow you to log messages. They always use the caller's 130The following functions allow you to log messages. They always use the
102package as a "logging context". Also, the main logging function C<log> is 131caller's package as a "logging context". Also, the main logging function,
103callable 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>
104loaded. 133module is loaded.
105 134
106=over 4 135=over 4
107 136
108=cut 137=cut
109 138
110package AnyEvent::Log; 139package AnyEvent::Log;
111 140
112use Carp (); 141use Carp ();
113use POSIX (); 142use POSIX ();
114 143
144# layout of a context
145# 0 1 2 3 4, 5
146# [$title, $level, %$slaves, &$logcb, &$fmtcb, $cap]
147
115use AnyEvent (); BEGIN { AnyEvent::common_sense } 148use AnyEvent (); BEGIN { AnyEvent::common_sense }
116use AnyEvent::Util (); 149#use AnyEvent::Util (); need to load this in a delayed fashion, as it uses AE::log
117 150
118our $VERSION = $AnyEvent::VERSION; 151our $VERSION = $AnyEvent::VERSION;
119 152
120our ($COLLECT, $FILTER, $LOG); 153our ($COLLECT, $FILTER, $LOG);
121 154
… …
151=item AnyEvent::Log::log $level, $msg[, @args] 184=item AnyEvent::Log::log $level, $msg[, @args]
152 185
153Requests 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
154returns true if the message was logged I<somewhere>. 187returns true if the message was logged I<somewhere>.
155 188
156For C<fatal> log levels, the program will abort. 189For loglevel C<fatal>, the program will abort.
157 190
158If 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
159C<$msg> is interpreted as an sprintf format string. 192C<$msg> is interpreted as an sprintf format string.
160 193
161The 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
… …
163 196
164Last 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
165supposed 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
166actually 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
167message 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.
168 204
169Whether 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
170and 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
171messages or not "lost" - for example, when L<AnyEvent::Debug> detects a 207messages or not "lost" - for example, when L<AnyEvent::Debug> detects a
172runtime 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
… …
206 info => 7, 242 info => 7,
207 debug => 8, 243 debug => 8,
208 trace => 9, 244 trace => 9,
209); 245);
210 246
211sub 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}
212 259
213AnyEvent::post_detect { 260AnyEvent::post_detect {
214 *now = \&AE::now; 261 exact_time $TIME_EXACT;
215}; 262};
216 263
217our @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);
218 265
219# time, ctx, level, msg 266# time, ctx, level, msg
… …
229 } 276 }
230 277
231 join "", @res 278 join "", @res
232} 279}
233 280
281sub fatal_exit() {
282 exit 1;
283}
284
234sub _log { 285sub _log {
235 my ($ctx, $level, $format, @args) = @_; 286 my ($ctx, $level, $format, @args) = @_;
236 287
237 $level = $level > 0 && $level <= 9 288 $level = $level > 0 && $level <= 9
238 ? $level+0 289 ? $level+0
239 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught"; 290 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught";
240 291
241 my $mask = 1 << $level; 292 my $mask = 1 << $level;
242 293
243 my ($success, %seen, @ctx, $now, $fmt); 294 my ($success, %seen, @ctx, $now, @fmt);
244 295
245 do 296 do
246 { 297 {
247 # skip if masked 298 # if !ref, then it's a level number
299 if (!ref $ctx) {
300 $level = $ctx;
248 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
249 if ($ctx->[3]) { 311 if ($ctx->[3]) {
250 # logging target found 312 # logging target found
313
314 local ($!, $@);
251 315
252 # now get raw message, unless we have it already 316 # now get raw message, unless we have it already
253 unless ($now) { 317 unless ($now) {
254 $format = $format->() if ref $format; 318 $format = $format->() if ref $format;
255 $format = sprintf $format, @args if @args; 319 $format = sprintf $format, @args if @args;
256 $format =~ s/\n$//; 320 $format =~ s/\n$//;
257 $now = now; 321 $now = _ts;
258 }; 322 };
259 323
260 # format msg 324 # format msg
261 my $str = $ctx->[4] 325 my $str = $ctx->[4]
262 ? $ctx->[4]($now, $_[0], $level, $format) 326 ? $ctx->[4]($now, $_[0], $level, $format)
263 : ($fmt ||= _format $now, $_[0], $level, $format); 327 : ($fmt[$level] ||= _format $now, $_[0], $level, $format);
264 328
265 $success = 1; 329 $success = 1;
266 330
267 $ctx->[3]($str) 331 $ctx->[3]($str)
268 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate 332 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate
… …
271 } 335 }
272 } 336 }
273 } 337 }
274 while $ctx = pop @ctx; 338 while $ctx = pop @ctx;
275 339
276 exit 1 if $level <= 1; 340 fatal_exit if $level <= 1;
277 341
278 $success 342 $success
279} 343}
280 344
281sub log($$;@) { 345sub log($$;@) {
282 _log 346 _log
283 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 347 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
284 @_; 348 @_;
285} 349}
286 350
287*AnyEvent::log = *AE::log = \&log;
288
289=item $logger = AnyEvent::Log::logger $level[, \$enabled] 351=item $logger = AnyEvent::Log::logger $level[, \$enabled]
290 352
291Creates a code reference that, when called, acts as if the 353Creates a code reference that, when called, acts as if the
292C<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
293level. 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
… …
357 419
358 $LOGGER{$logger+0} = $logger; 420 $LOGGER{$logger+0} = $logger;
359 421
360 _reassess $logger+0; 422 _reassess $logger+0;
361 423
424 require AnyEvent::Util unless $AnyEvent::Util::VERSION;
362 my $guard = AnyEvent::Util::guard { 425 my $guard = AnyEvent::Util::guard (sub {
363 # "clean up" 426 # "clean up"
364 delete $LOGGER{$logger+0}; 427 delete $LOGGER{$logger+0};
365 }; 428 });
366 429
367 sub { 430 sub {
368 $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
369 432
370 _log $ctx, $level, @_ 433 _log $ctx, $level, @_
… …
375sub logger($;$) { 438sub logger($;$) {
376 _logger 439 _logger
377 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 440 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
378 @_ 441 @_
379} 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.
380 458
381=back 459=back
382 460
383=head1 LOGGING CONTEXTS 461=head1 LOGGING CONTEXTS
384 462
… …
504This 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
505configuration, reset all contexts. 583configuration, reset all contexts.
506 584
507=cut 585=cut
508 586
587our $ORIG_VERBOSE = $AnyEvent::VERBOSE;
588$AnyEvent::VERBOSE = 9;
589
509sub reset { 590sub reset {
510 # hard to kill complex data structures 591 # hard to kill complex data structures
511 # we "recreate" all package loggers and reset the hierarchy 592 # we "recreate" all package loggers and reset the hierarchy
512 while (my ($k, $v) = each %CTX) { 593 while (my ($k, $v) = each %CTX) {
513 @$v = ($k, (1 << 10) - 1 - 1, { }); 594 @$v = ($k, (1 << 10) - 1 - 1, { });
… …
522 $LOG->title ('$AnyEvent::Log::LOG'); 603 $LOG->title ('$AnyEvent::Log::LOG');
523 $LOG->log_to_warn; 604 $LOG->log_to_warn;
524 605
525 $FILTER->slaves ($LOG); 606 $FILTER->slaves ($LOG);
526 $FILTER->title ('$AnyEvent::Log::FILTER'); 607 $FILTER->title ('$AnyEvent::Log::FILTER');
527 $FILTER->level ($AnyEvent::VERBOSE); 608 $FILTER->level ($ORIG_VERBOSE);
528 609
529 $COLLECT->slaves ($FILTER); 610 $COLLECT->slaves ($FILTER);
530 $COLLECT->title ('$AnyEvent::Log::COLLECT'); 611 $COLLECT->title ('$AnyEvent::Log::COLLECT');
531 612
532 _reassess; 613 _reassess;
533} 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;
534 623
535# create the default logger contexts 624# create the default logger contexts
536$LOG = ctx undef; 625$LOG = ctx undef;
537$FILTER = ctx undef; 626$FILTER = ctx undef;
538$COLLECT = ctx undef; 627$COLLECT = ctx undef;
… …
547package AnyEvent::Log::COLLECT; 636package AnyEvent::Log::COLLECT;
548package AE::Log::COLLECT; 637package AE::Log::COLLECT;
549 638
550package AnyEvent::Log::Ctx; 639package AnyEvent::Log::Ctx;
551 640
552# 0 1 2 3 4
553# [$title, $level, %$slaves, &$logcb, &$fmtcb]
554
555=item $ctx = new AnyEvent::Log::Ctx methodname => param... 641=item $ctx = new AnyEvent::Log::Ctx methodname => param...
556 642
557This is a convenience constructor that makes it simpler to construct 643This is a convenience constructor that makes it simpler to construct
558anonymous logging contexts. 644anonymous logging contexts.
559 645
… …
646 732
647=item $ctx->disable ($level[, $level...]) 733=item $ctx->disable ($level[, $level...])
648 734
649Disables logging for the given levels, leaving all others unchanged. 735Disables logging for the given levels, leaving all others unchanged.
650 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
651=cut 759=cut
652 760
653sub _lvl_lst { 761sub _lvl_lst {
654 map { 762 map {
655 $_ > 0 && $_ <= 9 ? $_+0 763 $_ > 0 && $_ <= 9 ? $_+0
656 : $_ eq "all" ? (1 .. 9) 764 : $_ eq "all" ? (1 .. 9)
657 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught" 765 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught"
658 } @_ 766 } @_
659} 767}
660 768
769sub _lvl {
770 $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1]
771}
772
661our $NOP_CB = sub { 0 }; 773our $NOP_CB = sub { 0 };
662 774
663sub levels { 775sub levels {
664 my $ctx = shift; 776 my $ctx = shift;
665 $ctx->[1] = 0; 777 $ctx->[1] = 0;
… …
668 AnyEvent::Log::_reassess; 780 AnyEvent::Log::_reassess;
669} 781}
670 782
671sub level { 783sub level {
672 my $ctx = shift; 784 my $ctx = shift;
673 my $lvl = $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1];
674
675 $ctx->[1] = ((1 << $lvl) - 1) << 1; 785 $ctx->[1] = ((1 << &_lvl) - 1) << 1;
676 AnyEvent::Log::_reassess; 786 AnyEvent::Log::_reassess;
677} 787}
678 788
679sub enable { 789sub enable {
680 my $ctx = shift; 790 my $ctx = shift;
… …
688 $ctx->[1] &= ~(1 << $_) 798 $ctx->[1] &= ~(1 << $_)
689 for &_lvl_lst; 799 for &_lvl_lst;
690 AnyEvent::Log::_reassess; 800 AnyEvent::Log::_reassess;
691} 801}
692 802
803sub cap {
804 my $ctx = shift;
805 $ctx->[5] = &_lvl;
806}
807
693=back 808=back
694 809
695=head3 SLAVE CONTEXTS 810=head3 SLAVE CONTEXTS
696 811
697The following methods attach and detach another logging context to a 812The following methods attach and detach another logging context to a
… …
784 899
785Replaces the formatting callback on the context (C<undef> restores the 900Replaces the formatting callback on the context (C<undef> restores the
786default formatter). 901default formatter).
787 902
788The callback is passed the (possibly fractional) timestamp, the original 903The callback is passed the (possibly fractional) timestamp, the original
789logging context, the (numeric) logging level and the raw message string 904logging context (object, not title), the (numeric) logging level and
790and 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
791string, 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
792the values. 907reference that just stores the values.
793 908
794If, 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
795logger 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
796inside the C<AnyEvent::Log> package. 911inside the C<AnyEvent::Log> package.
797 912
798Example: format just the raw message, with numeric log level in angle 913Example: format just the raw message, with numeric log level in angle
799brackets. 914brackets.
… …
803 918
804 "<$lvl>$msg\n" 919 "<$lvl>$msg\n"
805 }); 920 });
806 921
807Example: return an array reference with just the log values, and use 922Example: return an array reference with just the log values, and use
808C<PApp::SQL::sql_exec> to store the emssage in a database. 923C<PApp::SQL::sql_exec> to store the message in a database.
809 924
810 $ctx->fmt_cb (sub { \@_ }); 925 $ctx->fmt_cb (sub { \@_ });
811 $ctx->log_cb (sub { 926 $ctx->log_cb (sub {
812 my ($msg) = @_; 927 my ($msg) = @_;
813 928
… …
837 952
838Needless(?) 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
839calling C<chdir>, the path should be absolute. Doesn't help with 954calling C<chdir>, the path should be absolute. Doesn't help with
840C<chroot>, but hey... 955C<chroot>, but hey...
841 956
842=item $ctx->log_to_syslog ([$log_flags]) 957=item $ctx->log_to_syslog ([$facility])
843 958
844Logs 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
845the 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
846simply 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
847flags valid for Sys::Syslog::syslog, except for the priority levels. 962facility is C<user>.
848 963
849Note 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
850an array reference with [$level, $str] as input. 965an array reference with [$level, $str] as input.
851 966
852=cut 967=cut
… …
895 0 1010 0
896 }); 1011 });
897} 1012}
898 1013
899sub log_to_syslog { 1014sub log_to_syslog {
900 my ($ctx, $flags) = @_; 1015 my ($ctx, $facility) = @_;
901 1016
902 require Sys::Syslog; 1017 require Sys::Syslog;
903 1018
904 $ctx->fmt_cb (sub { 1019 $ctx->fmt_cb (sub {
905 my $str = $_[3]; 1020 my $str = $_[3];
906 $str =~ s/\n(?=.)/\n+ /g; 1021 $str =~ s/\n(?=.)/\n+ /g;
907 1022
908 [$_[2], "($_[1][0]) $str"] 1023 [$_[2], "($_[1][0]) $str"]
909 }); 1024 });
910 1025
1026 $facility ||= "user";
1027
911 $ctx->log_cb (sub { 1028 $ctx->log_cb (sub {
912 my $lvl = $_[0][0] < 9 ? $_[0][0] : 8; 1029 my $lvl = $_[0][0] < 9 ? $_[0][0] : 8;
913 1030
914 Sys::Syslog::syslog ($flags | ($lvl - 1), $_) 1031 Sys::Syslog::syslog ("$facility|" . ($lvl - 1), $_)
915 for split /\n/, $_[0][1]; 1032 for split /\n/, $_[0][1];
916 1033
917 0 1034 0
918 }); 1035 });
919} 1036}
… …
928=over 4 1045=over 4
929 1046
930=item $ctx->log ($level, $msg[, @params]) 1047=item $ctx->log ($level, $msg[, @params])
931 1048
932Same 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");
933 1054
934=item $logger = $ctx->logger ($level[, \$enabled]) 1055=item $logger = $ctx->logger ($level[, \$enabled])
935 1056
936Same 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
937context. 1058context.
… …
1025=item C<nolog> 1146=item C<nolog>
1026 1147
1027Configures the context to not log anything by itself, which is the 1148Configures the context to not log anything by itself, which is the
1028default. Same as C<< $ctx->log_cb (undef) >>. 1149default. Same as C<< $ctx->log_cb (undef) >>.
1029 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
1030=item C<0> or C<off> 1157=item C<0> or C<off>
1031 1158
1032Sets the logging level of the context ot C<0>, i.e. all messages will be 1159Sets the logging level of the context to C<0>, i.e. all messages will be
1033filtered out. 1160filtered out.
1034 1161
1035=item C<all> 1162=item C<all>
1036 1163
1037Enables all logging levels, i.e. filtering will effectively be switched 1164Enables all logging levels, i.e. filtering will effectively be switched
… …
1079 1206
1080Attaches the named context as slave to the context. 1207Attaches the named context as slave to the context.
1081 1208
1082=item C<+> 1209=item C<+>
1083 1210
1084A line C<+> detaches all contexts, i.e. clears the slave list from the 1211A lone C<+> detaches all contexts, i.e. clears the slave list from the
1085context. Anonymous (C<%name>) contexts have no attached slaves by default, 1212context. Anonymous (C<%name>) contexts have no attached slaves by default,
1086but package contexts have the parent context as slave by default. 1213but package contexts have the parent context as slave by default.
1087 1214
1088Example: log messages from My::Module to a file, do not send them to the 1215Example: log messages from My::Module to a file, do not send them to the
1089default log collector. 1216default log collector.
… …
1120 1247
1121 my $pkg = sub { 1248 my $pkg = sub {
1122 $_[0] eq "log" ? $LOG 1249 $_[0] eq "log" ? $LOG
1123 : $_[0] eq "filter" ? $FILTER 1250 : $_[0] eq "filter" ? $FILTER
1124 : $_[0] eq "collect" ? $COLLECT 1251 : $_[0] eq "collect" ? $COLLECT
1125 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= ctx undef) 1252 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= do { my $ctx = ctx undef; $ctx->[0] = $_[0]; $ctx })
1126 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/ 1253 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/
1127 : die # never reached? 1254 : die # never reached?
1128 }; 1255 };
1129 1256
1130 /\G[[:space:]]+/gc; # skip initial whitespace 1257 /\G[[:space:]]+/gc; # skip initial whitespace
… …
1136 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) { 1263 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) {
1137 for ("$1") { 1264 for ("$1") {
1138 if ($_ eq "stderr" ) { $ctx->log_to_warn; 1265 if ($_ eq "stderr" ) { $ctx->log_to_warn;
1139 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1"); 1266 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1");
1140 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1"); 1267 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1");
1141 } 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");
1142 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef); 1269 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef);
1270 } elsif (/^cap=(.+)/ ) { $ctx->cap ("$1");
1143 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1")); 1271 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1"));
1144 } elsif ($_ eq "+" ) { $ctx->slaves; 1272 } elsif ($_ eq "+" ) { $ctx->slaves;
1145 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0); 1273 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0);
1146 } elsif ($_ eq "all" ) { $ctx->level ("all"); 1274 } elsif ($_ eq "all" ) { $ctx->level ("all");
1147 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level"; 1275 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level";
… …
1199 1327
1200This writes them only when the global logging level allows it, because 1328This writes them only when the global logging level allows it, because
1201it is attached to the default context which is invoked I<after> global 1329it is attached to the default context which is invoked I<after> global
1202filtering. 1330filtering.
1203 1331
1204 $AnyEvent::Log::FILTER->attach 1332 $AnyEvent::Log::FILTER->attach (
1205 new AnyEvent::Log::Ctx log_to_file => $path); 1333 new AnyEvent::Log::Ctx log_to_file => $path);
1206 1334
1207 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path 1335 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
1208 1336
1209This writes them regardless of the global logging level, because it is 1337This writes them regardless of the global logging level, because it is
… …
1215 1343
1216 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger 1344 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
1217 1345
1218In both cases, messages are still written to STDERR. 1346In both cases, messages are still written to STDERR.
1219 1347
1348=item Additionally log all messages with C<warn> and higher priority to
1349C<syslog>, but cap at C<error>.
1350
1351This logs all messages to the default log target, but also logs messages
1352with priority C<warn> or higher (and not filtered otherwise) to syslog
1353facility C<user>. Messages with priority higher than C<error> will be
1354logged with level C<error>.
1355
1356 $AnyEvent::Log::LOG->attach (
1357 new AnyEvent::Log::Ctx
1358 level => "warn",
1359 cap => "error",
1360 syslog => "user",
1361 );
1362
1363 PERL_ANYEVENT_LOG=log=+%syslog:%syslog=warn,cap=error,syslog
1364
1220=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s). 1365=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s).
1221 1366
1222Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug> 1367Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug>
1223context - this simply circumvents the global filtering for trace messages. 1368context - this simply circumvents the global filtering for trace messages.
1224 1369

Diff Legend

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