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.31 by root, Thu Aug 25 03:08:48 2011 UTC vs.
Revision 1.68 by root, Sun May 12 11:14:13 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
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
22 $tracer->("i am here") if $trace; 40 $tracer->("i am here") if $trace;
23 $tracer->(sub { "lots of data: " . Dumper $self }) if $trace; 41 $tracer->(sub { "lots of data: " . Dumper $self }) if $trace;
24 42
25Configuration (also look at the EXAMPLES section): 43Configuration (also look at the EXAMPLES section):
26 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
27 # set logging for the current package to errors and higher only 50 # set logging for the current package to errors and higher only
28 AnyEvent::Log::ctx->level ("error"); 51 AnyEvent::Log::ctx->level ("error");
29 52
30 # set logging level to suppress anything below "notice" 53 # enable logging for the current package, regardless of global logging level
31 $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);
32 59
33 # send all critical and higher priority messages to syslog, 60 # send all critical and higher priority messages to syslog,
34 # regardless of (most) other settings 61 # regardless of (most) other settings
35 $AnyEvent::Log::COLLECT->attach (new AnyEvent::Log::Ctx 62 $AnyEvent::Log::COLLECT->attach (new AnyEvent::Log::Ctx
36 level => "critical", 63 level => "critical",
37 log_to_syslog => 0, 64 log_to_syslog => "user",
38 ); 65 );
39 66
40=head1 DESCRIPTION 67=head1 DESCRIPTION
41 68
42This module implements a relatively simple "logging framework". It doesn't 69This module implements a relatively simple "logging framework". It doesn't
43attempt to be "the" logging solution or even "a" logging solution for 70attempt to be "the" logging solution or even "a" logging solution for
44AnyEvent - AnyEvent simply creates logging messages internally, and this 71AnyEvent - AnyEvent simply creates logging messages internally, and this
45module 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
46using it from other modules as well. 73using it from other modules as well.
47 74
48Remember 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
49will be logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number 76errors and more important messages will be logged, unless you set
50before starting your program, or change the logging level at runtime with 77C<PERL_ANYEVENT_VERBOSE> to a higher number before starting your program
51something like: 78(C<AE_VERBOSE=5> is recommended during development), or change the logging
79level at runtime with something like:
52 80
53 use AnyEvent::Log; 81 use AnyEvent::Log;
54 AnyEvent::Log::FILTER->level ("info"); 82 $AnyEvent::Log::FILTER->level ("info");
55 83
56The 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),
57but make it powerful enough to be potentially useful for any module, and 85but make it powerful enough to be potentially useful for any module,
58extensive enough for the most common tasks, such as logging to multiple 86and extensive enough for the most common tasks, such as logging to
59targets, or being able to log into a database. 87multiple targets, or being able to log into a database.
60 88
89The module is also usable before AnyEvent itself is initialised, in which
90case some of the functionality might be reduced.
91
61The amount of documentation might indicate otherwise, but the module is 92The amount of documentation might indicate otherwise, but the runtime part
62still just below 300 lines of code. 93of the module is still just below 300 lines of code.
63 94
64=head1 LOGGING LEVELS 95=head1 LOGGING LEVELS
65 96
66Logging levels in this module range from C<1> (highest priority) to C<9> 97Logging levels in this module range from C<1> (highest priority) to C<9>
67(lowest priority). Note that the lowest numerical value is the highest 98(lowest priority). Note that the lowest numerical value is the highest
… …
69numerical value". 100numerical value".
70 101
71Instead 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:
72 103
73 LVL NAME SYSLOG PERL NOTE 104 LVL NAME SYSLOG PERL NOTE
74 1 fatal emerg exit aborts program! 105 1 fatal emerg exit system unusable, aborts program!
75 2 alert 106 2 alert failure in primary system
76 3 critical crit 107 3 critical crit failure in backup system
77 4 error err die 108 4 error err die non-urgent program errors, a bug
78 5 warn warning 109 5 warn warning possible problem, not necessarily error
79 6 note notice 110 6 note notice unusual conditions
80 7 info 111 7 info normal messages, no action required
81 8 debug 112 8 debug debugging messages for development
82 9 trace 113 9 trace copious tracing output
83 114
84As 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
85is 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)
86and the third one the "perl" name, suggesting that you log C<die> messages 117and the third one the "perl" name, suggesting (only!) that you log C<die>
87at C<error> priority. 118messages at C<error> priority. The NOTE column tries to provide some
119rationale on how to chose a logging level.
88 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
89You 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>,
90(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
91program - 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.
92 133
93Some 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>
94or C<all> - these are only valid in the methods they are documented for. 135or C<all> - these are only valid for the methods that documented them.
95 136
96=head1 LOGGING FUNCTIONS 137=head1 LOGGING FUNCTIONS
97 138
98These functions allow you to log messages. They always use the caller's 139The following functions allow you to log messages. They always use the
99package as a "logging context". Also, the main logging function C<log> is 140caller's package as a "logging context". Also, the main logging function,
100callable as C<AnyEvent::log> or C<AE::log> when the C<AnyEvent> module is 141C<log>, is aliased to C<AnyEvent::log> and C<AE::log> when the C<AnyEvent>
101loaded. 142module is loaded.
102 143
103=over 4 144=over 4
104 145
105=cut 146=cut
106 147
107package AnyEvent::Log; 148package AnyEvent::Log;
108 149
109use Carp (); 150use Carp ();
110use POSIX (); 151use POSIX ();
111 152
153# layout of a context
154# 0 1 2 3 4, 5
155# [$title, $level, %$slaves, &$logcb, &$fmtcb, $cap]
156
112use AnyEvent (); BEGIN { AnyEvent::common_sense } 157use AnyEvent (); BEGIN { AnyEvent::common_sense }
113use AnyEvent::Util (); 158#use AnyEvent::Util (); need to load this in a delayed fashion, as it uses AE::log
114 159
115our $VERSION = $AnyEvent::VERSION; 160our $VERSION = $AnyEvent::VERSION;
116 161
117our ($COLLECT, $FILTER, $LOG); 162our ($COLLECT, $FILTER, $LOG);
118 163
119our ($now_int, $now_str1, $now_str2); 164our ($now_int, $now_str1, $now_str2);
120 165
121# Format Time, not public - yet? 166# Format Time, not public - yet?
122sub ft($) { 167sub format_time($) {
123 my $i = int $_[0]; 168 my $i = int $_[0];
124 my $f = sprintf "%06d", 1e6 * ($_[0] - $i); 169 my $f = sprintf "%06d", 1e6 * ($_[0] - $i);
125 170
126 ($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)
127 if $now_int != $i; 172 if $now_int != $i;
… …
148=item AnyEvent::Log::log $level, $msg[, @args] 193=item AnyEvent::Log::log $level, $msg[, @args]
149 194
150Requests logging of the given C<$msg> with the given log level, and 195Requests logging of the given C<$msg> with the given log level, and
151returns true if the message was logged I<somewhere>. 196returns true if the message was logged I<somewhere>.
152 197
153For C<fatal> log levels, the program will abort. 198For loglevel C<fatal>, the program will abort.
154 199
155If only a C<$msg> is given, it is logged as-is. With extra C<@args>, the 200If only a C<$msg> is given, it is logged as-is. With extra C<@args>, the
156C<$msg> is interpreted as an sprintf format string. 201C<$msg> is interpreted as an sprintf format string.
157 202
158The C<$msg> should not end with C<\n>, but may if that is convenient for 203The C<$msg> should not end with C<\n>, but may if that is convenient for
… …
160 205
161Last 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
162supposed 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
163actually 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
164message 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.
165 213
166Whether 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
167and 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
168messages or not "lost" - for example, when L<AnyEvent::Debug> detects a 216messages or not "lost" - for example, when L<AnyEvent::Debug> detects a
169runtime error it tries to log it at C<die> level, but if that message is 217runtime error it tries to log it at C<die> level, but if that message is
… …
203 info => 7, 251 info => 7,
204 debug => 8, 252 debug => 8,
205 trace => 9, 253 trace => 9,
206); 254);
207 255
208sub now () { time } 256our $TIME_EXACT;
257
258sub exact_time($) {
259 $TIME_EXACT = shift;
260 *_ts = $AnyEvent::MODEL
261 ? $TIME_EXACT ? \&AE::now : \&AE::time
262 : sub () { $TIME_EXACT ? do { require Time::HiRes; Time::HiRes::time () } : time };
263}
264
265BEGIN {
266 exact_time 0;
267}
209 268
210AnyEvent::post_detect { 269AnyEvent::post_detect {
211 *now = \&AE::now; 270 exact_time $TIME_EXACT;
212}; 271};
213 272
214our @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);
215 274
216# time, ctx, level, msg 275# time, ctx, level, msg
217sub _format($$$$) { 276sub default_format($$$$) {
218 my $ts = ft $_[0]; 277 my $ts = format_time $_[0];
219 my $ct = " "; 278 my $ct = " ";
220 279
221 my @res; 280 my @res;
222 281
223 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]) {
… …
226 } 285 }
227 286
228 join "", @res 287 join "", @res
229} 288}
230 289
290sub fatal_exit() {
291 exit 1;
292}
293
231sub _log { 294sub _log {
232 my ($ctx, $level, $format, @args) = @_; 295 my ($ctx, $level, $format, @args) = @_;
233 296
234 $level = $level > 0 && $level <= 9 297 $level = $level > 0 && $level <= 9
235 ? $level+0 298 ? $level+0
236 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught"; 299 : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught";
237 300
238 my $mask = 1 << $level; 301 my $mask = 1 << $level;
239 302
240 my ($success, %seen, @ctx, $now, $fmt); 303 my ($success, %seen, @ctx, $now, @fmt);
241 304
242 do 305 do
243 { 306 {
244 # skip if masked 307 # if !ref, then it's a level number
308 if (!ref $ctx) {
309 $level = $ctx;
245 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
246 if ($ctx->[3]) { 320 if ($ctx->[3]) {
247 # logging target found 321 # logging target found
322
323 local ($!, $@);
248 324
249 # now get raw message, unless we have it already 325 # now get raw message, unless we have it already
250 unless ($now) { 326 unless ($now) {
251 $format = $format->() if ref $format; 327 $format = $format->() if ref $format;
252 $format = sprintf $format, @args if @args; 328 $format = sprintf $format, @args if @args;
253 $format =~ s/\n$//; 329 $format =~ s/\n$//;
254 $now = now; 330 $now = _ts;
255 }; 331 };
256 332
257 # format msg 333 # format msg
258 my $str = $ctx->[4] 334 my $str = $ctx->[4]
259 ? $ctx->[4]($now, $_[0], $level, $format) 335 ? $ctx->[4]($now, $_[0], $level, $format)
260 : ($fmt ||= _format $now, $_[0], $level, $format); 336 : ($fmt[$level] ||= default_format $now, $_[0], $level, $format);
261 337
262 $success = 1; 338 $success = 1;
263 339
264 $ctx->[3]($str) 340 $ctx->[3]($str)
265 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate 341 or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate
… …
268 } 344 }
269 } 345 }
270 } 346 }
271 while $ctx = pop @ctx; 347 while $ctx = pop @ctx;
272 348
273 exit 1 if $level <= 1; 349 fatal_exit if $level <= 1;
274 350
275 $success 351 $success
276} 352}
277 353
278sub log($$;@) { 354sub log($$;@) {
279 _log 355 _log
280 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 356 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
281 @_; 357 @_;
282} 358}
283 359
284*AnyEvent::log = *AE::log = \&log;
285
286=item $logger = AnyEvent::Log::logger $level[, \$enabled] 360=item $logger = AnyEvent::Log::logger $level[, \$enabled]
287 361
288Creates a code reference that, when called, acts as if the 362Creates a code reference that, when called, acts as if the
289C<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
290level. 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
… …
354 428
355 $LOGGER{$logger+0} = $logger; 429 $LOGGER{$logger+0} = $logger;
356 430
357 _reassess $logger+0; 431 _reassess $logger+0;
358 432
433 require AnyEvent::Util unless $AnyEvent::Util::VERSION;
359 my $guard = AnyEvent::Util::guard { 434 my $guard = AnyEvent::Util::guard (sub {
360 # "clean up" 435 # "clean up"
361 delete $LOGGER{$logger+0}; 436 delete $LOGGER{$logger+0};
362 }; 437 });
363 438
364 sub { 439 sub {
365 $guard if 0; # keep guard alive, but don't cause runtime overhead 440 $guard if 0; # keep guard alive, but don't cause runtime overhead
366 441
367 _log $ctx, $level, @_ 442 _log $ctx, $level, @_
… …
372sub logger($;$) { 447sub logger($;$) {
373 _logger 448 _logger
374 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0], 449 $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
375 @_ 450 @_
376} 451}
452
453=item AnyEvent::Log::exact_time $on
454
455By default, C<AnyEvent::Log> will use C<AE::now>, i.e. the cached
456eventloop time, for the log timestamps. After calling this function with a
457true value it will instead resort to C<AE::time>, i.e. fetch the current
458time on each log message. This only makes a difference for event loops
459that actually cache the time (such as L<EV> or L<AnyEvent::Loop>).
460
461This setting can be changed at any time by calling this function.
462
463Since C<AnyEvent::Log> has to work even before the L<AnyEvent> has been
464initialised, this switch will also decide whether to use C<CORE::time> or
465C<Time::HiRes::time> when logging a message before L<AnyEvent> becomes
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.
377 502
378=back 503=back
379 504
380=head1 LOGGING CONTEXTS 505=head1 LOGGING CONTEXTS
381 506
… …
469 594
470=item $ctx = AnyEvent::Log::ctx [$pkg] 595=item $ctx = AnyEvent::Log::ctx [$pkg]
471 596
472This function creates or returns a logging context (which is an object). 597This function creates or returns a logging context (which is an object).
473 598
474If 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
475returned. 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
476callers 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
477would use). 602would use).
478 603
479If 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
… …
501This 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
502configuration, reset all contexts. 627configuration, reset all contexts.
503 628
504=cut 629=cut
505 630
631our $ORIG_VERBOSE = $AnyEvent::VERBOSE;
632$AnyEvent::VERBOSE = 9;
633
506sub reset { 634sub reset {
507 # hard to kill complex data structures 635 # hard to kill complex data structures
508 # we "recreate" all package loggers and reset the hierarchy 636 # we "recreate" all package loggers and reset the hierarchy
509 while (my ($k, $v) = each %CTX) { 637 while (my ($k, $v) = each %CTX) {
510 @$v = ($k, (1 << 10) - 1 - 1, { }); 638 @$v = ($k, (1 << 10) - 1 - 1, { });
… …
513 } 641 }
514 642
515 @$_ = ($_->[0], (1 << 10) - 1 - 1) 643 @$_ = ($_->[0], (1 << 10) - 1 - 1)
516 for $LOG, $FILTER, $COLLECT; 644 for $LOG, $FILTER, $COLLECT;
517 645
518 $LOG->slaves; 646 #$LOG->slaves;
519 $LOG->title ('$AnyEvent::Log::LOG'); 647 $LOG->title ('$AnyEvent::Log::LOG');
520 $LOG->log_to_warn; 648 $LOG->log_to_warn;
521 649
522 $FILTER->slaves ($LOG); 650 $FILTER->slaves ($LOG);
523 $FILTER->title ('$AnyEvent::Log::FILTER'); 651 $FILTER->title ('$AnyEvent::Log::FILTER');
524 $FILTER->level ($AnyEvent::VERBOSE); 652 $FILTER->level ($ORIG_VERBOSE);
525 653
526 $COLLECT->slaves ($FILTER); 654 $COLLECT->slaves ($FILTER);
527 $COLLECT->title ('$AnyEvent::Log::COLLECT'); 655 $COLLECT->title ('$AnyEvent::Log::COLLECT');
528 656
529 _reassess; 657 _reassess;
530} 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;
531 667
532# create the default logger contexts 668# create the default logger contexts
533$LOG = ctx undef; 669$LOG = ctx undef;
534$FILTER = ctx undef; 670$FILTER = ctx undef;
535$COLLECT = ctx undef; 671$COLLECT = ctx undef;
… …
544package AnyEvent::Log::COLLECT; 680package AnyEvent::Log::COLLECT;
545package AE::Log::COLLECT; 681package AE::Log::COLLECT;
546 682
547package AnyEvent::Log::Ctx; 683package AnyEvent::Log::Ctx;
548 684
549# 0 1 2 3 4
550# [$title, $level, %$slaves, &$logcb, &$fmtcb]
551
552=item $ctx = new AnyEvent::Log::Ctx methodname => param... 685=item $ctx = new AnyEvent::Log::Ctx methodname => param...
553 686
554This is a convenience constructor that makes it simpler to construct 687This is a convenience constructor that makes it simpler to construct
555anonymous logging contexts. 688anonymous logging contexts.
556 689
… …
643 776
644=item $ctx->disable ($level[, $level...]) 777=item $ctx->disable ($level[, $level...])
645 778
646Disables logging for the given levels, leaving all others unchanged. 779Disables logging for the given levels, leaving all others unchanged.
647 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
648=cut 803=cut
649 804
650sub _lvl_lst { 805sub _lvl_lst {
651 map { 806 map {
652 $_ > 0 && $_ <= 9 ? $_+0 807 $_ > 0 && $_ <= 9 ? $_+0
653 : $_ eq "all" ? (1 .. 9) 808 : $_ eq "all" ? (1 .. 9)
654 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught" 809 : $STR2LEVEL{$_} || Carp::croak "$_: not a valid logging level, caught"
655 } @_ 810 } @_
656} 811}
657 812
813sub _lvl {
814 $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1]
815}
816
658our $NOP_CB = sub { 0 }; 817our $NOP_CB = sub { 0 };
659 818
660sub levels { 819sub levels {
661 my $ctx = shift; 820 my $ctx = shift;
662 $ctx->[1] = 0; 821 $ctx->[1] = 0;
… …
665 AnyEvent::Log::_reassess; 824 AnyEvent::Log::_reassess;
666} 825}
667 826
668sub level { 827sub level {
669 my $ctx = shift; 828 my $ctx = shift;
670 my $lvl = $_[0] =~ /^(?:0|off|none)$/ ? 0 : (_lvl_lst $_[0])[-1];
671
672 $ctx->[1] = ((1 << $lvl) - 1) << 1; 829 $ctx->[1] = ((1 << &_lvl) - 1) << 1;
673 AnyEvent::Log::_reassess; 830 AnyEvent::Log::_reassess;
674} 831}
675 832
676sub enable { 833sub enable {
677 my $ctx = shift; 834 my $ctx = shift;
… …
685 $ctx->[1] &= ~(1 << $_) 842 $ctx->[1] &= ~(1 << $_)
686 for &_lvl_lst; 843 for &_lvl_lst;
687 AnyEvent::Log::_reassess; 844 AnyEvent::Log::_reassess;
688} 845}
689 846
847sub cap {
848 my $ctx = shift;
849 $ctx->[5] = &_lvl;
850}
851
690=back 852=back
691 853
692=head3 SLAVE CONTEXTS 854=head3 SLAVE CONTEXTS
693 855
694The following methods attach and detach another logging context to a 856The following methods attach and detach another logging context to a
… …
722sub attach { 884sub attach {
723 my $ctx = shift; 885 my $ctx = shift;
724 886
725 $ctx->[2]{$_+0} = $_ 887 $ctx->[2]{$_+0} = $_
726 for map { AnyEvent::Log::ctx $_ } @_; 888 for map { AnyEvent::Log::ctx $_ } @_;
889 AnyEvent::Log::_reassess;
727} 890}
728 891
729sub detach { 892sub detach {
730 my $ctx = shift; 893 my $ctx = shift;
731 894
732 delete $ctx->[2]{$_+0} 895 delete $ctx->[2]{$_+0}
733 for map { AnyEvent::Log::ctx $_ } @_; 896 for map { AnyEvent::Log::ctx $_ } @_;
897 AnyEvent::Log::_reassess;
734} 898}
735 899
736sub slaves { 900sub slaves {
737 undef $_[0][2]; 901 undef $_[0][2];
738 &attach; 902 &attach;
903 AnyEvent::Log::_reassess;
739} 904}
740 905
741=back 906=back
742 907
743=head3 LOG TARGETS 908=head3 LOG TARGETS
… …
746the logging (which consists of formatting the message and printing it or 911the logging (which consists of formatting the message and printing it or
747whatever it wants to do with it). 912whatever it wants to do with it).
748 913
749=over 4 914=over 4
750 915
751=item $ctx->log_cb ($cb->($str) 916=item $ctx->log_cb ($cb->($str))
752 917
753Replaces the logging callback on the context (C<undef> disables the 918Replaces the logging callback on the context (C<undef> disables the
754logging callback). 919logging callback).
755 920
756The logging callback is responsible for handling formatted log messages 921The logging callback is responsible for handling formatted log messages
… …
781 946
782Replaces the formatting callback on the context (C<undef> restores the 947Replaces the formatting callback on the context (C<undef> restores the
783default formatter). 948default formatter).
784 949
785The callback is passed the (possibly fractional) timestamp, the original 950The callback is passed the (possibly fractional) timestamp, the original
786logging context, the (numeric) logging level and the raw message string 951logging context (object, not title), the (numeric) logging level and
787and 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
788string, 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
789the values. 954reference that just stores the values.
790 955
791If, 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
792logger 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
793inside the C<AnyEvent::Log> package. 958inside the C<AnyEvent::Log> package.
794 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
795Example: format just the raw message, with numeric log level in angle 974Example: format just the raw message, with numeric log level in angle
796brackets. 975brackets.
797 976
798 $ctx->fmt_cb (sub { 977 $ctx->fmt_cb (sub {
799 my ($time, $ctx, $lvl, $msg) = @_; 978 my ($time, $ctx, $lvl, $msg) = @_;
800 979
801 "<$lvl>$msg\n" 980 "<$lvl>$msg\n"
802 }); 981 });
803 982
804Example: return an array reference with just the log values, and use 983Example: return an array reference with just the log values, and use
805C<PApp::SQL::sql_exec> to store the emssage in a database. 984C<PApp::SQL::sql_exec> to store the message in a database.
806 985
807 $ctx->fmt_cb (sub { \@_ }); 986 $ctx->fmt_cb (sub { \@_ });
808 $ctx->log_cb (sub { 987 $ctx->log_cb (sub {
809 my ($msg) = @_; 988 my ($msg) = @_;
810 989
… …
822Sets 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
823(usually this logs to STDERR). 1002(usually this logs to STDERR).
824 1003
825=item $ctx->log_to_file ($path) 1004=item $ctx->log_to_file ($path)
826 1005
827Sets 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.
828 1008
829=item $ctx->log_to_path ($path) 1009=item $ctx->log_to_path ($path)
830 1010
831Same 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
832is 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
… …
834 1014
835Needless(?) to say, if you do not want to be bitten by some evil person 1015Needless(?) to say, if you do not want to be bitten by some evil person
836calling C<chdir>, the path should be absolute. Doesn't help with 1016calling C<chdir>, the path should be absolute. Doesn't help with
837C<chroot>, but hey... 1017C<chroot>, but hey...
838 1018
839=item $ctx->log_to_syslog ([$log_flags]) 1019=item $ctx->log_to_syslog ([$facility])
840 1020
841Logs all messages via L<Sys::Syslog>, mapping C<trace> to C<debug> and all 1021Logs all messages via L<Sys::Syslog>, mapping C<trace> to C<debug> and
842the others in the obvious way. If specified, then the C<$log_flags> are 1022all the others in the obvious way. If specified, then the C<$facility> is
843simply or'ed onto the priority argument and can contain any C<LOG_xxx> 1023used as the facility (C<user>, C<auth>, C<local0> and so on). The default
844flags valid for Sys::Syslog::syslog, except for the priority levels. 1024facility is C<user>.
845 1025
846Note that this function also sets a C<fmt_cb> - the logging part requires 1026Note that this function also sets a C<fmt_cb> - the logging part requires
847an array reference with [$level, $str] as input. 1027an array reference with [$level, $str] as input.
848 1028
849=cut 1029=cut
… …
867 warn shift; 1047 warn shift;
868 0 1048 0
869 }); 1049 });
870} 1050}
871 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
872sub log_to_file { 1136sub log_to_file {
873 my ($ctx, $path) = @_; 1137 my ($ctx, $path) = @_;
874 1138
875 open my $fh, ">>", $path 1139 _log_to_disk $ctx, $path, 1;
876 or die "$path: $!";
877
878 $ctx->log_cb (sub {
879 syswrite $fh, shift;
880 0
881 });
882} 1140}
883 1141
884sub log_to_path { 1142sub log_to_path {
885 my ($ctx, $path) = @_; 1143 my ($ctx, $path) = @_;
886 1144
887 $ctx->log_cb (sub { 1145 _log_to_disk $ctx, $path, 0;
888 open my $fh, ">>", $path
889 or die "$path: $!";
890
891 syswrite $fh, shift;
892 0
893 });
894} 1146}
895 1147
896sub log_to_syslog { 1148sub log_to_syslog {
897 my ($ctx, $flags) = @_; 1149 my ($ctx, $facility) = @_;
898 1150
899 require Sys::Syslog; 1151 require Sys::Syslog;
900 1152
901 $ctx->fmt_cb (sub { 1153 $ctx->fmt_cb (sub {
902 my $str = $_[3]; 1154 my $str = $_[3];
903 $str =~ s/\n(?=.)/\n+ /g; 1155 $str =~ s/\n(?=.)/\n+ /g;
904 1156
905 [$_[2], "($_[1][0]) $str"] 1157 [$_[2], "($_[1][0]) $str"]
906 }); 1158 });
907 1159
1160 $facility ||= "user";
1161
908 $ctx->log_cb (sub { 1162 $ctx->log_cb (sub {
909 my $lvl = $_[0][0] < 9 ? $_[0][0] : 8; 1163 my $lvl = $_[0][0] < 9 ? $_[0][0] : 8;
910 1164
911 Sys::Syslog::syslog ($flags | ($lvl - 1), $_) 1165 Sys::Syslog::syslog ("$facility|" . ($lvl - 1), $_)
912 for split /\n/, $_[0][1]; 1166 for split /\n/, $_[0][1];
913 1167
914 0 1168 0
915 }); 1169 });
916} 1170}
… …
925=over 4 1179=over 4
926 1180
927=item $ctx->log ($level, $msg[, @params]) 1181=item $ctx->log ($level, $msg[, @params])
928 1182
929Same 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");
930 1188
931=item $logger = $ctx->logger ($level[, \$enabled]) 1189=item $logger = $ctx->logger ($level[, \$enabled])
932 1190
933Same 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
934context. 1192context.
… …
982 1240
983Context names starting with a C<%> are anonymous contexts created when the 1241Context names starting with a C<%> are anonymous contexts created when the
984name is first mentioned. The difference to package contexts is that by 1242name is first mentioned. The difference to package contexts is that by
985default they have no attached slaves. 1243default they have no attached slaves.
986 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
987=item a perl package name 1248=item a perl package name
988 1249
989Any other string references the logging context associated with the given 1250Any other string references the logging context associated with the given
990Perl 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
991context 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
… …
1012Configures the context to log to a file with the given path. Works like 1273Configures the context to log to a file with the given path. Works like
1013C<log_to_path>. 1274C<log_to_path>.
1014 1275
1015=item C<syslog> or C<syslog=>I<expr> 1276=item C<syslog> or C<syslog=>I<expr>
1016 1277
1017Configured the context to log to syslog. If I<expr> is given, then it is 1278Configures the context to log to syslog. If I<expr> is given, then it is
1018evaluated in the L<Sys::Syslog> package, so you could use: 1279evaluated in the L<Sys::Syslog> package, so you could use:
1019 1280
1020 log=syslog=LOG_LOCAL0 1281 log=syslog=LOG_LOCAL0
1021 1282
1022=item C<nolog> 1283=item C<nolog>
1023 1284
1024Configures the context to not log anything by itself, which is the 1285Configures the context to not log anything by itself, which is the
1025default. Same as C<< $ctx->log_cb (undef) >>. 1286default. Same as C<< $ctx->log_cb (undef) >>.
1026 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
1027=item C<0> or C<off> 1294=item C<0> or C<off>
1028 1295
1029Sets 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
1030filtered out. 1297filtered out.
1031 1298
1032=item C<all> 1299=item C<all>
1033 1300
1034Enables all logging levels, i.e. filtering will effectively be switched 1301Enables all logging levels, i.e. filtering will effectively be switched
… …
1064 filter=warn 1331 filter=warn
1065 1332
1066 # or, more verbose 1333 # or, more verbose
1067 filter=only,level,warn 1334 filter=only,level,warn
1068 1335
1069=item C<1>..C<9>, a logging level name (C<error>, C<debug> etc.) 1336=item C<1>..C<9> or a logging level name (C<error>, C<debug> etc.)
1070 1337
1071A numeric loglevel or the name of a loglevel will be interpreted according 1338A numeric loglevel or the name of a loglevel will be interpreted according
1072to the most recent C<only>, C<except> or C<level> directive. By default, 1339to the most recent C<only>, C<except> or C<level> directive. By default,
1073specifying a logging level enables that and any higher priority messages. 1340specifying a logging level enables that and any higher priority messages.
1074 1341
1075=item C<+>I<context> 1342=item C<+>I<context>
1076 1343
1077Adds/attaches the named context as slave to the context. 1344Attaches the named context as slave to the context.
1078 1345
1079=item C<+> 1346=item C<+>
1080 1347
1081A line C<+> clears the slave list form the context. Anonymous (C<%name>) 1348A lone C<+> detaches all contexts, i.e. clears the slave list from the
1082contexts have no slaves by default, but package contexts have the parent 1349context. Anonymous (C<%name>) contexts have no attached slaves by default,
1083context as slave by default. 1350but package contexts have the parent context as slave by default.
1084 1351
1085Example: 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
1086default log collector. 1353default log collector.
1087 1354
1088 My::Module=+,file=/tmp/mymodulelog 1355 My::Module=+,file=/tmp/mymodulelog
1089 1356
1090=back 1357=back
1091 1358
1092Any character can be escaped by prefixing it with a C<\> (backslash), as 1359Any character can be escaped by prefixing it with a C<\> (backslash), as
1093usual, so to log to a file containing a comma, colon, backslash and space in the 1360usual, so to log to a file containing a comma, colon, backslash and some
1094filename, you would do this: 1361spaces in the filename, you would do this:
1095 1362
1096 PERL_ANYEVENT_LOG='log=file=/some\ \:file\ with\,\ \\-escapes' 1363 PERL_ANYEVENT_LOG='log=file=/some\ \:file\ with\,\ \\-escapes'
1097 1364
1098Since whitespace (which includes newlines) is allowed, it is fine to 1365Since whitespace (which includes newlines) is allowed, it is fine to
1099specify multiple lines in C<PERL_ANYEVENT_LOG>, e.g.: 1366specify multiple lines in C<PERL_ANYEVENT_LOG>, e.g.:
… …
1117 1384
1118 my $pkg = sub { 1385 my $pkg = sub {
1119 $_[0] eq "log" ? $LOG 1386 $_[0] eq "log" ? $LOG
1120 : $_[0] eq "filter" ? $FILTER 1387 : $_[0] eq "filter" ? $FILTER
1121 : $_[0] eq "collect" ? $COLLECT 1388 : $_[0] eq "collect" ? $COLLECT
1122 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= ctx undef) 1389 : $_[0] =~ /^%(.+)$/ ? ($anon{$1} ||= do { my $ctx = ctx undef; $ctx->[0] = $_[0]; $ctx })
1123 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/ 1390 : $_[0] =~ /^(.*?)(?:::)?$/ ? ctx "$1" # egad :/
1124 : die # never reached? 1391 : die # never reached?
1125 }; 1392 };
1126 1393
1127 /\G[[:space:]]+/gc; # skip initial whitespace 1394 /\G[[:space:]]+/gc; # skip initial whitespace
… …
1133 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) { 1400 while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) {
1134 for ("$1") { 1401 for ("$1") {
1135 if ($_ eq "stderr" ) { $ctx->log_to_warn; 1402 if ($_ eq "stderr" ) { $ctx->log_to_warn;
1136 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1"); 1403 } elsif (/^file=(.+)/ ) { $ctx->log_to_file ("$1");
1137 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1"); 1404 } elsif (/^path=(.+)/ ) { $ctx->log_to_path ("$1");
1138 } elsif (/syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog (eval "package Sys::Syslog; $1"); 1405 } elsif (/^syslog(?:=(.*))?/ ) { require Sys::Syslog; $ctx->log_to_syslog ("$1");
1139 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef); 1406 } elsif ($_ eq "nolog" ) { $ctx->log_cb (undef);
1407 } elsif (/^cap=(.+)/ ) { $ctx->cap ("$1");
1140 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1")); 1408 } elsif (/^\+(.+)$/ ) { $ctx->attach ($pkg->("$1"));
1141 } elsif ($_ eq "+" ) { $ctx->slaves; 1409 } elsif ($_ eq "+" ) { $ctx->slaves;
1142 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0); 1410 } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0);
1143 } elsif ($_ eq "all" ) { $ctx->level ("all"); 1411 } elsif ($_ eq "all" ) { $ctx->level ("all");
1144 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level"; 1412 } elsif ($_ eq "level" ) { $ctx->level ("all"); $level = "level";
… …
1161 if (/\G(.+)/g) { 1429 if (/\G(.+)/g) {
1162 die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n"; 1430 die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n";
1163 } 1431 }
1164} 1432}
1165 1433
11661;
1167
1168=head1 EXAMPLES 1434=head1 EXAMPLES
1169 1435
1170This section shows some common configurations, both as code, and as 1436This section shows some common configurations, both as code, and as
1171C<PERL_ANYEVENT_LOG> string. 1437C<PERL_ANYEVENT_LOG> string.
1172 1438
… …
1196 1462
1197This writes them only when the global logging level allows it, because 1463This writes them only when the global logging level allows it, because
1198it 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
1199filtering. 1465filtering.
1200 1466
1201 $AnyEvent::Log::FILTER->attach 1467 $AnyEvent::Log::FILTER->attach (
1202 new AnyEvent::Log::Ctx log_to_file => $path); 1468 new AnyEvent::Log::Ctx log_to_file => $path);
1203 1469
1204 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path 1470 PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
1205 1471
1206This writes them regardless of the global logging level, because it is 1472This writes them regardless of the global logging level, because it is
… …
1212 1478
1213 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger 1479 PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
1214 1480
1215In both cases, messages are still written to STDERR. 1481In both cases, messages are still written to STDERR.
1216 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
1217=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).
1218 1501
1219Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug> 1502Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug>
1220context - this simply circumvents the global filtering for trace messages. 1503context - this simply circumvents the global filtering for trace messages.
1221 1504
… …
1228assumes 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
1229default. 1512default.
1230 1513
1231=back 1514=back
1232 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
1233=head1 AUTHOR 1522=head1 AUTHOR
1234 1523
1235 Marc Lehmann <schmorp@schmorp.de> 1524 Marc Lehmann <schmorp@schmorp.de>
1236 http://home.schmorp.de/ 1525 http://anyevent.schmorp.de
1237 1526
1238=cut 1527=cut
1239 1528
15291
1530

Diff Legend

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