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

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.38 by root, Fri Aug 26 00:32:45 2011 UTC vs.
Revision 1.43 by root, Mon Sep 5 07:21:54 2011 UTC

    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!"; # never returns
+   # available log levels in order:
+   # fatal alert critical error warn note info debug trace
 "Complex" uses (for speed sensitive code):
    use AnyEvent::Log;
    my $tracer = AnyEvent::Log::logger trace => \$my $trace;
    # 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,
+      log_to_syslog => "user",
    );
 =head1 DESCRIPTION
 This module implements a relatively simple "logging framework". It doesn't
 numerical value".
 Instead of specifying levels by name you can also specify them by aliases:
    LVL NAME      SYSLOG   PERL  NOTE
-   1   fatal     emerg    exit  aborts program!
+    1  fatal     emerg    exit  system unusable, aborts program!
-   2   alert
+    2  alert                    failure in primary system
-   3   critical  crit
+    3  critical  crit           failure in backup system
-   4   error     err      die
+    4  error     err      die   non-urgent program errors, a bug
-   5   warn      warning
+    5  warn      warning        possible problem, not necessarily error
-   6   note      notice
+    6  note      notice         unusual conditions
-   7   info
+    7  info                     normal messages, no action required
-   8   debug
+    8  debug                    debugging messages for development
-   9   trace
+    9  trace                    copious tracing output
 As you can see, some logging levels have multiple aliases - the first one
 is the "official" name, the second one the "syslog" name (if it differs)
-and the third one the "perl" name, suggesting that you log C<die> messages
+and the third one the "perl" name, suggesting (only!) that you log C<die>
-at C<error> priority.
+messages at C<error> priority. The NOTE column tries to provide some
+rationale on how to chose a logging level.
+As a rough guideline, levels 1..3 are primarily meant for users of
+the program (admins, staff), and are the only logged to STDERR by
+default. Levels 4..6 are meant for users and developers alike, while
+levels 7..9 are usually meant for developers.
 You can normally only log a single message at highest priority level
 (C<1>, C<fatal>), because logging a fatal message will also quit the
 program - so use it sparingly :)
 =item AnyEvent::Log::log $level, $msg[, @args]
 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.
+For loglevel C<fatal>, 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.
 The C<$msg> should not end with C<\n>, but may if that is convenient for
    }
    join "", @res
 }
+sub fatal_exit() {
+   exit 1;
+}
 sub _log {
    my ($ctx, $level, $format, @args) = @_;
    $level = $level > 0 && $level <= 9
             ? $level+0
             }
          }
       }
    while $ctx = pop @ctx;
-   exit 1 if $level <= 1;
+   fatal_exit 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 given
 level. C<$logger> is passed a C<$msg> and optional C<@args>, just as with
    $LOGGER{$logger+0} = $logger;
    _reassess $logger+0;
-   require AnyEvent::Util;
+   require AnyEvent::Util unless $AnyEvent::Util::VERSION;
    my $guard = AnyEvent::Util::guard (sub {
       # "clean up"
       delete $LOGGER{$logger+0};
    });
 By default, C<AnyEvent::Log> will use C<AE::now>, i.e. the cached
 eventloop time, for the log timestamps. After calling this function with a
 true value it will instead resort to C<AE::time>, i.e. fetch the current
 time on each log message. This only makes a difference for event loops
 that actually cache the time (such as L<EV> or L<AnyEvent::Loop>).
+This setting can be changed at any time by calling this function.
 Since C<AnyEvent::Log> has to work even before the L<AnyEvent> has been
 initialised, this switch will also decide whether to use C<CORE::time> or
 C<Time::HiRes::time> when logging a message before L<AnyEvent> becomes
 available.
 This can be used to implement config-file (re-)loading: before loading a
 configuration, reset all contexts.
 =cut
