[ViewVC] Diff of: cvs/AnyEvent/lib/AnyEvent/Log.pm

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.18 by root, Sat Aug 20 15:57:35 2011 UTC vs.
Revision 1.24 by root, Sun Aug 21 03:24:59 2011 UTC

 AnyEvent::Log - simple logging "framework"
 =head1 SYNOPSIS
-   # simple use
+   # simple use:
    use AnyEvent;
    AE::log debug => "hit my knee";
    AE::log warn  => "it's a bit too hot";
    AE::log error => "the flag was false!";
-   AE::log fatal => "the bit toggled! run!";
+   AE::log fatal => "the bit toggled! run!"; # never returns
-   # "complex" use
+   # "complex" use (for speed sensitive code):
    use AnyEvent::Log;
    my $tracer = AnyEvent::Log::logger trace => \$my $trace;
    $tracer->("i am here") if $trace;
    $tracer->(sub { "lots of data: " . Dumper $self }) if $trace;
-   # configuration
+   # configuration:
    # set logging for the current package to errors and higher only
    AnyEvent::Log::ctx->level ("error");
-   # set logging globally to anything below debug
+   # set logging level to suppress anything below "notice"
    $AnyEvent::Log::FILTER->level ("notice");
+   # send all critical and higher priority messages to syslog,
+   # regardless of (most) other settings
+   $AnyEvent::Log::COLLECT->attach (new AnyEvent::Log::Ctx
+      level         => "critical",
+      log_to_syslog => 0,
+   );
    # see also EXAMPLES, below
 =head1 DESCRIPTION
 attempt to be "the" logging solution or even "a" logging solution for
 AnyEvent - AnyEvent simply creates logging messages internally, and this
 module more or less exposes the mechanism, with some extra spiff to allow
 using it from other modules as well.
-Remember that the default verbosity level is C<0>, so nothing will be
+Remember that the default verbosity level is C<0> (C<off>), so nothing
-logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number before
+will be logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number
-starting your program, or change the logging level at runtime with
+before starting your program, or change the logging level at runtime with
 something like:
    use AnyEvent::Log;
    AnyEvent::Log::FILTER->level ("info");
    $ctx
 }
 =item AnyEvent::Log::log $level, $msg[, @args]
-Requests logging of the given C<$msg> with the given log level.
+Requests logging of the given C<$msg> with the given log level, and
+returns true if the message was logged I<somewhere>.
 For C<fatal> log levels, the program will abort.
 If only a C<$msg> is given, it is logged as-is. With extra C<@args>, the
 C<$msg> is interpreted as an sprintf format string.
 supposed to return the message. It will be called only then the message
 actually gets logged, which is useful if it is costly to create the
 message in the first place.
 Whether the given message will be logged depends on the maximum log level
-and the caller's package.
+and the caller's package. The return value can be used to ensure that
+messages or not "lost" - for example, when L<AnyEvent::Debug> detects a
+runtime error it tries to log it at C<die> level, but if that message is
+lost it simply uses warn.
 Note that you can (and should) call this function as C<AnyEvent::log> or
 C<AE::log>, without C<use>-ing this module if possible (i.e. you don't
 need any additional functionality), as those functions will load the
 logging module on demand only. They are also much shorter to write.
             ? $level+0
             : $STR2LEVEL{$level} || Carp::croak "$level: not a valid logging level, caught";
    my $mask = 1 << $level;
-   my (%seen, @ctx, $now, $fmt);
+   my ($success, %seen, @ctx, $now, $fmt);
    do
       {
          # skip if masked
          if ($ctx->[1] & $mask && !$seen{$ctx+0}++) {
                };
                # format msg
                my $str = $ctx->[4]
                   ? $ctx->[4]($now, $_[0], $level, $format)
-                  : $fmt ||= _format $now, $_[0], $level, $format;
+                  : ($fmt ||= _format $now, $_[0], $level, $format);
+               $success = 1;
                $ctx->[3]($str)
                   or push @ctx, values %{ $ctx->[2] }; # not consumed - propagate
             } else {
                push @ctx, values %{ $ctx->[2] }; # not masked - propagate
          }
       }
    while $ctx = pop @ctx;
    exit 1 if $level <= 1;
