… | |
… | |
377 | They have exactly one parent - the context of the "parent" package. The |
377 | They have exactly one parent - the context of the "parent" package. The |
378 | parent package is simply defined to be the package name without the last |
378 | parent package is simply defined to be the package name without the last |
379 | component, i.e. C<AnyEvent::Debug::Wrapped> becomes C<AnyEvent::Debug>, |
379 | component, i.e. C<AnyEvent::Debug::Wrapped> becomes C<AnyEvent::Debug>, |
380 | and C<AnyEvent> becomes ... C<AnyEvent::Log::Top> which is the |
380 | and C<AnyEvent> becomes ... C<AnyEvent::Log::Top> which is the |
381 | exception of the rule - just like the parent of any package name in |
381 | exception of the rule - just like the parent of any package name in |
382 | Perl is C<main>, the default parent of any toplevel package context is |
382 | Perl is C<main>, the default parent of any top-level package context is |
383 | C<AnyEvent::Log::Top>. |
383 | C<AnyEvent::Log::Top>. |
384 | |
384 | |
385 | Since perl packages form only an approximate hierarchy, this parent |
385 | Since perl packages form only an approximate hierarchy, this parent |
386 | context can of course be removed. |
386 | context can of course be removed. |
387 | |
387 | |
388 | All other (anonymous) contexts have no parents and an empty title by |
388 | All other (anonymous) contexts have no parents and an empty title by |
389 | default. |
389 | default. |
390 | |
390 | |
391 | When the module is loaded it creates the default context called |
391 | When the module is loaded it creates the default context called |
392 | C<AnyEvent::Log::Default>, which simply logs everything to STDERR and |
392 | C<AnyEvent::Log::Default> (also stored in C<$AnyEvent::Log::Default>), |
393 | doesn't propagate anything anywhere by default. The purpose of the default |
393 | which simply logs everything to STDERR and doesn't propagate anything |
394 | context is to provide a convenient place to override the global logging |
394 | anywhere by default. The purpose of the default context is to provide |
|
|
395 | a convenient place to override the global logging target or to attach |
395 | target or to attach additional log targets. It's not meant for filtering. |
396 | additional log targets. It's not meant for filtering. |
396 | |
397 | |
397 | It then creates the root context called C<AnyEvent::Log::Root> and |
398 | It then creates the root context called C<AnyEvent::Log::Root> (also |
398 | sets its log level set to all levels up to the one specified by |
399 | stored in C<$AnyEvent::Log::Root>) and sets its log level set to all |
399 | C<$ENV{PERL_ANYEVENT_VERBOSE}>. It then attached the default logging |
400 | levels up to the one specified by C<$ENV{PERL_ANYEVENT_VERBOSE}>. It |
400 | context to it. The purpose of the root context is to simply provide |
401 | then attached the default logging context to it. The purpose of the root |
401 | filtering according to some global log level. |
402 | context is to simply provide filtering according to some global log level. |
402 | |
403 | |
403 | Finally it creates the toplevel package context called |
404 | Finally it creates the top-level package context called |
|
|
405 | C<AnyEvent::Log::Top> (also stored in, you might have guessed, |
404 | C<AnyEvent::Log::Top> and attached the root context but otherwise leaves |
406 | C<$AnyEvent::Log::Top>) and attached the root context but otherwise leaves |
405 | it at default config. It's purpose is simply to collect all log messages |
407 | it at default config. It's purpose is simply to collect all log messages |
406 | system-wide. |
408 | system-wide. |
407 | |
409 | |
408 | These three special contexts can also be referred to by the names |
410 | These three special contexts can also be referred to by the |
409 | C<AE::Log::Default>, C<AE::Log::Root> and C<AE::Log::Top>. |
411 | package/context names C<AE::Log::Default>, C<AE::Log::Root> and |
|
|
412 | C<AE::Log::Top>. |
410 | |
413 | |
411 | The effect of all this is that log messages, by default, wander up |
414 | The effect of all this is that log messages, by default, wander up |
412 | to the root context where log messages with lower priority then |
415 | to the root context where log messages with lower priority then |
413 | C<$ENV{PERL_ANYEVENT_VERBOSE}> will be filtered away and then to the |
416 | C<$ENV{PERL_ANYEVENT_VERBOSE}> will be filtered away and then to the |
414 | AnyEvent::Log::Default context to be logged to STDERR. |
417 | AnyEvent::Log::Default context to be logged to STDERR. |
… | |
… | |
468 | $default->title ("AnyEvent::Log::Default"); |
471 | $default->title ("AnyEvent::Log::Default"); |
469 | $default->log_cb (sub { |
472 | $default->log_cb (sub { |
470 | print STDERR shift; |
473 | print STDERR shift; |
471 | 0 |
474 | 0 |
472 | }); |
475 | }); |
473 | $CTX{"AnyEvent::Log::Default"} = $CTX{"AE::Log::Default"} = $default; |
476 | $AnyEvent::Log::Default = $CTX{"AnyEvent::Log::Default"} = $CTX{"AE::Log::Default"} = $default; |
474 | |
477 | |
475 | my $root = ctx undef; |
478 | my $root = ctx undef; |
476 | $root->title ("AnyEvent::Log::Root"); |
479 | $root->title ("AnyEvent::Log::Root"); |
477 | $root->level ($AnyEvent::VERBOSE); |
480 | $root->level ($AnyEvent::VERBOSE); |
478 | $root->attach ($default); |
481 | $root->attach ($default); |
479 | $CTX{"AnyEvent::Log::Root"} = $CTX{"AE::Log::Root"} = $root; |
482 | $AnyEvent::Log::Root = $CTX{"AnyEvent::Log::Root"} = $CTX{"AE::Log::Root"} = $root; |
480 | |
483 | |
481 | my $top = ctx undef; |
484 | my $top = ctx undef; |
482 | $top->title ("AnyEvent::Log::Top"); |
485 | $top->title ("AnyEvent::Log::Top"); |
483 | $top->attach ($root); |
486 | $top->attach ($root); |
484 | $CTX{"AnyEvent::Log::Top"} = $CTX{"AE::Log::Top"} = $top; |
487 | $AnyEvent::Log::Top = $CTX{"AnyEvent::Log::Top"} = $CTX{"AE::Log::Top"} = $top; |
485 | } |
488 | } |
486 | |
489 | |
487 | AnyEvent::Log::reset; |
490 | AnyEvent::Log::reset; |
488 | |
491 | |
|
|
492 | # hello, CPAN, please catch me |
489 | package AnyEvent::Log::Default; |
493 | package AnyEvent::Log::Default; |
490 | package AE::Log::Default; |
494 | package AE::Log::Default; |
491 | package AnyEvent::Log::Root; |
495 | package AnyEvent::Log::Root; |
492 | package AE::Log::Root; |
496 | package AE::Log::Root; |
493 | package AnyEvent::Log::Top; |
497 | package AnyEvent::Log::Top; |
494 | package AE::Log::Top; |
498 | package AE::Log::Top; |
495 | |
499 | |
496 | =back |
|
|
497 | |
|
|
498 | =cut |
|
|
499 | |
|
|
500 | package AnyEvent::Log::Ctx; |
500 | package AnyEvent::Log::Ctx; |
501 | |
501 | |
502 | # 0 1 2 3 4 |
502 | # 0 1 2 3 4 |
503 | # [$title, $level, %$parents, &$logcb, &$fmtcb] |
503 | # [$title, $level, %$parents, &$logcb, &$fmtcb] |
|
|
504 | |
|
|
505 | =item $ctx = new AnyEvent::Log::Ctx methodname => param... |
|
|
506 | |
|
|
507 | This is a convenience constructor that makes it simpler to construct |
|
|
508 | anonymous logging contexts. |
|
|
509 | |
|
|
510 | Each key-value pair results in an invocation of the method of the same |
|
|
511 | name as the key with the value as parameter, unless the value is an |
|
|
512 | arrayref, in which case it calls the method with the contents of the |
|
|
513 | array. The methods are called in the same order as specified. |
|
|
514 | |
|
|
515 | Example: create a new logging context and set both the default logging |
|
|
516 | level, some parent contexts and a logging callback. |
|
|
517 | |
|
|
518 | $ctx = new AnyEvent::Log::Ctx |
|
|
519 | title => "dubious messages", |
|
|
520 | level => "error", |
|
|
521 | log_cb => sub { print STDOUT shift; 0 }, |
|
|
522 | parents => [$ctx1, $ctx, $ctx2], |
|
|
523 | ; |
|
|
524 | |
|
|
525 | =back |
|
|
526 | |
|
|
527 | =cut |
|
|
528 | |
|
|
529 | sub new { |
|
|
530 | my $class = shift; |
|
|
531 | |
|
|
532 | my $ctx = AnyEvent::Log::ctx undef; |
|
|
533 | |
|
|
534 | while (@_) { |
|
|
535 | my ($k, $v) = splice @_, 0, 2; |
|
|
536 | $ctx->$k (ref $v eq "ARRAY" ? @$v : $v); |
|
|
537 | } |
|
|
538 | |
|
|
539 | bless $ctx, $class # do we really support subclassing, hmm? |
|
|
540 | } |
|
|
541 | |
504 | |
542 | |
505 | =head2 CONFIGURING A LOG CONTEXT |
543 | =head2 CONFIGURING A LOG CONTEXT |
506 | |
544 | |
507 | The following methods can be used to configure the logging context. |
545 | The following methods can be used to configure the logging context. |
508 | |
546 | |
… | |
… | |
758 | |
796 | |
759 | 1; |
797 | 1; |
760 | |
798 | |
761 | =back |
799 | =back |
762 | |
800 | |
|
|
801 | =head1 EXAMPLES |
|
|
802 | |
|
|
803 | This section shows some common configurations. |
|
|
804 | |
|
|
805 | =over 4 |
|
|
806 | |
|
|
807 | =item Setting the global logging level. |
|
|
808 | |
|
|
809 | Either put PERL_ANYEVENT_VERBOSE=<number> into your environment before |
|
|
810 | running your program, or modify the log level of the root context: |
|
|
811 | |
|
|
812 | PERL_ANYEVENT_VERBOSE=5 ./myprog |
|
|
813 | |
|
|
814 | $AnyEvent::Log::Root->level ("warn"); |
|
|
815 | |
|
|
816 | =item Append all messages to a file instead of sending them to STDERR. |
|
|
817 | |
|
|
818 | This is affected by the global logging level. |
|
|
819 | |
|
|
820 | open my $fh, ">>", $path |
|
|
821 | or die "$path: $!"; |
|
|
822 | |
|
|
823 | $AnyEvent::Log::Default->log_cb (sub { |
|
|
824 | syswrite $fh, shift; |
|
|
825 | 0 |
|
|
826 | }); |
|
|
827 | |
|
|
828 | =item Write all messages with priority C<error> and higher to a file. |
|
|
829 | |
|
|
830 | This writes them only when the global logging level allows it, because |
|
|
831 | it is attached to the default context which is invoked I<after> global |
|
|
832 | filtering. |
|
|
833 | |
|
|
834 | open my $fh, ">>", $path |
|
|
835 | or die "$path: $!"; |
|
|
836 | |
|
|
837 | $AnyEvent::Log::Default->attach (new AnyEvent::Log::Ctx |
|
|
838 | log_cb => sub { syswrite $fh, shift; 0 }); |
|
|
839 | |
|
|
840 | This writes them regardless of the global logging level, because it is |
|
|
841 | attached to the toplevel context, which receives all messages I<before> |
|
|
842 | the global filtering. |
|
|
843 | |
|
|
844 | $AnyEvent::Log::Top->attach (new AnyEvent::Log::Ctx |
|
|
845 | log_cb => sub { syswrite $fh, shift; 0 }); |
|
|
846 | |
|
|
847 | In both cases, messages are still written to STDOUT. |
|
|
848 | |
|
|
849 | =item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s). |
|
|
850 | |
|
|
851 | Attach the CyAnyEvent::Log::Default> context to the C<AnyEvent::Debug> |
|
|
852 | context and increase the C<AnyEvent::Debug> logging level - this simply |
|
|
853 | circumvents the global filtering for trace messages. |
|
|
854 | |
|
|
855 | my $debug = AnyEvent::Debug->AnyEvent::Log::ctx; |
|
|
856 | $debug->attach ($AnyEvent::Log::Default); |
|
|
857 | $debug->levels ("trace"); # not "level"! |
|
|
858 | |
|
|
859 | This of course works for any package. |
|
|
860 | |
|
|
861 | =back |
|
|
862 | |
763 | =head1 AUTHOR |
863 | =head1 AUTHOR |
764 | |
864 | |
765 | Marc Lehmann <schmorp@schmorp.de> |
865 | Marc Lehmann <schmorp@schmorp.de> |
766 | http://home.schmorp.de/ |
866 | http://home.schmorp.de/ |
767 | |
867 | |