+our $ORIG_VERBOSE = $AnyEvent::VERBOSE;
+$AnyEvent::VERBOSE = 9;
 sub reset {
    # hard to kill complex data structures
    # we "recreate" all package loggers and reset the hierarchy
    while (my ($k, $v) = each %CTX) {
       @$v = ($k, (1 << 10) - 1 - 1, { });
    $LOG->title ('$AnyEvent::Log::LOG');
    $LOG->log_to_warn;
    $FILTER->slaves ($LOG);
    $FILTER->title ('$AnyEvent::Log::FILTER');
-   $FILTER->level ($AnyEvent::VERBOSE);
+   $FILTER->level ($ORIG_VERBOSE);
    $COLLECT->slaves ($FILTER);
    $COLLECT->title ('$AnyEvent::Log::COLLECT');
    _reassess;
 }
+# override AE::log/logger
+*AnyEvent::log    = *AE::log    = \&log;
+*AnyEvent::logger = *AE::logger = \&logger;
+# convert AnyEvent loggers to AnyEvent::Log loggers
+$_->[0] = ctx $_->[0] # convert "pkg" to "ctx"
+   for values %LOGGER;
 # create the default logger contexts
 $LOG     = ctx undef;
 $FILTER  = ctx undef;
 $COLLECT = ctx undef;
 Needless(?) to say, if you do not want to be bitten by some evil person
 calling C<chdir>, the path should be absolute. Doesn't help with
 C<chroot>, but hey...
-=item $ctx->log_to_syslog ([$log_flags])
+=item $ctx->log_to_syslog ([$facility])
-Logs all messages via L<Sys::Syslog>, mapping C<trace> to C<debug> and all
+Logs all messages via L<Sys::Syslog>, mapping C<trace> to C<debug> and
-the others in the obvious way. If specified, then the C<$log_flags> are
+all the others in the obvious way. If specified, then the C<$facility> is
-simply or'ed onto the priority argument and can contain any C<LOG_xxx>
+used as the facility (C<user>, C<auth>, C<local0> and so on). The default
-flags valid for Sys::Syslog::syslog, except for the priority levels.
+facility is C<user>.
 Note that this function also sets a C<fmt_cb> - the logging part requires
 an array reference with [$level, $str] as input.
 =cut
       0
    });
 }
 sub log_to_syslog {
-   my ($ctx, $flags) = @_;
+   my ($ctx, $facility) = @_;
    require Sys::Syslog;
    $ctx->fmt_cb (sub {
       my $str = $_[3];
       $str =~ s/\n(?=.)/\n+ /g;
       [$_[2], "($_[1][0]) $str"]
    });
+   $facility ||= "user";
    $ctx->log_cb (sub {
       my $lvl = $_[0][0] < 9 ? $_[0][0] : 8;
-      Sys::Syslog::syslog ($flags | ($lvl - 1), $_)
+      Sys::Syslog::syslog ("$facility|" . ($lvl - 1), $_)
          for split /\n/, $_[0][1];
       0
    });
 }
       while (/\G((?:[^,:[:space:]]+|::|\\.)+)/gc) {
          for ("$1") {
             if ($_ eq "stderr"               ) { $ctx->log_to_warn;
             } elsif (/^file=(.+)/            ) { $ctx->log_to_file ("$1");
             } elsif (/^path=(.+)/            ) { $ctx->log_to_path ("$1");
-            } elsif (/syslog(?:=(.*))?/      ) { require Sys::Syslog; $ctx->log_to_syslog (eval "package Sys::Syslog; $1");
+            } elsif (/syslog(?:=(.*))?/      ) { require Sys::Syslog; $ctx->log_to_syslog ($1);
             } elsif ($_ eq "nolog"           ) { $ctx->log_cb (undef);
             } elsif (/^\+(.+)$/              ) { $ctx->attach ($pkg->("$1"));
             } elsif ($_ eq "+"               ) { $ctx->slaves;
             } elsif ($_ eq "off" or $_ eq "0") { $ctx->level (0);
             } elsif ($_ eq "all"             ) { $ctx->level ("all");
 This writes them only when the global logging level allows it, because
 it is attached to the default context which is invoked I<after> global
 filtering.
-   $AnyEvent::Log::FILTER->attach
+   $AnyEvent::Log::FILTER->attach (
       new AnyEvent::Log::Ctx log_to_file => $path);
    PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
 This writes them regardless of the global logging level, because it is

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents): Revision 1.38 by root, Fri Aug 26 00:32:45 2011 UTC vs. Revision 1.43 by root, Mon Sep 5 07:21:54 2011 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.38 by root, Fri Aug 26 00:32:45 2011 UTC vs.
Revision 1.43 by root, Mon Sep 5 07:21:54 2011 UTC