+   $success
 }
 sub log($$;@) {
    _log
       $CTX{ (caller)[0] } ||= _pkg_ctx +(caller)[0],
 *AnyEvent::log = *AE::log = \&log;
 =item $logger = AnyEvent::Log::logger $level[, \$enabled]
 Creates a code reference that, when called, acts as if the
-C<AnyEvent::Log::log> function was called at this point with the givne
+C<AnyEvent::Log::log> function was called at this point with the given
 level. C<$logger> is passed a C<$msg> and optional C<@args>, just as with
 the C<AnyEvent::Log::log> function:
    my $debug_log = AnyEvent::Log::logger "debug";
 =cut
 sub reset {
    # hard to kill complex data structures
-   # we recreate all package loggers and reset the hierarchy
+   # we "recreate" all package loggers and reset the hierarchy
    while (my ($k, $v) = each %CTX) {
       @$v = ($k, (1 << 10) - 1 - 1, { });
-      $v->attach ($k =~ /^(.+)::/ ? $CTX{$1} : $AnyEvent::Log);
+      $v->attach ($k =~ /^(.+)::/ ? $CTX{$1} : $AnyEvent::Log::COLLECT);
    }
+   @$_ = ($_->[0], (1 << 10) - 1 - 1)
+      for $LOG, $FILTER, $COLLECT;
    $LOG->slaves;
    $LOG->title ('$AnyEvent::Log::LOG');
    $LOG->log_cb (sub {
       warn shift;
    $FILTER->slaves ($LOG);
    $FILTER->title ('$AnyEvent::Log::FILTER');
    $FILTER->level ($AnyEvent::VERBOSE);
    $COLLECT->slaves ($FILTER);
-   $COLLECT->title ('$AnyEvent::Log::FILTER');
+   $COLLECT->title ('$AnyEvent::Log::COLLECT');
    _reassess;
 }
 # create the default logger contexts
 the logging (which consists of formatting the message and printing it or
 whatever it wants to do with it).
 =over 4
-=item $ctx->log_cb ($cb->($str))
+=item $ctx->log_cb ($cb->($str)
 Replaces the logging callback on the context (C<undef> disables the
 logging callback).
 The logging callback is responsible for handling formatted log messages
 your program.
    $ctx->levels ("debug", "trace");
    $ctx->log_cb (sub { 1 }); # do not log, but eat debug and trace messages
-=item $ctx->log_to_file ($path)
-Sets the C<log_cb> to log to a file (by appending), unbuffered.
-=item $ctx->log_to_path ($path)
-Same as C<< ->log_to_file >>, but opens the file for each message. This
-is much slower, but allows you to change/move/rename/delete the file at
-basically any time.
-=item $ctx->fmt_cb ($fmt_cb->($timestamp, $ctx, $level, $message))
+=item $ctx->fmt_cb ($fmt_cb->($timestamp, $orig_ctx, $level, $message))
 Replaces the formatting callback on the context (C<undef> restores the
 default formatter).
 The callback is passed the (possibly fractional) timestamp, the original
                "$msg->[3]";
       0
    });
+=item $ctx->log_to_file ($path)
+Sets the C<log_cb> to log to a file (by appending), unbuffered.
+=item $ctx->log_to_path ($path)
+Same as C<< ->log_to_file >>, but opens the file for each message. This
+is much slower, but allows you to change/move/rename/delete the file at
+basically any time.
+=item $ctx->log_to_syslog ([$log_flags])
+Logs all messages via L<Sys::Syslog>, mapping C<trace> to C<debug> and all
+the others in the obvious way. If specified, then the C<$log_flags> are
+simply or'ed onto the priority argument and can contain any C<LOG_xxx>
+flags valid for Sys::Syslog::syslog, except for the priority levels.
+Note that this function also sets a C<fmt_cb> - the logging part requires
+an array reference with [$level, $str] as input.
 =cut
 sub log_cb {
    my ($ctx, $cb) = @_;
       syswrite $fh, shift;
       0
    });
 }
+sub log_to_syslog {
+   my ($ctx, $flags) = @_;
+   require Sys::Syslog;
+   $ctx->fmt_cb (sub {
+      my $str = $_[3];
+      $str =~ s/\n(?=.)/\n+ /g;
+      [$_[2], "($_[1][0]) $str"]
+   });
+   $ctx->log_cb (sub {
+      my $lvl = $_[0][0] < 9 ? $_[0][0] : 8;
+      Sys::Syslog::syslog ($flags | ($lvl - 1), $_)
+         for split /\n/, $_[0][1];
+      0
+   });
+}
 =back
 =head3 MESSAGE LOGGING
 These methods allow you to log messages directly to a context, without

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents): Revision 1.18 by root, Sat Aug 20 15:57:35 2011 UTC vs. Revision 1.24 by root, Sun Aug 21 03:24:59 2011 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.18 by root, Sat Aug 20 15:57:35 2011 UTC vs.
Revision 1.24 by root, Sun Aug 21 03:24:59 2011 UTC