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

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.19 by root, Sat Aug 20 15:59:33 2011 UTC vs.
Revision 1.26 by root, Sun Aug 21 03:29:19 2011 UTC

 AnyEvent::Log - simple logging "framework"
 =head1 SYNOPSIS
-   # simple use
+Simple uses:
    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" uses (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 (also look at the EXAMPLES section):
    # 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");
-   # see also EXAMPLES, below
+   # 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,
+   );
 =head1 DESCRIPTION
 This module implements a relatively simple "logging framework". It doesn't
 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";
 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
 logging context, the (numeric) logging level and the raw message string
 and needs to return a formatted log message. In most cases this will be a
 string, but it could just as well be an array reference that just stores
 the values.
-If, for some reaosn, you want to use C<caller> to find out more baout the
+If, for some reason, you want to use C<caller> to find out more baout the
 logger then you should walk up the call stack until you are no longer
 inside the C<AnyEvent::Log> package.
 Example: format just the raw message, with numeric log level in angle
 brackets.
                "$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.19 by root, Sat Aug 20 15:59:33 2011 UTC vs. Revision 1.26 by root, Sun Aug 21 03:29:19 2011 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.19 by root, Sat Aug 20 15:59:33 2011 UTC vs.
Revision 1.26 by root, Sun Aug 21 03:29:19 2011 UTC