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.66 by root, Mon Mar 11 20:48:19 2019 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
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):
… …
46attempt to be "the" logging solution or even "a" logging solution for 61attempt to be "the" logging solution or even "a" logging solution for
47AnyEvent - AnyEvent simply creates logging messages internally, and this 62AnyEvent - AnyEvent simply creates logging messages internally, and this
48module 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
49using it from other modules as well. 64using it from other modules as well.
50 65
51Remember 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
52will be logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number 67errors and more important messages will be logged, unless you set
53before starting your program, or change the logging level at runtime with 68C<PERL_ANYEVENT_VERBOSE> to a higher number before starting your program
54something like: 69(C<AE_VERBOSE=5> is recommended during development), or change the logging
70level at runtime with something like:
55 71
56 use AnyEvent::Log; 72 use AnyEvent::Log;
57 $AnyEvent::Log::FILTER->level ("info"); 73 $AnyEvent::Log::FILTER->level ("info");
58 74
59The 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),
60but make it powerful enough to be potentially useful for any module, and 76but make it powerful enough to be potentially useful for any module,
61extensive enough for the most common tasks, such as logging to multiple 77and extensive enough for the most common tasks, such as logging to
62targets, or being able to log into a database. 78multiple targets, or being able to log into a database.
63 79
64The module is also usable before AnyEvent itself is initialised, in which 80The module is also usable before AnyEvent itself is initialised, in which
65case some of the functionality might be reduced. 81case some of the functionality might be reduced.
66 82
67The amount of documentation might indicate otherwise, but the runtime part 83The amount of documentation might indicate otherwise, but the runtime part
… …
75numerical value". 91numerical value".
76 92
77Instead 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:
78 94
79 LVL NAME SYSLOG PERL NOTE 95 LVL NAME SYSLOG PERL NOTE
80 1 fatal emerg exit aborts program! 96 1 fatal emerg exit system unusable, aborts program!
81 2 alert 97 2 alert failure in primary system
82 3 critical crit 98 3 critical crit failure in backup system
83 4 error err die 99 4 error err die non-urgent program errors, a bug
84 5 warn warning 100 5 warn warning possible problem, not necessarily error
85 6 note notice 101 6 note notice unusual conditions
86 7 info 102 7 info normal messages, no action required
87 8 debug 103 8 debug debugging messages for development
88 9 trace 104 9 trace copious tracing output
89 105
90As 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
91is 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)
92and the third one the "perl" name, suggesting (only!) that you log C<die> 108and the third one the "perl" name, suggesting (only!) that you log C<die>
93messages at C<error> priority. 109messages at C<error> priority. The NOTE column tries to provide some
110rationale on how to chose a logging level.
94 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
95You 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>,
96(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
97program - 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.
98 124
99Some 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>
100or 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.
101 127
102=head1 LOGGING FUNCTIONS 128=head1 LOGGING FUNCTIONS
103 129
104These functions allow you to log messages. They always use the caller's 130The following functions allow you to log messages. They always use the
105package as a "logging context". Also, the main logging function C<log> is 131caller'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 132C<log>, is aliased to C<AnyEvent::log> and C<AE::log> when the C<AnyEvent>
107loaded. 133module is loaded.
108 134
109=over 4 135=over 4
110 136
111=cut 137=cut
112 138
113package AnyEvent::Log; 139package AnyEvent::Log;
114 140
115use Carp (); 141use Carp ();
116use POSIX (); 142use POSIX ();
117 143
144# layout of a context
145# 0 1 2 3 4, 5
146# [$title, $level, %$slaves, &$logcb, &$fmtcb, $cap]
147
118use AnyEvent (); BEGIN { AnyEvent::common_sense } 148use AnyEvent (); BEGIN { AnyEvent::common_sense }
119#use AnyEvent::Util (); need to load this in a delayed fashion, as it uses AE::log 149#use AnyEvent::Util (); need to load this in a delayed fashion, as it uses AE::log
120 150
121our $VERSION = $AnyEvent::VERSION; 151our $VERSION = $AnyEvent::VERSION;
122 152
123our ($COLLECT, $FILTER, $LOG); 153our ($COLLECT, $FILTER, $LOG);
124 154
125our ($now_int, $now_str1, $now_str2); 155our ($now_int, $now_str1, $now_str2);
126 156
127# Format Time, not public - yet? 157# Format Time, not public - yet?
128sub ft($) { 158sub format_time($) {
129 my $i = int $_[0]; 159 my $i = int $_[0];
130 my $f = sprintf "%06d", 1e6 * ($_[0] - $i); 160 my $f = sprintf "%06d", 1e6 * ($_[0] - $i);
131 161
132 ($now_int, $now_str1, $now_str2) = ($i, split /\x01/, POSIX::strftime "%Y-%m-%d %H:%M:%S.\x01 %z", localtime $i) 162 ($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; 163 if $now_int != $i;
… …
166 196
167Last 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
168supposed 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
169actually 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
170message 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.
171 204
172Whether 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
173and 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
174messages or not "lost" - for example, when L<AnyEvent::Debug> detects a 207messages 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 208runtime error it tries to log it at C<die> level, but if that message is
… …
229}; 262};
230 263
231our @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);
232 265
233# time, ctx, level, msg 266# time, ctx, level, msg
234sub _format($$$$) { 267sub default_format($$$$) {
235 my $ts = ft $_[0]; 268 my $ts = format_time $_[0];
236 my $ct = " "; 269 my $ct = " ";
237 270
238 my @res; 271 my @res;
239 272
240 for (split /\n/, sprintf "%-5s %s: %s", $LEVEL2STR[$_[2]], $_[1][0], $_[3]) { 273 for (split /\n/, sprintf "%-5s %s: %s", $LEVEL2STR[$_[2]], $_[1][0], $_[3]) {
… …
243 } 276 }
244 277
245 join "", @res 278 join "", @res
246} 279}
247 280
281sub fatal_exit() {
282 exit 1;
283}
284
248sub _log { 285sub _log {
249 my ($ctx, $level, $format, @args) = @_; 286 my ($ctx, $level, $format, @args) = @_;
250 287
251 $level = $level > 0 && $level <= 9 288 $level = $level > 0 && $level <= 9
252 ? $level+0 289 ? $level+0
253 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught"; 290 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught";
254 291
255 my $mask = 1 << $level; 292 my $mask = 1 << $level;
256 293
257 my ($success, %seen, @ctx, $now, $fmt); 294 my ($success, %seen, @ctx, $now, @fmt);
258 295
259 do 296 do
260 { 297 {
261 # skip if masked 298 # if !ref, then it's a level number
299 if (!ref $ctx) {
300 $level = $ctx;
262 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
263 if ($ctx->[3]) { 311 if ($ctx->[3]) {
264 # logging target found 312 # logging target found
313
314 local ($!, $@);
265 315
266 # now get raw message, unless we have it already 316 # now get raw message, unless we have it already
267 unless ($now) { 317 unless ($now) {
268 $format = $format->() if ref $format; 318 $format = $format->() if ref $format;
269 $format = sprintf $format, @args if @args; 319 $format = sprintf $format, @args if @args;
… …
272 }; 322 };
273 323
274 # format msg 324 # format msg
275 my $str = $ctx->[4] 325 my $str = $ctx->[4]
276 ? $ctx->[4]($now, $_[0], $level, $format) 326 ? $ctx->[4]($now, $_[0], $level, $format)
277 : ($fmt ||= _format $now, $_[0], $level, $format); 327 : ($fmt[$level] ||= default_format $now, $_[0], $level, $format);
278 328
279 $success = 1; 329 $success = 1;
280 330
281 $ctx->[3]($str) 331 $ctx->[3]($str)
282 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate 332 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate
… …
285 } 335 }
286 } 336 }
287 } 337 }
288 while $ctx = pop @ctx; 338 while $ctx = pop @ctx;
289 339
290 exit 1 if $level <= 1; 340 fatal_exit if $level <= 1;
291 341
292 $success 342 $success
293} 343}
294 344
295sub log($$;@) { 345sub log($$;@) {
296 _log 346 _log
297 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 347 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
298 @_; 348 @_;
299} 349}
300 350
301*AnyEvent::log = *AE::log = \&log;
302
303=item $logger = AnyEvent::Log::logger $level[, \$enabled] 351=item $logger = AnyEvent::Log::logger $level[, \$enabled]
304 352
305Creates a code reference that, when called, acts as if the 353Creates a code reference that, when called, acts as if the
306C<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
307level. 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
… …
371 419
372 $LOGGER{$logger+0} = $logger; 420 $LOGGER{$logger+0} = $logger;
373 421
374 _reassess $logger+0; 422 _reassess $logger+0;
375 423
376 require AnyEvent::Util; 424 require AnyEvent::Util unless $AnyEvent::Util::VERSION;
377 my $guard = AnyEvent::Util::guard (sub { 425 my $guard = AnyEvent::Util::guard (sub {
378 # "clean up" 426 # "clean up"
379 delete $LOGGER{$logger+0}; 427 delete $LOGGER{$logger+0};
380 }); 428 });
381 429
… …
405 453
406Since C<AnyEvent::Log> has to work even before the L<AnyEvent> has been 454Since C<AnyEvent::Log> has to work even before the L<AnyEvent> has been
407initialised, this switch will also decide whether to use C<CORE::time> or 455initialised, this switch will also decide whether to use C<CORE::time> or
408C<Time::HiRes::time> when logging a message before L<AnyEvent> becomes 456C<Time::HiRes::time> when logging a message before L<AnyEvent> becomes
409available. 457available.
458
459=item AnyEvent::Log::format_time $timestamp
460
461Formats a timestamp as returned by C<< AnyEvent->now >> or C<<
462AnyEvent->time >> or many other functions in the same way as
463C<AnyEvent::Log> does.
464
465In your main program (as opposed to in your module) you can override
466the default timestamp display format by loading this module and then
467redefining this function.
468
469Most commonly, this function can be used in formatting callbacks.
470
471=item AnyEvent::Log::default_format $time, $ctx, $level, $msg
472
473Format a log message using the given timestamp, logging context, log level
474and log message.
475
476This is the formatting function used to format messages when no custom
477function is provided.
478
479In your main program (as opposed to in your module) you can override the
480default message format by loading this module and then redefining this
481function.
482
483=item AnyEvent::Log::fatal_exit()
484
485This is the function that is called after logging a C<fatal> log
486message. It must not return.
487
488The default implementation simply calls C<exit 1>.
489
490In your main program (as opposed to in your module) you can override
491the fatal exit function by loading this module and then redefining this
492function. Make sure you don't return.
410 493
411=back 494=back
412 495
413=head1 LOGGING CONTEXTS 496=head1 LOGGING CONTEXTS
414 497
… …
534This can be used to implement config-file (re-)loading: before loading a 617This can be used to implement config-file (re-)loading: before loading a
535configuration, reset all contexts. 618configuration, reset all contexts.
536 619
537=cut 620=cut
538 621
622our $ORIG_VERBOSE = $AnyEvent::VERBOSE;
623$AnyEvent::VERBOSE = 9;
624
539sub reset { 625sub reset {
540 # hard to kill complex data structures 626 # hard to kill complex data structures
541 # we "recreate" all package loggers and reset the hierarchy 627 # we "recreate" all package loggers and reset the hierarchy
542 while (my ($k, $v) = each %CTX) { 628 while (my ($k, $v) = each %CTX) {
543 @$v = ($k, (1 << 10) - 1 - 1, { }); 629 @$v = ($k, (1 << 10) - 1 - 1, { });
… …
552 $LOG->title ('$AnyEvent::Log::LOG'); 638 $LOG->title ('$AnyEvent::Log::LOG');
553 $LOG->log_to_warn; 639 $LOG->log_to_warn;
554 640
555 $FILTER->slaves ($LOG); 641 $FILTER->slaves ($LOG);
556 $FILTER->title ('$AnyEvent::Log::FILTER'); 642 $FILTER->title ('$AnyEvent::Log::FILTER');
557 $FILTER->level ($AnyEvent::VERBOSE); 643 $FILTER->level ($ORIG_VERBOSE);
558 644
559 $COLLECT->slaves ($FILTER); 645 $COLLECT->slaves ($FILTER);
560 $COLLECT->title ('$AnyEvent::Log::COLLECT'); 646 $COLLECT->title ('$AnyEvent::Log::COLLECT');
561 647
562 _reassess; 648 _reassess;
563} 649}
650
651# override AE::log/logger
652*AnyEvent::log = *AE::log = \&log;
653*AnyEvent::logger = *AE::logger = \&logger;
654
655# convert AnyEvent loggers to AnyEvent::Log loggers
656$_->[0] = ctx $_->[0] # convert "pkg" to "ctx"
657 for values %LOGGER;
564 658
565# create the default logger contexts 659# create the default logger contexts
566$LOG = ctx undef; 660$LOG = ctx undef;
567$FILTER = ctx undef; 661$FILTER = ctx undef;
568$COLLECT = ctx undef; 662$COLLECT = ctx undef;
… …
577package AnyEvent::Log::COLLECT; 671package AnyEvent::Log::COLLECT;
578package AE::Log::COLLECT; 672package AE::Log::COLLECT;
579 673
580package AnyEvent::Log::Ctx; 674package AnyEvent::Log::Ctx;
581 675
582# 0 1 2 3 4
583# [$title, $level, %$slaves, &$logcb, &$fmtcb]
584
585=item $ctx = new AnyEvent::Log::Ctx methodname => param... 676=item $ctx = new AnyEvent::Log::Ctx methodname => param...
586 677
587This is a convenience constructor that makes it simpler to construct 678This is a convenience constructor that makes it simpler to construct
588anonymous logging contexts. 679anonymous logging contexts.
589 680
… …
676 767
677=item $ctx->disable ($level[, $level...]) 768=item $ctx->disable ($level[, $level...])
678 769
679Disables logging for the given levels, leaving all others unchanged. 770Disables logging for the given levels, leaving all others unchanged.
680 771
772=item $ctx->cap ($level)
773
774Caps the maximum priority to the given level, for all messages logged
775to, or passing through, this context. That is, while this doesn't affect
776whether a message is logged or passed on, the maximum priority of messages
777will be limited to the specified level - messages with a higher priority
778will be set to the specified priority.
779
780Another way to view this is that C<< ->level >> filters out messages with
781a too low priority, while C<< ->cap >> modifies messages with a too high
782priority.
783
784This is useful when different log targets have different interpretations
785of priority. For example, for a specific command line program, a wrong
786command line switch might well result in a C<fatal> log message, while the
787same message, logged to syslog, is likely I<not> fatal to the system or
788syslog facility as a whole, but more likely a mere C<error>.
789
790This can be modeled by having a stderr logger that logs messages "as-is"
791and a syslog logger that logs messages with a level cap of, say, C<error>,
792or, for truly system-critical components, actually C<critical>.
793
681=cut 794=cut
682 795
683sub _lvl_lst { 796sub _lvl_lst {
684 map { 797 map {
685 $_ > 0 && $_ <= 9 ? $_+0 798 $_ > 0 && $_ <= 9 ? $_+0
686 : $_ eq "all" ? (1 .. 9) 799 : $_ eq "all" ? (1 .. 9)
687 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught" 800 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught"
688 } @_ 801 } @_
689} 802}
690 803
804sub _lvl {
805 $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1]
806}
807
691our $NOP_CB = sub { 0 }; 808our $NOP_CB = sub { 0 };
692 809
693sub levels { 810sub levels {
694 my $ctx = shift; 811 my $ctx = shift;
695 $ctx->[1] = 0; 812 $ctx->[1] = 0;
… …
698 AnyEvent::Log::_reassess; 815 AnyEvent::Log::_reassess;
699} 816}
700 817
701sub level { 818sub level {
702 my $ctx = shift; 819 my $ctx = shift;
703 my $lvl = $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1];
704
705 $ctx->[1] = ((1 << $lvl) - 1) << 1; 820 $ctx->[1] = ((1 << &_lvl) - 1) << 1;
706 AnyEvent::Log::_reassess; 821 AnyEvent::Log::_reassess;
707} 822}
708 823
709sub enable { 824sub enable {
710 my $ctx = shift; 825 my $ctx = shift;
… …
718 $ctx->[1] &= ~(1 << $_) 833 $ctx->[1] &= ~(1 << $_)
719 for &_lvl_lst; 834 for &_lvl_lst;
720 AnyEvent::Log::_reassess; 835 AnyEvent::Log::_reassess;
721} 836}
722 837
838sub cap {
839 my $ctx = shift;
840 $ctx->[5] = &_lvl;
841}
842
723=back 843=back
724 844
725=head3 SLAVE CONTEXTS 845=head3 SLAVE CONTEXTS
726 846
727The following methods attach and detach another logging context to a 847The following methods attach and detach another logging context to a
… …
779the logging (which consists of formatting the message and printing it or 899the logging (which consists of formatting the message and printing it or
780whatever it wants to do with it). 900whatever it wants to do with it).
781 901
782=over 4 902=over 4
783 903
784=item $ctx->log_cb ($cb->($str) 904=item $ctx->log_cb ($cb->($str))
785 905
786Replaces the logging callback on the context (C<undef> disables the 906Replaces the logging callback on the context (C<undef> disables the
787logging callback). 907logging callback).
788 908
789The logging callback is responsible for handling formatted log messages 909The logging callback is responsible for handling formatted log messages
… …
814 934
815Replaces the formatting callback on the context (C<undef> restores the 935Replaces the formatting callback on the context (C<undef> restores the
816default formatter). 936default formatter).
817 937
818The callback is passed the (possibly fractional) timestamp, the original 938The callback is passed the (possibly fractional) timestamp, the original
819logging context, the (numeric) logging level and the raw message string 939logging context (object, not title), the (numeric) logging level and
820and needs to return a formatted log message. In most cases this will be a 940the 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 941most cases this will be a string, but it could just as well be an array
822the values. 942reference that just stores the values.
823 943
824If, for some reason, you want to use C<caller> to find out more baout the 944If, 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 945logger then you should walk up the call stack until you are no longer
826inside the C<AnyEvent::Log> package. 946inside the C<AnyEvent::Log> package.
827 947
948To implement your own logging callback, you might find the
949C<AnyEvent::Log::format_time> and C<AnyEvent::Log::default_format>
950functions useful.
951
952Example: format the message just as AnyEvent::Log would, by letting
953AnyEvent::Log do the work. This is a good basis to design a formatting
954callback that only changes minor aspects of the formatting.
955
956 $ctx->fmt_cb (sub {
957 my ($time, $ctx, $lvl, $msg) = @_;
958
959 AnyEvent::Log::default_format $time, $ctx, $lvl, $msg
960 });
961
828Example: format just the raw message, with numeric log level in angle 962Example: format just the raw message, with numeric log level in angle
829brackets. 963brackets.
830 964
831 $ctx->fmt_cb (sub { 965 $ctx->fmt_cb (sub {
832 my ($time, $ctx, $lvl, $msg) = @_; 966 my ($time, $ctx, $lvl, $msg) = @_;
833 967
834 "<$lvl>$msg\n" 968 "<$lvl>$msg\n"
835 }); 969 });
836 970
837Example: return an array reference with just the log values, and use 971Example: return an array reference with just the log values, and use
838C<PApp::SQL::sql_exec> to store the emssage in a database. 972C<PApp::SQL::sql_exec> to store the message in a database.
839 973
840 $ctx->fmt_cb (sub { \@_ }); 974 $ctx->fmt_cb (sub { \@_ });
841 $ctx->log_cb (sub { 975 $ctx->log_cb (sub {
842 my ($msg) = @_; 976 my ($msg) = @_;
843 977
… …
855Sets the C<log_cb> to simply use C<CORE::warn> to report any messages 989Sets the C<log_cb> to simply use C<CORE::warn> to report any messages
856(usually this logs to STDERR). 990(usually this logs to STDERR).
857 991
858=item $ctx->log_to_file ($path) 992=item $ctx->log_to_file ($path)
859 993
860Sets the C<log_cb> to log to a file (by appending), unbuffered. 994Sets the C<log_cb> to log to a file (by appending), unbuffered. The
995function might return before the log file has been opened or created.
861 996
862=item $ctx->log_to_path ($path) 997=item $ctx->log_to_path ($path)
863 998
864Same as C<< ->log_to_file >>, but opens the file for each message. This 999Same 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 1000is much slower, but allows you to change/move/rename/delete the file at
… …
900 warn shift; 1035 warn shift;
901 0 1036 0
902 }); 1037 });
903} 1038}
904 1039
1040# this function is a good example of why threads are a must,
1041# simply for priority inversion.
1042sub _log_to_disk {
1043 # eval'uating this at runtime saves 220kb rss - perl has become
1044 # an insane memory waster.
1045 eval q{ # poor man's autoloading {}
1046 sub _log_to_disk {
1047 my ($ctx, $path, $keepopen) = @_;
1048
1049 my $fh;
1050 my @queue;
1051 my $delay;
1052 my $disable;
1053
1054 use AnyEvent::IO ();
1055
1056 my $kick = sub {
1057 undef $delay;
1058 return unless @queue;
1059 $delay = 1;
1060
1061 # we pass $kick to $kick, so $kick itself doesn't keep a reference to $kick.
1062 my $kick = shift;
1063
1064 # write one or more messages
1065 my $write = sub {
1066 # we write as many messages as have been queued
1067 my $data = join "", @queue;
1068 @queue = ();
1069
1070 AnyEvent::IO::aio_write $fh, $data, sub {
1071 $disable = 1;
1072 @_
1073 ? ($_[0] == length $data or AE::log 4 => "unable to write to logfile '$path': short write")
1074 : AE::log 4 => "unable to write to logfile '$path': $!";
1075 undef $disable;
1076
1077 if ($keepopen) {
1078 $kick->($kick);
1079 } else {
1080 AnyEvent::IO::aio_close ($fh, sub {
1081 undef $fh;
1082 $kick->($kick);
1083 });
1084 }
1085 };
1086 };
1087
1088 if ($fh) {
1089 $write->();
1090 } else {
1091 AnyEvent::IO::aio_open
1092 $path,
1093 AnyEvent::IO::O_CREAT | AnyEvent::IO::O_WRONLY | AnyEvent::IO::O_APPEND,
1094 0666,
1095 sub {
1096 $fh = shift
1097 or do {
1098 $disable = 1;
1099 AE::log 4 => "unable to open logfile '$path': $!";
1100 undef $disable;
1101 return;
1102 };
1103
1104 $write->();
1105 }
1106 ;
1107 }
1108 };
1109
1110 $ctx->log_cb (sub {
1111 return if $disable;
1112 push @queue, shift;
1113 $kick->($kick) unless $delay;
1114 0
1115 });
1116
1117 $kick->($kick) if $keepopen; # initial open
1118 };
1119 };
1120 die if $@;
1121 &_log_to_disk
1122}
1123
905sub log_to_file { 1124sub log_to_file {
906 my ($ctx, $path) = @_; 1125 my ($ctx, $path) = @_;
907 1126
908 open my $fh, ">>", $path 1127 _log_to_disk $ctx, $path, 1;
909 or die "$path: $!";
910
911 $ctx->log_cb (sub {
912 syswrite $fh, shift;
913 0
914 });
915} 1128}
916 1129
917sub log_to_path { 1130sub log_to_path {
918 my ($ctx, $path) = @_; 1131 my ($ctx, $path) = @_;
919 1132
920 $ctx->log_cb (sub { 1133 _log_to_disk $ctx, $path, 0;
921 open my $fh, ">>", $path
922 or die "$path: $!";
923
924 syswrite $fh, shift;
925 0
926 });
927} 1134}
928 1135
929sub log_to_syslog { 1136sub log_to_syslog {
930 my ($ctx, $facility) = @_; 1137 my ($ctx, $facility) = @_;
931 1138
… …
960=over 4 1167=over 4
961 1168
962=item $ctx->log ($level, $msg[, @params]) 1169=item $ctx->log ($level, $msg[, @params])
963 1170
964Same as C<AnyEvent::Log::log>, but uses the given context as log context. 1171Same as C<AnyEvent::Log::log>, but uses the given context as log context.
1172
1173Example: log a message in the context of another package.
1174
1175 (AnyEvent::Log::ctx "Other::Package")->log (warn => "heely bo");
965 1176
966=item $logger = $ctx->logger ($level[, \$enabled]) 1177=item $logger = $ctx->logger ($level[, \$enabled])
967 1178
968Same as C<AnyEvent::Log::logger>, but uses the given context as log 1179Same as C<AnyEvent::Log::logger>, but uses the given context as log
969context. 1180context.
… …
1017 1228
1018Context names starting with a C<%> are anonymous contexts created when the 1229Context names starting with a C<%> are anonymous contexts created when the
1019name is first mentioned. The difference to package contexts is that by 1230name is first mentioned. The difference to package contexts is that by
1020default they have no attached slaves. 1231default they have no attached slaves.
1021 1232
1233This makes it possible to create new log contexts that can be refered to
1234multiple times by name within the same log specification.
1235
1022=item a perl package name 1236=item a perl package name
1023 1237
1024Any other string references the logging context associated with the given 1238Any other string references the logging context associated with the given
1025Perl C<package>. In the unlikely case where you want to specify a package 1239Perl 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 1240context that matches on of the other context name forms, you can add a
… …
1057=item C<nolog> 1271=item C<nolog>
1058 1272
1059Configures the context to not log anything by itself, which is the 1273Configures the context to not log anything by itself, which is the
1060default. Same as C<< $ctx->log_cb (undef) >>. 1274default. Same as C<< $ctx->log_cb (undef) >>.
1061 1275
1276=item C<cap=>I<level>
1277
1278Caps logging messages entering this context at the given level, i.e.
1279reduces the priority of messages with higher priority than this level. The
1280default is C<0> (or C<off>), meaning the priority will not be touched.
1281
1062=item C<0> or C<off> 1282=item C<0> or C<off>
1063 1283
1064Sets the logging level of the context ot C<0>, i.e. all messages will be 1284Sets the logging level of the context to C<0>, i.e. all messages will be
1065filtered out. 1285filtered out.
1066 1286
1067=item C<all> 1287=item C<all>
1068 1288
1069Enables all logging levels, i.e. filtering will effectively be switched 1289Enables all logging levels, i.e. filtering will effectively be switched
… …
1111 1331
1112Attaches the named context as slave to the context. 1332Attaches the named context as slave to the context.
1113 1333
1114=item C<+> 1334=item C<+>
1115 1335
1116A line C<+> detaches all contexts, i.e. clears the slave list from the 1336A lone C<+> detaches all contexts, i.e. clears the slave list from the
1117context. Anonymous (C<%name>) contexts have no attached slaves by default, 1337context. Anonymous (C<%name>) contexts have no attached slaves by default,
1118but package contexts have the parent context as slave by default. 1338but package contexts have the parent context as slave by default.
1119 1339
1120Example: log messages from My::Module to a file, do not send them to the 1340Example: log messages from My::Module to a file, do not send them to the
1121default log collector. 1341default log collector.
… …
1152 1372
1153 my $pkg = sub { 1373 my $pkg = sub {
1154 $_[0] eq "log" ? $LOG 1374 $_[0] eq "log" ? $LOG
1155 : $_[0] eq "filter" ? $FILTER 1375 : $_[0] eq "filter" ? $FILTER
1156 : $_[0] eq "collect" ? $COLLECT 1376 : $_[0] eq "collect" ? $COLLECT
1157 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= ctx undef) 1377 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= do { my $ctx = ctx undef; $ctx->[0] = $_[0]; $ctx })
1158 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/ 1378 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/
1159 : die # never reached? 1379 : die # never reached?
1160 }; 1380 };
1161 1381
1162 /\G[[:space:]]+/gc; # skip initial whitespace 1382 /\G[[:space:]]+/gc; # skip initial whitespace
… …
1168 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) { 1388 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) {
1169 for ("$1") { 1389 for ("$1") {
1170 if ($_ eq "stderr" ) { $ctx->log_to_warn; 1390 if ($_ eq "stderr" ) { $ctx->log_to_warn;
1171 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1"); 1391 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1");
1172 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1"); 1392 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1");
1173 } elsif (/syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog ($1); 1393 } elsif (/^syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog ("$1");
1174 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef); 1394 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef);
1395 } elsif (/^cap=(.+)/ ) { $ctx->cap ("$1");
1175 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1")); 1396 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1"));
1176 } elsif ($_ eq "+" ) { $ctx->slaves; 1397 } elsif ($_ eq "+" ) { $ctx->slaves;
1177 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0); 1398 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0);
1178 } elsif ($_ eq "all" ) { $ctx->level ("all"); 1399 } elsif ($_ eq "all" ) { $ctx->level ("all");
1179 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level"; 1400 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level";
… …
1196 if (/\G(.+)/g) { 1417 if (/\G(.+)/g) {
1197 die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n"; 1418 die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n";
1198 } 1419 }
1199} 1420}
1200 1421
12011;
1202
1203=head1 EXAMPLES 1422=head1 EXAMPLES
1204 1423
1205This section shows some common configurations, both as code, and as 1424This section shows some common configurations, both as code, and as
1206C<PERL_ANYEVENT_LOG> string. 1425C<PERL_ANYEVENT_LOG> string.
1207 1426
… …
1231 1450
1232This writes them only when the global logging level allows it, because 1451This writes them only when the global logging level allows it, because
1233it is attached to the default context which is invoked I<after> global 1452it is attached to the default context which is invoked I<after> global
1234filtering. 1453filtering.
1235 1454
1236 $AnyEvent::Log::FILTER->attach 1455 $AnyEvent::Log::FILTER->attach (
1237 new AnyEvent::Log::Ctx log_to_file => $path); 1456 new AnyEvent::Log::Ctx log_to_file => $path);
1238 1457
1239 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path 1458 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
1240 1459
1241This writes them regardless of the global logging level, because it is 1460This writes them regardless of the global logging level, because it is
… …
1247 1466
1248 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger 1467 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
1249 1468
1250In both cases, messages are still written to STDERR. 1469In both cases, messages are still written to STDERR.
1251 1470
1471=item Additionally log all messages with C<warn> and higher priority to
1472C<syslog>, but cap at C<error>.
1473
1474This logs all messages to the default log target, but also logs messages
1475with priority C<warn> or higher (and not filtered otherwise) to syslog
1476facility C<user>. Messages with priority higher than C<error> will be
1477logged with level C<error>.
1478
1479 $AnyEvent::Log::LOG->attach (
1480 new AnyEvent::Log::Ctx
1481 level => "warn",
1482 cap => "error",
1483 syslog => "user",
1484 );
1485
1486 PERL_ANYEVENT_LOG=log=+%syslog:%syslog=warn,cap=error,syslog
1487
1252=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s). 1488=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s).
1253 1489
1254Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug> 1490Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug>
1255context - this simply circumvents the global filtering for trace messages. 1491context - this simply circumvents the global filtering for trace messages.
1256 1492
… …
1263assumes the log level for AnyEvent::Debug hasn't been changed from the 1499assumes the log level for AnyEvent::Debug hasn't been changed from the
1264default. 1500default.
1265 1501
1266=back 1502=back
1267 1503
1504=head1 ASYNCHRONOUS DISK I/O
1505
1506This module uses L<AnyEvent::IO> to actually write log messages (in
1507C<log_to_file> and C<log_to_path>), so it doesn't block your program when
1508the disk is busy and a non-blocking L<AnyEvent::IO> backend is available.
1509
1268=head1 AUTHOR 1510=head1 AUTHOR
1269 1511
1270 Marc Lehmann <schmorp@schmorp.de> 1512 Marc Lehmann <schmorp@schmorp.de>
1271 http://home.schmorp.de/ 1513 http://anyevent.schmorp.de
1272 1514
1273=cut 1515=cut
1274 1516
15171
1518

Diff Legend

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