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.41 by root, Thu Sep 1 04:07:18 2011 UTC vs.
Revision 1.72 by root, Wed Feb 9 00:28:21 2022 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 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 => "Attempted 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
16 # available log levels in order: 21Log level overview:
17 # fatal alert critical error warn note info debug trace
18 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
19"Complex" uses (for speed sensitive code): 34"Complex" uses (for speed sensitive code, e.g. trace/debug messages):
20 35
21 use AnyEvent::Log; 36 use AnyEvent::Log;
22 37
23 my $tracer = AnyEvent::Log::logger trace => \$my $trace; 38 my $tracer = AnyEvent::Log::logger trace => \my $trace;
24 39
25 $tracer->("i am here") if $trace; 40 $tracer->("i am here") if $trace;
26 $tracer->(sub { "lots of data: " . Dumper $self }) if $trace; 41 $tracer->(sub { "lots of data: " . Dumper $self }) if $trace;
27 42
28Configuration (also look at the EXAMPLES section): 43Configuration (also look at the EXAMPLES section):
29 44
45 # set default logging level to suppress anything below "notice"
46 # i.e. enable logging at "notice" or above - the default is to
47 # to not log anything at all.
48 $AnyEvent::Log::FILTER->level ("notice");
49
30 # set logging for the current package to errors and higher only 50 # set logging for the current package to errors and higher only
31 AnyEvent::Log::ctx->level ("error"); 51 AnyEvent::Log::ctx->level ("error");
32 52
33 # set logging level to suppress anything below "notice" 53 # enable logging for the current package, regardless of global logging level
34 $AnyEvent::Log::FILTER->level ("notice"); 54 AnyEvent::Log::ctx->attach ($AnyEvent::Log::LOG);
55
56 # enable debug logging for module some::mod and enable logging by default
57 (AnyEvent::Log::ctx "some::mod")->level ("debug");
58 (AnyEvent::Log::ctx "some::mod")->attach ($AnyEvent::Log::LOG);
35 59
36 # send all critical and higher priority messages to syslog, 60 # send all critical and higher priority messages to syslog,
37 # regardless of (most) other settings 61 # regardless of (most) other settings
38 $AnyEvent::Log::COLLECT->attach (new AnyEvent::Log::Ctx 62 $AnyEvent::Log::COLLECT->attach (new AnyEvent::Log::Ctx
39 level => "critical", 63 level => "critical",
… …
46attempt to be "the" logging solution or even "a" logging solution for 70attempt to be "the" logging solution or even "a" logging solution for
47AnyEvent - AnyEvent simply creates logging messages internally, and this 71AnyEvent - AnyEvent simply creates logging messages internally, and this
48module more or less exposes the mechanism, with some extra spiff to allow 72module more or less exposes the mechanism, with some extra spiff to allow
49using it from other modules as well. 73using it from other modules as well.
50 74
51Remember that the default verbosity level is C<0> (C<off>), so nothing 75Remember that the default verbosity level is C<4> (C<error>), so only
52will be logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number 76errors and more important messages will be logged, unless you set
53before starting your program, or change the logging level at runtime with 77C<PERL_ANYEVENT_VERBOSE> to a higher number before starting your program
54something like: 78(C<AE_VERBOSE=5> is recommended during development), or change the logging
79level at runtime with something like:
55 80
56 use AnyEvent::Log; 81 use AnyEvent::Log;
57 $AnyEvent::Log::FILTER->level ("info"); 82 $AnyEvent::Log::FILTER->level ("info");
58 83
59The design goal behind this module was to keep it simple (and small), 84The design goal behind this module was to keep it simple (and small),
60but make it powerful enough to be potentially useful for any module, and 85but make it powerful enough to be potentially useful for any module,
61extensive enough for the most common tasks, such as logging to multiple 86and extensive enough for the most common tasks, such as logging to
62targets, or being able to log into a database. 87multiple targets, or being able to log into a database.
63 88
64The module is also usable before AnyEvent itself is initialised, in which 89The module is also usable before AnyEvent itself is initialised, in which
65case some of the functionality might be reduced. 90case some of the functionality might be reduced.
66 91
67The amount of documentation might indicate otherwise, but the runtime part 92The amount of documentation might indicate otherwise, but the runtime part
… …
75numerical value". 100numerical value".
76 101
77Instead of specifying levels by name you can also specify them by aliases: 102Instead of specifying levels by name you can also specify them by aliases:
78 103
79 LVL NAME SYSLOG PERL NOTE 104 LVL NAME SYSLOG PERL NOTE
80 1 fatal emerg exit aborts program! 105 1 fatal emerg exit system unusable, aborts program!
81 2 alert 106 2 alert failure in primary system
82 3 critical crit 107 3 critical crit failure in backup system
83 4 error err die 108 4 error err die non-urgent program errors, a bug
84 5 warn warning 109 5 warn warning possible problem, not necessarily error
85 6 note notice 110 6 note notice unusual conditions
86 7 info 111 7 info normal messages, no action required
87 8 debug 112 8 debug debugging messages for development
88 9 trace 113 9 trace copious tracing output
89 114
90As you can see, some logging levels have multiple aliases - the first one 115As you can see, some logging levels have multiple aliases - the first one
91is the "official" name, the second one the "syslog" name (if it differs) 116is the "official" name, the second one the "syslog" name (if it differs)
92and the third one the "perl" name, suggesting (only!) that you log C<die> 117and the third one the "perl" name, suggesting (only!) that you log C<die>
93messages at C<error> priority. 118messages at C<error> priority. The NOTE column tries to provide some
119rationale on how to chose a logging level.
94 120
121As a rough guideline, levels 1..3 are primarily meant for users of the
122program (admins, staff), and are the only ones logged to STDERR by
123default. Levels 4..6 are meant for users and developers alike, while
124levels 7..9 are usually meant for developers.
125
95You can normally only log a single message at highest priority level 126You can normally only log a message once at highest priority level (C<1>,
96(C<1>, C<fatal>), because logging a fatal message will also quit the 127C<fatal>), because logging a fatal message will also quit the program - so
97program - so use it sparingly :) 128use it sparingly :)
129
130For example, a program that finds an unknown switch on the commandline
131might well use a fatal logging level to tell users about it - the "system"
132in this case would be the program, or module.
98 133
99Some methods also offer some extra levels, such as C<0>, C<off>, C<none> 134Some methods also offer some extra levels, such as C<0>, C<off>, C<none>
100or C<all> - these are only valid in the methods they are documented for. 135or C<all> - these are only valid for the methods that document them.
101 136
102=head1 LOGGING FUNCTIONS 137=head1 LOGGING FUNCTIONS
103 138
104These functions allow you to log messages. They always use the caller's 139The following functions allow you to log messages. They always use the
105package as a "logging context". Also, the main logging function C<log> is 140caller's package as a "logging context". Also, the main logging function,
106callable as C<AnyEvent::log> or C<AE::log> when the C<AnyEvent> module is 141C<log>, is aliased to C<AnyEvent::log> and C<AE::log> when the C<AnyEvent>
107loaded. 142module is loaded.
108 143
109=over 4 144=over 4
110 145
111=cut 146=cut
112 147
113package AnyEvent::Log; 148package AnyEvent::Log;
114 149
115use Carp (); 150use Carp ();
116use POSIX (); 151use POSIX ();
117 152
153# layout of a context
154# 0 1 2 3 4, 5
155# [$title, $level, %$slaves, &$logcb, &$fmtcb, $cap]
156
118use AnyEvent (); BEGIN { AnyEvent::common_sense } 157use AnyEvent (); BEGIN { AnyEvent::common_sense }
119#use AnyEvent::Util (); need to load this in a delayed fashion, as it uses AE::log 158#use AnyEvent::Util (); need to load this in a delayed fashion, as it uses AE::log
120 159
121our $VERSION = $AnyEvent::VERSION; 160our $VERSION = $AnyEvent::VERSION;
122 161
123our ($COLLECT, $FILTER, $LOG); 162our ($COLLECT, $FILTER, $LOG);
124 163
125our ($now_int, $now_str1, $now_str2); 164our ($now_int, $now_str1, $now_str2);
126 165
127# Format Time, not public - yet? 166# Format Time, not public - yet?
128sub ft($) { 167sub format_time($) {
129 my $i = int $_[0]; 168 my $i = int $_[0];
130 my $f = sprintf "%06d", 1e6 * ($_[0] - $i); 169 my $f = sprintf "%06d", 1e6 * ($_[0] - $i);
131 170
132 ($now_int, $now_str1, $now_str2) = ($i, split /\x01/, POSIX::strftime "%Y-%m-%d %H:%M:%S.\x01 %z", localtime $i) 171 ($now_int, $now_str1, $now_str2) = ($i, split /\x01/, POSIX::strftime "%Y-%m-%d %H:%M:%S.\x01 %z", localtime $i)
133 if $now_int != $i; 172 if $now_int != $i;
… …
166 205
167Last not least, C<$msg> might be a code reference, in which case it is 206Last not least, C<$msg> might be a code reference, in which case it is
168supposed to return the message. It will be called only then the message 207supposed to return the message. It will be called only then the message
169actually gets logged, which is useful if it is costly to create the 208actually gets logged, which is useful if it is costly to create the
170message in the first place. 209message in the first place.
210
211This function takes care of saving and restoring C<$!> and C<$@>, so you
212don't have to.
171 213
172Whether the given message will be logged depends on the maximum log level 214Whether the given message will be logged depends on the maximum log level
173and the caller's package. The return value can be used to ensure that 215and the caller's package. The return value can be used to ensure that
174messages or not "lost" - for example, when L<AnyEvent::Debug> detects a 216messages or not "lost" - for example, when L<AnyEvent::Debug> detects a
175runtime error it tries to log it at C<die> level, but if that message is 217runtime error it tries to log it at C<die> level, but if that message is
… …
229}; 271};
230 272
231our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace); 273our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace);
232 274
233# time, ctx, level, msg 275# time, ctx, level, msg
234sub _format($$$$) { 276sub default_format($$$$) {
235 my $ts = ft $_[0]; 277 my $ts = format_time $_[0];
236 my $ct = " "; 278 my $ct = " ";
237 279
238 my @res; 280 my @res;
239 281
240 for (split /\n/, sprintf "%-5s %s: %s", $LEVEL2STR[$_[2]], $_[1][0], $_[3]) { 282 for (split /\n/, sprintf "%-5s %s: %s", $LEVEL2STR[$_[2]], $_[1][0], $_[3]) {
… …
243 } 285 }
244 286
245 join "", @res 287 join "", @res
246} 288}
247 289
290sub fatal_exit() {
291 exit 1;
292}
293
248sub _log { 294sub _log {
249 my ($ctx, $level, $format, @args) = @_; 295 my ($ctx, $level, $format, @args) = @_;
250 296
251 $level = $level > 0 && $level <= 9 297 $level = $level > 0 && $level <= 9
252 ? $level+0 298 ? $level+0
253 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught"; 299 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught";
254 300
255 my $mask = 1 << $level; 301 my $mask = 1 << $level;
256 302
257 my ($success, %seen, @ctx, $now, $fmt); 303 my ($success, %seen, @ctx, $now, @fmt);
258 304
259 do 305 do
260 { 306 {
261 # skip if masked 307 # if !ref, then it's a level number
308 if (!ref $ctx) {
309 $level = $ctx;
262 if ($ctx->[1] & $mask && !$seen{$ctx+0}++) { 310 } elsif ($ctx->[1] & $mask and !$seen{$ctx+0}++) {
311 # logging/recursing into this context
312
313 # level cap
314 if ($ctx->[5] > $level) {
315 push @ctx, $level; # restore level when going up in tree
316 $level = $ctx->[5];
317 }
318
319 # log if log cb
263 if ($ctx->[3]) { 320 if ($ctx->[3]) {
264 # logging target found 321 # logging target found
322
323 local ($!, $@);
265 324
266 # now get raw message, unless we have it already 325 # now get raw message, unless we have it already
267 unless ($now) { 326 unless ($now) {
268 $format = $format->() if ref $format; 327 $format = $format->() if ref $format;
269 $format = sprintf $format, @args if @args; 328 $format = sprintf $format, @args if @args;
… …
272 }; 331 };
273 332
274 # format msg 333 # format msg
275 my $str = $ctx->[4] 334 my $str = $ctx->[4]
276 ? $ctx->[4]($now, $_[0], $level, $format) 335 ? $ctx->[4]($now, $_[0], $level, $format)
277 : ($fmt ||= _format $now, $_[0], $level, $format); 336 : ($fmt[$level] ||= default_format $now, $_[0], $level, $format);
278 337
279 $success = 1; 338 $success = 1;
280 339
281 $ctx->[3]($str) 340 $ctx->[3]($str)
282 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate 341 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate
… …
285 } 344 }
286 } 345 }
287 } 346 }
288 while $ctx = pop @ctx; 347 while $ctx = pop @ctx;
289 348
290 exit 1 if $level <= 1; 349 fatal_exit if $level <= 1;
291 350
292 $success 351 $success
293} 352}
294 353
295sub log($$;@) { 354sub log($$;@) {
296 _log 355 _log
297 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 356 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
298 @_; 357 @_;
299} 358}
300 359
301*AnyEvent::log = *AE::log = \&log;
302
303=item $logger = AnyEvent::Log::logger $level[, \$enabled] 360=item $logger = AnyEvent::Log::logger $level[, \$enabled]
304 361
305Creates a code reference that, when called, acts as if the 362Creates a code reference that, when called, acts as if the
306C<AnyEvent::Log::log> function was called at this point with the given 363C<AnyEvent::Log::log> function was called at this point with the given
307level. C<$logger> is passed a C<$msg> and optional C<@args>, just as with 364level. C<$logger> is passed a C<$msg> and optional C<@args>, just as with
… …
371 428
372 $LOGGER{$logger+0} = $logger; 429 $LOGGER{$logger+0} = $logger;
373 430
374 _reassess $logger+0; 431 _reassess $logger+0;
375 432
376 require AnyEvent::Util; 433 require AnyEvent::Util unless $AnyEvent::Util::VERSION;
377 my $guard = AnyEvent::Util::guard (sub { 434 my $guard = AnyEvent::Util::guard (sub {
378 # "clean up" 435 # "clean up"
379 delete $LOGGER{$logger+0}; 436 delete $LOGGER{$logger+0};
380 }); 437 });
381 438
… …
401time on each log message. This only makes a difference for event loops 458time on each log message. This only makes a difference for event loops
402that actually cache the time (such as L<EV> or L<AnyEvent::Loop>). 459that actually cache the time (such as L<EV> or L<AnyEvent::Loop>).
403 460
404This setting can be changed at any time by calling this function. 461This setting can be changed at any time by calling this function.
405 462
406Since C<AnyEvent::Log> has to work even before the L<AnyEvent> has been 463Since C<AnyEvent::Log> has to work even before L<AnyEvent> has been
407initialised, this switch will also decide whether to use C<CORE::time> or 464initialised, this switch will also decide whether to use C<CORE::time> or
408C<Time::HiRes::time> when logging a message before L<AnyEvent> becomes 465C<Time::HiRes::time> when logging a message before L<AnyEvent> becomes
409available. 466available.
467
468=item AnyEvent::Log::format_time $timestamp
469
470Formats a timestamp as returned by C<< AnyEvent->now >> or C<<
471AnyEvent->time >> or many other functions in the same way as
472C<AnyEvent::Log> does.
473
474In your main program (as opposed to in your module) you can override
475the default timestamp display format by loading this module and then
476redefining this function.
477
478Most commonly, this function can be used in formatting callbacks.
479
480=item AnyEvent::Log::default_format $time, $ctx, $level, $msg
481
482Format a log message using the given timestamp, logging context, log level
483and log message.
484
485This is the formatting function used to format messages when no custom
486function is provided.
487
488In your main program (as opposed to in your module) you can override the
489default message format by loading this module and then redefining this
490function.
491
492=item AnyEvent::Log::fatal_exit()
493
494This is the function that is called after logging a C<fatal> log
495message. It must not return.
496
497The default implementation simply calls C<exit 1>.
498
499In your main program (as opposed to in your module) you can override
500the fatal exit function by loading this module and then redefining this
501function. Make sure you don't return.
410 502
411=back 503=back
412 504
413=head1 LOGGING CONTEXTS 505=head1 LOGGING CONTEXTS
414 506
… …
502 594
503=item $ctx = AnyEvent::Log::ctx [$pkg] 595=item $ctx = AnyEvent::Log::ctx [$pkg]
504 596
505This function creates or returns a logging context (which is an object). 597This function creates or returns a logging context (which is an object).
506 598
507If a package name is given, then the context for that packlage is 599If a package name is given, then the context for that package is
508returned. If it is called without any arguments, then the context for the 600returned. If it is called without any arguments, then the context for the
509callers package is returned (i.e. the same context as a C<AE::log> call 601callers package is returned (i.e. the same context as a C<AE::log> call
510would use). 602would use).
511 603
512If C<undef> is given, then it creates a new anonymous context that is not 604If C<undef> is given, then it creates a new anonymous context that is not
… …
534This can be used to implement config-file (re-)loading: before loading a 626This can be used to implement config-file (re-)loading: before loading a
535configuration, reset all contexts. 627configuration, reset all contexts.
536 628
537=cut 629=cut
538 630
631our $ORIG_VERBOSE = $AnyEvent::VERBOSE;
632$AnyEvent::VERBOSE = 9;
633
539sub reset { 634sub reset {
540 # hard to kill complex data structures 635 # hard to kill complex data structures
541 # we "recreate" all package loggers and reset the hierarchy 636 # we "recreate" all package loggers and reset the hierarchy
542 while (my ($k, $v) = each %CTX) { 637 while (my ($k, $v) = each %CTX) {
543 @$v = ($k, (1 << 10) - 1 - 1, { }); 638 @$v = ($k, (1 << 10) - 1 - 1, { });
… …
552 $LOG->title ('$AnyEvent::Log::LOG'); 647 $LOG->title ('$AnyEvent::Log::LOG');
553 $LOG->log_to_warn; 648 $LOG->log_to_warn;
554 649
555 $FILTER->slaves ($LOG); 650 $FILTER->slaves ($LOG);
556 $FILTER->title ('$AnyEvent::Log::FILTER'); 651 $FILTER->title ('$AnyEvent::Log::FILTER');
557 $FILTER->level ($AnyEvent::VERBOSE); 652 $FILTER->level ($ORIG_VERBOSE);
558 653
559 $COLLECT->slaves ($FILTER); 654 $COLLECT->slaves ($FILTER);
560 $COLLECT->title ('$AnyEvent::Log::COLLECT'); 655 $COLLECT->title ('$AnyEvent::Log::COLLECT');
561 656
562 _reassess; 657 _reassess;
563} 658}
659
660# override AE::log/logger
661*AnyEvent::log = *AE::log = \&log;
662*AnyEvent::logger = *AE::logger = \&logger;
663
664# convert AnyEvent loggers to AnyEvent::Log loggers
665$_->[0] = ctx $_->[0] # convert "pkg" to "ctx"
666 for values %LOGGER;
564 667
565# create the default logger contexts 668# create the default logger contexts
566$LOG = ctx undef; 669$LOG = ctx undef;
567$FILTER = ctx undef; 670$FILTER = ctx undef;
568$COLLECT = ctx undef; 671$COLLECT = ctx undef;
… …
577package AnyEvent::Log::COLLECT; 680package AnyEvent::Log::COLLECT;
578package AE::Log::COLLECT; 681package AE::Log::COLLECT;
579 682
580package AnyEvent::Log::Ctx; 683package AnyEvent::Log::Ctx;
581 684
582# 0 1 2 3 4
583# [$title, $level, %$slaves, &$logcb, &$fmtcb]
584
585=item $ctx = new AnyEvent::Log::Ctx methodname => param... 685=item $ctx = new AnyEvent::Log::Ctx methodname => param...
586 686
587This is a convenience constructor that makes it simpler to construct 687This is a convenience constructor that makes it simpler to construct
588anonymous logging contexts. 688anonymous logging contexts.
589 689
… …
676 776
677=item $ctx->disable ($level[, $level...]) 777=item $ctx->disable ($level[, $level...])
678 778
679Disables logging for the given levels, leaving all others unchanged. 779Disables logging for the given levels, leaving all others unchanged.
680 780
781=item $ctx->cap ($level)
782
783Caps the maximum priority to the given level, for all messages logged
784to, or passing through, this context. That is, while this doesn't affect
785whether a message is logged or passed on, the maximum priority of messages
786will be limited to the specified level - messages with a higher priority
787will be set to the specified priority.
788
789Another way to view this is that C<< ->level >> filters out messages with
790a too low priority, while C<< ->cap >> modifies messages with a too high
791priority.
792
793This is useful when different log targets have different interpretations
794of priority. For example, for a specific command line program, a wrong
795command line switch might well result in a C<fatal> log message, while the
796same message, logged to syslog, is likely I<not> fatal to the system or
797syslog facility as a whole, but more likely a mere C<error>.
798
799This can be modeled by having a stderr logger that logs messages "as-is"
800and a syslog logger that logs messages with a level cap of, say, C<error>,
801or, for truly system-critical components, actually C<critical>.
802
681=cut 803=cut
682 804
683sub _lvl_lst { 805sub _lvl_lst {
684 map { 806 map {
685 $_ > 0 && $_ <= 9 ? $_+0 807 $_ > 0 && $_ <= 9 ? $_+0
686 : $_ eq "all" ? (1 .. 9) 808 : $_ eq "all" ? (1 .. 9)
687 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught" 809 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught"
688 } @_ 810 } @_
689} 811}
690 812
813sub _lvl {
814 $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1]
815}
816
691our $NOP_CB = sub { 0 }; 817our $NOP_CB = sub { 0 };
692 818
693sub levels { 819sub levels {
694 my $ctx = shift; 820 my $ctx = shift;
695 $ctx->[1] = 0; 821 $ctx->[1] = 0;
… …
698 AnyEvent::Log::_reassess; 824 AnyEvent::Log::_reassess;
699} 825}
700 826
701sub level { 827sub level {
702 my $ctx = shift; 828 my $ctx = shift;
703 my $lvl = $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1];
704
705 $ctx->[1] = ((1 << $lvl) - 1) << 1; 829 $ctx->[1] = ((1 << &_lvl) - 1) << 1;
706 AnyEvent::Log::_reassess; 830 AnyEvent::Log::_reassess;
707} 831}
708 832
709sub enable { 833sub enable {
710 my $ctx = shift; 834 my $ctx = shift;
… …
718 $ctx->[1] &= ~(1 << $_) 842 $ctx->[1] &= ~(1 << $_)
719 for &_lvl_lst; 843 for &_lvl_lst;
720 AnyEvent::Log::_reassess; 844 AnyEvent::Log::_reassess;
721} 845}
722 846
847sub cap {
848 my $ctx = shift;
849 $ctx->[5] = &_lvl;
850}
851
723=back 852=back
724 853
725=head3 SLAVE CONTEXTS 854=head3 SLAVE CONTEXTS
726 855
727The following methods attach and detach another logging context to a 856The following methods attach and detach another logging context to a
… …
755sub attach { 884sub attach {
756 my $ctx = shift; 885 my $ctx = shift;
757 886
758 $ctx->[2]{$_+0} = $_ 887 $ctx->[2]{$_+0} = $_
759 for map { AnyEvent::Log::ctx $_ } @_; 888 for map { AnyEvent::Log::ctx $_ } @_;
889 AnyEvent::Log::_reassess;
760} 890}
761 891
762sub detach { 892sub detach {
763 my $ctx = shift; 893 my $ctx = shift;
764 894
765 delete $ctx->[2]{$_+0} 895 delete $ctx->[2]{$_+0}
766 for map { AnyEvent::Log::ctx $_ } @_; 896 for map { AnyEvent::Log::ctx $_ } @_;
897 AnyEvent::Log::_reassess;
767} 898}
768 899
769sub slaves { 900sub slaves {
770 undef $_[0][2]; 901 undef $_[0][2];
771 &attach; 902 &attach;
903 AnyEvent::Log::_reassess;
772} 904}
773 905
774=back 906=back
775 907
776=head3 LOG TARGETS 908=head3 LOG TARGETS
… …
779the logging (which consists of formatting the message and printing it or 911the logging (which consists of formatting the message and printing it or
780whatever it wants to do with it). 912whatever it wants to do with it).
781 913
782=over 4 914=over 4
783 915
784=item $ctx->log_cb ($cb->($str) 916=item $ctx->log_cb ($cb->($str))
785 917
786Replaces the logging callback on the context (C<undef> disables the 918Replaces the logging callback on the context (C<undef> disables the
787logging callback). 919logging callback).
788 920
789The logging callback is responsible for handling formatted log messages 921The logging callback is responsible for handling formatted log messages
… …
814 946
815Replaces the formatting callback on the context (C<undef> restores the 947Replaces the formatting callback on the context (C<undef> restores the
816default formatter). 948default formatter).
817 949
818The callback is passed the (possibly fractional) timestamp, the original 950The callback is passed the (possibly fractional) timestamp, the original
819logging context, the (numeric) logging level and the raw message string 951logging context (object, not title), the (numeric) logging level and
820and needs to return a formatted log message. In most cases this will be a 952the raw message string and needs to return a formatted log message. In
821string, but it could just as well be an array reference that just stores 953most cases this will be a string, but it could just as well be an array
822the values. 954reference that just stores the values.
823 955
824If, for some reason, you want to use C<caller> to find out more baout the 956If, for some reason, you want to use C<caller> to find out more about the
825logger then you should walk up the call stack until you are no longer 957logger then you should walk up the call stack until you are no longer
826inside the C<AnyEvent::Log> package. 958inside the C<AnyEvent::Log> package.
827 959
960To implement your own logging callback, you might find the
961C<AnyEvent::Log::format_time> and C<AnyEvent::Log::default_format>
962functions useful.
963
964Example: format the message just as AnyEvent::Log would, by letting
965AnyEvent::Log do the work. This is a good basis to design a formatting
966callback that only changes minor aspects of the formatting.
967
968 $ctx->fmt_cb (sub {
969 my ($time, $ctx, $lvl, $msg) = @_;
970
971 AnyEvent::Log::default_format $time, $ctx, $lvl, $msg
972 });
973
828Example: format just the raw message, with numeric log level in angle 974Example: format just the raw message, with numeric log level in angle
829brackets. 975brackets.
830 976
831 $ctx->fmt_cb (sub { 977 $ctx->fmt_cb (sub {
832 my ($time, $ctx, $lvl, $msg) = @_; 978 my ($time, $ctx, $lvl, $msg) = @_;
833 979
834 "<$lvl>$msg\n" 980 "<$lvl>$msg\n"
835 }); 981 });
836 982
837Example: return an array reference with just the log values, and use 983Example: return an array reference with just the log values, and use
838C<PApp::SQL::sql_exec> to store the emssage in a database. 984C<PApp::SQL::sql_exec> to store the message in a database.
839 985
840 $ctx->fmt_cb (sub { \@_ }); 986 $ctx->fmt_cb (sub { \@_ });
841 $ctx->log_cb (sub { 987 $ctx->log_cb (sub {
842 my ($msg) = @_; 988 my ($msg) = @_;
843 989
… …
855Sets the C<log_cb> to simply use C<CORE::warn> to report any messages 1001Sets the C<log_cb> to simply use C<CORE::warn> to report any messages
856(usually this logs to STDERR). 1002(usually this logs to STDERR).
857 1003
858=item $ctx->log_to_file ($path) 1004=item $ctx->log_to_file ($path)
859 1005
860Sets the C<log_cb> to log to a file (by appending), unbuffered. 1006Sets the C<log_cb> to log to a file (by appending), unbuffered. The
1007function might return before the log file has been opened or created.
861 1008
862=item $ctx->log_to_path ($path) 1009=item $ctx->log_to_path ($path)
863 1010
864Same as C<< ->log_to_file >>, but opens the file for each message. This 1011Same as C<< ->log_to_file >>, but opens the file for each message. This
865is much slower, but allows you to change/move/rename/delete the file at 1012is much slower, but allows you to change/move/rename/delete the file at
… …
900 warn shift; 1047 warn shift;
901 0 1048 0
902 }); 1049 });
903} 1050}
904 1051
1052# this function is a good example of why threads are a must,
1053# simply for priority inversion.
1054sub _log_to_disk {
1055 # eval'uating this at runtime saves 220kb rss - perl has become
1056 # an insane memory waster.
1057 eval q{ # poor man's autoloading {}
1058 sub _log_to_disk {
1059 my ($ctx, $path, $keepopen) = @_;
1060
1061 my $fh;
1062 my @queue;
1063 my $delay;
1064 my $disable;
1065
1066 use AnyEvent::IO ();
1067
1068 my $kick = sub {
1069 undef $delay;
1070 return unless @queue;
1071 $delay = 1;
1072
1073 # we pass $kick to $kick, so $kick itself doesn't keep a reference to $kick.
1074 my $kick = shift;
1075
1076 # write one or more messages
1077 my $write = sub {
1078 # we write as many messages as have been queued
1079 my $data = join "", @queue;
1080 @queue = ();
1081
1082 AnyEvent::IO::aio_write $fh, $data, sub {
1083 $disable = 1;
1084 @_
1085 ? ($_[0] == length $data or AE::log 4 => "unable to write to logfile '$path': short write")
1086 : AE::log 4 => "unable to write to logfile '$path': $!";
1087 undef $disable;
1088
1089 if ($keepopen) {
1090 $kick->($kick);
1091 } else {
1092 AnyEvent::IO::aio_close ($fh, sub {
1093 undef $fh;
1094 $kick->($kick);
1095 });
1096 }
1097 };
1098 };
1099
1100 if ($fh) {
1101 $write->();
1102 } else {
1103 AnyEvent::IO::aio_open
1104 $path,
1105 AnyEvent::IO::O_CREAT | AnyEvent::IO::O_WRONLY | AnyEvent::IO::O_APPEND,
1106 0666,
1107 sub {
1108 $fh = shift
1109 or do {
1110 $disable = 1;
1111 AE::log 4 => "unable to open logfile '$path': $!";
1112 undef $disable;
1113 return;
1114 };
1115
1116 $write->();
1117 }
1118 ;
1119 }
1120 };
1121
1122 $ctx->log_cb (sub {
1123 return if $disable;
1124 push @queue, shift;
1125 $kick->($kick) unless $delay;
1126 0
1127 });
1128
1129 $kick->($kick) if $keepopen; # initial open
1130 };
1131 };
1132 die if $@;
1133 &_log_to_disk
1134}
1135
905sub log_to_file { 1136sub log_to_file {
906 my ($ctx, $path) = @_; 1137 my ($ctx, $path) = @_;
907 1138
908 open my $fh, ">>", $path 1139 _log_to_disk $ctx, $path, 1;
909 or die "$path: $!";
910
911 $ctx->log_cb (sub {
912 syswrite $fh, shift;
913 0
914 });
915} 1140}
916 1141
917sub log_to_path { 1142sub log_to_path {
918 my ($ctx, $path) = @_; 1143 my ($ctx, $path) = @_;
919 1144
920 $ctx->log_cb (sub { 1145 _log_to_disk $ctx, $path, 0;
921 open my $fh, ">>", $path
922 or die "$path: $!";
923
924 syswrite $fh, shift;
925 0
926 });
927} 1146}
928 1147
929sub log_to_syslog { 1148sub log_to_syslog {
930 my ($ctx, $facility) = @_; 1149 my ($ctx, $facility) = @_;
931 1150
… …
960=over 4 1179=over 4
961 1180
962=item $ctx->log ($level, $msg[, @params]) 1181=item $ctx->log ($level, $msg[, @params])
963 1182
964Same as C<AnyEvent::Log::log>, but uses the given context as log context. 1183Same as C<AnyEvent::Log::log>, but uses the given context as log context.
1184
1185Example: log a message in the context of another package.
1186
1187 (AnyEvent::Log::ctx "Other::Package")->log (warn => "heely bo");
965 1188
966=item $logger = $ctx->logger ($level[, \$enabled]) 1189=item $logger = $ctx->logger ($level[, \$enabled])
967 1190
968Same as C<AnyEvent::Log::logger>, but uses the given context as log 1191Same as C<AnyEvent::Log::logger>, but uses the given context as log
969context. 1192context.
… …
1017 1240
1018Context names starting with a C<%> are anonymous contexts created when the 1241Context names starting with a C<%> are anonymous contexts created when the
1019name is first mentioned. The difference to package contexts is that by 1242name is first mentioned. The difference to package contexts is that by
1020default they have no attached slaves. 1243default they have no attached slaves.
1021 1244
1245This makes it possible to create new log contexts that can be refered to
1246multiple times by name within the same log specification.
1247
1022=item a perl package name 1248=item a perl package name
1023 1249
1024Any other string references the logging context associated with the given 1250Any other string references the logging context associated with the given
1025Perl C<package>. In the unlikely case where you want to specify a package 1251Perl C<package>. In the unlikely case where you want to specify a package
1026context that matches on of the other context name forms, you can add a 1252context that matches on of the other context name forms, you can add a
… …
1057=item C<nolog> 1283=item C<nolog>
1058 1284
1059Configures the context to not log anything by itself, which is the 1285Configures the context to not log anything by itself, which is the
1060default. Same as C<< $ctx->log_cb (undef) >>. 1286default. Same as C<< $ctx->log_cb (undef) >>.
1061 1287
1288=item C<cap=>I<level>
1289
1290Caps logging messages entering this context at the given level, i.e.
1291reduces the priority of messages with higher priority than this level. The
1292default is C<0> (or C<off>), meaning the priority will not be touched.
1293
1062=item C<0> or C<off> 1294=item C<0> or C<off>
1063 1295
1064Sets the logging level of the context ot C<0>, i.e. all messages will be 1296Sets the logging level of the context to C<0>, i.e. all messages will be
1065filtered out. 1297filtered out.
1066 1298
1067=item C<all> 1299=item C<all>
1068 1300
1069Enables all logging levels, i.e. filtering will effectively be switched 1301Enables all logging levels, i.e. filtering will effectively be switched
… …
1111 1343
1112Attaches the named context as slave to the context. 1344Attaches the named context as slave to the context.
1113 1345
1114=item C<+> 1346=item C<+>
1115 1347
1116A line C<+> detaches all contexts, i.e. clears the slave list from the 1348A lone C<+> detaches all contexts, i.e. clears the slave list from the
1117context. Anonymous (C<%name>) contexts have no attached slaves by default, 1349context. Anonymous (C<%name>) contexts have no attached slaves by default,
1118but package contexts have the parent context as slave by default. 1350but package contexts have the parent context as slave by default.
1119 1351
1120Example: log messages from My::Module to a file, do not send them to the 1352Example: log messages from My::Module to a file, do not send them to the
1121default log collector. 1353default log collector.
… …
1152 1384
1153 my $pkg = sub { 1385 my $pkg = sub {
1154 $_[0] eq "log" ? $LOG 1386 $_[0] eq "log" ? $LOG
1155 : $_[0] eq "filter" ? $FILTER 1387 : $_[0] eq "filter" ? $FILTER
1156 : $_[0] eq "collect" ? $COLLECT 1388 : $_[0] eq "collect" ? $COLLECT
1157 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= ctx undef) 1389 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= do { my $ctx = ctx undef; $ctx->[0] = $_[0]; $ctx })
1158 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/ 1390 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/
1159 : die # never reached? 1391 : die # never reached?
1160 }; 1392 };
1161 1393
1162 /\G[[:space:]]+/gc; # skip initial whitespace 1394 /\G[[:space:]]+/gc; # skip initial whitespace
… …
1168 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) { 1400 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) {
1169 for ("$1") { 1401 for ("$1") {
1170 if ($_ eq "stderr" ) { $ctx->log_to_warn; 1402 if ($_ eq "stderr" ) { $ctx->log_to_warn;
1171 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1"); 1403 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1");
1172 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1"); 1404 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1");
1173 } elsif (/syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog ($1); 1405 } elsif (/^syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog ("$1");
1174 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef); 1406 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef);
1407 } elsif (/^cap=(.+)/ ) { $ctx->cap ("$1");
1175 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1")); 1408 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1"));
1176 } elsif ($_ eq "+" ) { $ctx->slaves; 1409 } elsif ($_ eq "+" ) { $ctx->slaves;
1177 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0); 1410 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0);
1178 } elsif ($_ eq "all" ) { $ctx->level ("all"); 1411 } elsif ($_ eq "all" ) { $ctx->level ("all");
1179 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level"; 1412 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level";
… …
1196 if (/\G(.+)/g) { 1429 if (/\G(.+)/g) {
1197 die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n"; 1430 die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n";
1198 } 1431 }
1199} 1432}
1200 1433
12011;
1202
1203=head1 EXAMPLES 1434=head1 EXAMPLES
1204 1435
1205This section shows some common configurations, both as code, and as 1436This section shows some common configurations, both as code, and as
1206C<PERL_ANYEVENT_LOG> string. 1437C<PERL_ANYEVENT_LOG> string.
1207 1438
… …
1231 1462
1232This writes them only when the global logging level allows it, because 1463This writes them only when the global logging level allows it, because
1233it is attached to the default context which is invoked I<after> global 1464it is attached to the default context which is invoked I<after> global
1234filtering. 1465filtering.
1235 1466
1236 $AnyEvent::Log::FILTER->attach 1467 $AnyEvent::Log::FILTER->attach (
1237 new AnyEvent::Log::Ctx log_to_file => $path); 1468 new AnyEvent::Log::Ctx log_to_file => $path);
1238 1469
1239 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path 1470 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
1240 1471
1241This writes them regardless of the global logging level, because it is 1472This writes them regardless of the global logging level, because it is
… …
1247 1478
1248 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger 1479 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
1249 1480
1250In both cases, messages are still written to STDERR. 1481In both cases, messages are still written to STDERR.
1251 1482
1483=item Additionally log all messages with C<warn> and higher priority to
1484C<syslog>, but cap at C<error>.
1485
1486This logs all messages to the default log target, but also logs messages
1487with priority C<warn> or higher (and not filtered otherwise) to syslog
1488facility C<user>. Messages with priority higher than C<error> will be
1489logged with level C<error>.
1490
1491 $AnyEvent::Log::LOG->attach (
1492 new AnyEvent::Log::Ctx
1493 level => "warn",
1494 cap => "error",
1495 syslog => "user",
1496 );
1497
1498 PERL_ANYEVENT_LOG=log=+%syslog:%syslog=warn,cap=error,syslog
1499
1252=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s). 1500=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s).
1253 1501
1254Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug> 1502Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug>
1255context - this simply circumvents the global filtering for trace messages. 1503context - this simply circumvents the global filtering for trace messages.
1256 1504
… …
1263assumes the log level for AnyEvent::Debug hasn't been changed from the 1511assumes the log level for AnyEvent::Debug hasn't been changed from the
1264default. 1512default.
1265 1513
1266=back 1514=back
1267 1515
1516=head1 ASYNCHRONOUS DISK I/O
1517
1518This module uses L<AnyEvent::IO> to actually write log messages (in
1519C<log_to_file> and C<log_to_path>), so it doesn't block your program when
1520the disk is busy and a non-blocking L<AnyEvent::IO> backend is available.
1521
1268=head1 AUTHOR 1522=head1 AUTHOR
1269 1523
1270 Marc Lehmann <schmorp@schmorp.de> 1524 Marc Lehmann <schmorp@schmorp.de>
1271 http://home.schmorp.de/ 1525 http://anyevent.schmorp.de
1272 1526
1273=cut 1527=cut
1274 1528
15291
1530

Diff Legend

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