--- AnyEvent/lib/AnyEvent/Log.pm	2011/08/25 03:08:48	1.31
+++ AnyEvent/lib/AnyEvent/Log.pm	2011/09/01 22:38:11	1.42
@@ -13,6 +13,9 @@
    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;
@@ -34,7 +37,7 @@
    # 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
@@ -51,15 +54,18 @@
 something like:
 
    use AnyEvent::Log;
-   AnyEvent::Log::FILTER->level ("info");
+   $AnyEvent::Log::FILTER->level ("info");
 
 The design goal behind this module was to keep it simple (and small),
 but make it powerful enough to be potentially useful for any module, and
 extensive enough for the most common tasks, such as logging to multiple
 targets, or being able to log into a database.
 
-The amount of documentation might indicate otherwise, but the module is
-still just below 300 lines of code.
+The module is also usable before AnyEvent itself is initialised, in which
+case some of the functionality might be reduced.
+
+The amount of documentation might indicate otherwise, but the runtime part
+of the module is still just below 300 lines of code.
 
 =head1 LOGGING LEVELS
 
@@ -71,20 +77,26 @@
 Instead of specifying levels by name you can also specify them by aliases:
 
    LVL NAME      SYSLOG   PERL  NOTE
-   1   fatal     emerg    exit  aborts program!
-   2   alert
-   3   critical  crit     
-   4   error     err      die
-   5   warn      warning  
-   6   note      notice   
-   7   info
-   8   debug
-   9   trace
+    1  fatal     emerg    exit  system unusable, aborts program!
+    2  alert                    failure in primary system
+    3  critical  crit           failure in backup system
+    4  error     err      die   non-urgent program errors, a bug
+    5  warn      warning        possible problem, not necessarily error
+    6  note      notice         unusual conditions
+    7  info                     normal messages, no action required
+    8  debug                    debugging messages for development
+    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
-at C<error> priority.
+and the third one the "perl" name, suggesting (only!) that you log C<die>
+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
@@ -110,7 +122,7 @@
 use POSIX ();
 
 use AnyEvent (); BEGIN { AnyEvent::common_sense }
-use AnyEvent::Util ();
+#use AnyEvent::Util (); need to load this in a delayed fashion, as it uses AE::log
 
 our $VERSION = $AnyEvent::VERSION;
 
@@ -150,7 +162,7 @@
 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.
@@ -205,10 +217,21 @@
    trace    => 9,
 );
 
-sub now () { time }
+our $TIME_EXACT;
+
+sub exact_time($) {
+   $TIME_EXACT = shift;
+   *_ts = $AnyEvent::MODEL
+      ? $TIME_EXACT ? \&AE::now : \&AE::time
+      : sub () { $TIME_EXACT ? do { require Time::HiRes; Time::HiRes::time () } : time };
+}
+
+BEGIN {
+   exact_time 0;
+}
 
 AnyEvent::post_detect {
-   *now = \&AE::now;
+   exact_time $TIME_EXACT;
 };
 
 our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace);
@@ -251,7 +274,7 @@
                   $format = $format->() if ref $format;
                   $format = sprintf $format, @args if @args;
                   $format =~ s/\n$//;
-                  $now = now;
+                  $now = _ts;
                };
 
                # format msg
@@ -356,10 +379,11 @@
 
    _reassess $logger+0;
 
-   my $guard = AnyEvent::Util::guard {
+   require AnyEvent::Util;
+   my $guard = AnyEvent::Util::guard (sub {
       # "clean up"
       delete $LOGGER{$logger+0};
-   };
+   });
 
    sub {
       $guard if 0; # keep guard alive, but don't cause runtime overhead
@@ -375,6 +399,21 @@
       @_
 }
 
+=item AnyEvent::Log::exact_time $on
+
+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.
+
 =back
 
 =head1 LOGGING CONTEXTS
@@ -515,7 +554,7 @@
    @$_ = ($_->[0], (1 << 10) - 1 - 1)
       for $LOG, $FILTER, $COLLECT;
 
-   $LOG->slaves;
+   #$LOG->slaves;
    $LOG->title ('$AnyEvent::Log::LOG');
    $LOG->log_to_warn;
 
@@ -836,12 +875,12 @@
 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
-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.
+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<$facility> is
+used as the facility (C<user>, C<auth>, C<local0> and so on). The default
+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.
@@ -894,7 +933,7 @@
 }
 
 sub log_to_syslog {
-   my ($ctx, $flags) = @_;
+   my ($ctx, $facility) = @_;
 
    require Sys::Syslog;
 
@@ -905,10 +944,12 @@
       [$_[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
@@ -1014,7 +1055,7 @@
 
 =item C<syslog> or C<syslog=>I<expr>
 
-Configured the context to log to syslog. If I<expr> is given, then it is
+Configures the context to log to syslog. If I<expr> is given, then it is
 evaluated in the L<Sys::Syslog> package, so you could use:
 
    log=syslog=LOG_LOCAL0
@@ -1066,7 +1107,7 @@
    # or, more verbose
    filter=only,level,warn
 
-=item C<1>..C<9>, a logging level name (C<error>, C<debug> etc.)
+=item C<1>..C<9> or a logging level name (C<error>, C<debug> etc.)
 
 A numeric loglevel or the name of a loglevel will be interpreted according
 to the most recent C<only>, C<except> or C<level> directive. By default,
@@ -1074,13 +1115,13 @@
 
 =item C<+>I<context>
 
-Adds/attaches the named context as slave to the context.
+Attaches the named context as slave to the context.
 
 =item C<+>
 
-A line C<+> clears the slave list form the context. Anonymous (C<%name>)
-contexts have no slaves by default, but package contexts have the parent
-context as slave by default.
+A line C<+> detaches all contexts, i.e. clears the slave list from the
+context. Anonymous (C<%name>) contexts have no attached slaves by default,
+but package contexts have the parent context as slave by default.
 
 Example: log messages from My::Module to a file, do not send them to the
 default log collector.
@@ -1090,8 +1131,8 @@
 =back
 
 Any character can be escaped by prefixing it with a C<\> (backslash), as
-usual, so to log to a file containing a comma, colon, backslash and space in the
-filename, you would do this:
+usual, so to log to a file containing a comma, colon, backslash and some
+spaces in the filename, you would do this:
 
    PERL_ANYEVENT_LOG='log=file=/some\ \:file\ with\,\ \\-escapes'
 
@@ -1135,7 +1176,7 @@
             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;