view release on metacpan or  search on metacpan

lib/AnyEvent/Log.pm  view on Meta::CPAN

=head1 NAME

AnyEvent::Log - simple logging "framework"

=head1 SYNOPSIS

Simple uses:

   use AnyEvent;

   AE::log fatal => "No config found, cannot continue!"; # never returns
   AE::log alert => "The battery died!";
   AE::log crit  => "The battery is too hot!";
   AE::log error => "Division by zero attempted.";
   AE::log warn  => "Couldn't delete the file.";
   AE::log note  => "Attempted to create config, but config already exists.";
   AE::log info  => "File soandso successfully deleted.";
   AE::log debug => "the function returned 3";
   AE::log trace => "going to call function abc";

Log level overview:

   LVL NAME      SYSLOG   PERL  NOTE
    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

"Complex" uses (for speed sensitive code, e.g. trace/debug messages):

   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 (also look at the EXAMPLES section):

   # set default logging level to suppress anything below "notice"
   # i.e. enable logging at "notice" or above - the default is to
   # to not log anything at all.
   $AnyEvent::Log::FILTER->level ("notice");

   # set logging for the current package to errors and higher only
   AnyEvent::Log::ctx->level ("error");

   # enable logging for the current package, regardless of global logging level
   AnyEvent::Log::ctx->attach ($AnyEvent::Log::LOG);

   # enable debug logging for module some::mod and enable logging by default
   (AnyEvent::Log::ctx "some::mod")->level ("debug");
   (AnyEvent::Log::ctx "some::mod")->attach ($AnyEvent::Log::LOG);

   # 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 => "user",
   );

=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<4> (C<error>), so only
errors and more important messages will be logged, unless you set
C<PERL_ANYEVENT_VERBOSE> to a higher number before starting your program
(C<AE_VERBOSE=5> is recommended during development), or change the logging
level at runtime with something like:

   use AnyEvent::Log;
   $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 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

Logging levels in this module range from C<1> (highest priority) to C<9>
(lowest priority). Note that the lowest numerical value is the highest
priority, so when this document says "higher priority" it means "lower
numerical value".

Instead of specifying levels by name you can also specify them by aliases:

   LVL NAME      SYSLOG   PERL  NOTE
    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 (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 ones 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 message once at highest priority level (C<1>,
C<fatal>), because logging a fatal message will also quit the program - so
use it sparingly :)

For example, a program that finds an unknown switch on the commandline
might well use a fatal logging level to tell users about it - the "system"
in this case would be the program, or module.

Some methods also offer some extra levels, such as C<0>, C<off>, C<none>
or C<all> - these are only valid for the methods that documented them.

=head1 LOGGING FUNCTIONS

The following functions allow you to log messages. They always use the
caller's package as a "logging context". Also, the main logging function,
C<log>, is aliased to C<AnyEvent::log> and C<AE::log> when the C<AnyEvent>
module is loaded.

=over 4

=cut

package AnyEvent::Log;

use Carp ();
use POSIX ();

# layout of a context
#       0       1         2        3        4,    5
# [$title, $level, %$slaves, &$logcb, &$fmtcb, $cap]

use AnyEvent (); BEGIN { AnyEvent::common_sense }
#use AnyEvent::Util (); need to load this in a delayed fashion, as it uses AE::log

our $VERSION = $AnyEvent::VERSION;

our ($COLLECT, $FILTER, $LOG);

our ($now_int, $now_str1, $now_str2);

# Format Time, not public - yet?
sub format_time($) {