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",
);
Remember that the default verbosity level is 4 ("error"), so only errors and more important messages will be logged, unless you set "PERL_ANYEVENT_VERBOSE" to a higher number before starting your program ("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.
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 "die" messages at "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 (1, "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 0, "off", "none" or "all" - these are only valid for the methods that documented them.
For loglevel "fatal", the program will abort.
If only a $msg is given, it is logged as-is. With extra @args, the $msg is interpreted as an sprintf format string.
The $msg should not end with "\n", but may if that is convenient for you. Also, multiline messages are handled properly.
Last not least, $msg might be a code reference, in which case it is 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.
This function takes care of saving and restoring $! and $@, so you don't have to.
Whether the given message will be logged depends on the maximum log level and the caller's package. The return value can be used to ensure that messages or not ``lost'' - for example, when AnyEvent::Debug detects a runtime error it tries to log it at "die" level, but if that message is lost it simply uses warn.
Note that you can (and should) call this function as "AnyEvent::log" or "AE::log", without "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.
Also, if you optionally generate a lot of debug messages (such as when tracing some code), you should look into using a logger callback and a boolean enabler (see "logger", below).
Example: log something at error level.
AE::log error => "something";
Example: use printf-formatting.
AE::log info => "%5d %-10.10s %s", $index, $category, $msg;
Example: only generate a costly dump when the message is actually being logged.
AE::log debug => sub { require Data::Dump; Data::Dump::dump \%cache };
my $debug_log = AnyEvent::Log::logger "debug";
$debug_log->("debug here");
$debug_log->("%06d emails processed", 12345);
$debug_log->(sub { $obj->as_string });
The idea behind this function is to decide whether to log before actually logging - when the "logger" function is called once, but the returned logger callback often, then this can be a tremendous speed win.
Despite this speed advantage, changes in logging configuration will still be reflected by the logger callback, even if configuration changes after it was created.
To further speed up logging, you can bind a scalar variable to the logger, which contains true if the logger should be called or not - if it is false, calling the logger can be safely skipped. This variable will be updated as long as $logger is alive.
Full example:
# near the init section
use AnyEvent::Log;
my $debug_log = AnyEvent:Log::logger debug => \my $debug;
# and later in your program
$debug_log->("yo, stuff here") if $debug;
$debug and $debug_log->("123");
This setting can be changed at any time by calling this function.
Since "AnyEvent::Log" has to work even before the AnyEvent has been initialised, this switch will also decide whether to use "CORE::time" or "Time::HiRes::time" when logging a message before AnyEvent becomes available.
In your main program (as opposed to in your module) you can override the default timestamp display format by loading this module and then redefining this function.
Most commonly, this function can be used in formatting callbacks.
This is the formatting function used to format messages when no custom function is provided.
In your main program (as opposed to in your module) you can override the default message format by loading this module and then redefining this function.
The default implementation simply calls "exit 1".
In your main program (as opposed to in your module) you can override the fatal exit function by loading this module and then redefining this function. Make sure you don't return.
A logging context has three major responsibilities: filtering, logging and propagating the message.
For the first purpose, filtering, each context has a set of logging levels, called the log level mask. Messages not in the set will be ignored by this context (masked).
For logging, the context stores a formatting callback (which takes the timestamp, context, level and string message and formats it in the way it should be logged) and a logging callback (which is responsible for actually logging the formatted message and telling "AnyEvent::Log" whether it has consumed the message, or whether it should be propagated).
For propagation, a context can have any number of attached slave contexts. Any message that is neither masked by the logging mask nor masked by the logging callback returning true will be passed to all slave contexts.
Each call to a logging function will log the message at most once per context, so it does not matter (much) if there are cycles or if the message can arrive at the same context via multiple paths.
Package contexts have the package name as logging title by default.
They have exactly one slave - the context of the ``parent'' package. The parent package is simply defined to be the package name without the last component, i.e. "AnyEvent::Debug::Wrapped" becomes "AnyEvent::Debug", and "AnyEvent" becomes ... $AnyEvent::Log::COLLECT which is the exception of the rule - just like the ``parent'' of any single-component package name in Perl is "main", the default slave of any top-level package context is $AnyEvent::Log::COLLECT.
Since perl packages form only an approximate hierarchy, this slave context can of course be removed.
All other (anonymous) contexts have no slaves and an empty title by default.
When the module is loaded it creates the $AnyEvent::Log::LOG logging context that simply logs everything via "warn", without propagating anything anywhere by default. The purpose of this context is to provide a convenient place to override the global logging target or to attach additional log targets. It's not meant for filtering.
It then creates the $AnyEvent::Log::FILTER context whose purpose is to suppress all messages with priority higher than $ENV{PERL_ANYEVENT_VERBOSE}. It then attached the $AnyEvent::Log::LOG context to it. The purpose of the filter context is to simply provide filtering according to some global log level.
Finally it creates the top-level package context $AnyEvent::Log::COLLECT and attaches the $AnyEvent::Log::FILTER context to it, but otherwise leaves it at default config. Its purpose is simply to collect all log messages system-wide.
The hierarchy is then:
any package, eventually -> $COLLECT -> $FILTER -> $LOG
The effect of all this is that log messages, by default, wander up to the $AnyEvent::Log::COLLECT context where all messages normally end up, from there to $AnyEvent::Log::FILTER where log messages with lower priority then $ENV{PERL_ANYEVENT_VERBOSE} will be filtered out and then to the $AnyEvent::Log::LOG context to be passed to "warn".
This makes it easy to set a global logging level (by modifying $FILTER), but still allow other contexts to send, for example, their debug and trace messages to the $LOG target despite the global logging level, or to attach additional log targets that log messages, regardless of the global logging level.
It also makes it easy to modify the default warn-logger ($LOG) to something that logs to a file, or to attach additional logging targets (such as loggign to a file) by attaching it to $FILTER.
If a package name is given, then the context for that package is returned. If it is called without any arguments, then the context for the callers package is returned (i.e. the same context as a "AE::log" call would use).
If "undef" is given, then it creates a new anonymous context that is not tied to any package and is destroyed when no longer referenced.
This can be used to implement config-file (re-)loading: before loading a configuration, reset all contexts.
Each key-value pair results in an invocation of the method of the same name as the key with the value as parameter, unless the value is an arrayref, in which case it calls the method with the contents of the array. The methods are called in the same order as specified.
Example: create a new logging context and set both the default logging level, some slave contexts and a logging callback.
$ctx = new AnyEvent::Log::Ctx
title => "dubious messages",
level => "error",
log_cb => sub { print STDOUT shift; 0 },
slaves => [$ctx1, $ctx, $ctx2],
;
If $new_title is given, then it replaces the package name or title.
LOGGING LEVELS
The following methods deal with the logging level set associated with the log context.
The most common method to use is probably "$ctx->level ($level)", which configures the specified and any higher priority levels.
All functions which accept a list of levels also accept the special string "all" which expands to all logging levels.
Example: log warnings, errors and higher priority messages.
$ctx->level ("warn");
$ctx->level (5); # same thing, just numeric
Another way to view this is that "->level" filters out messages with a too low priority, while "->cap" modifies messages with a too high priority.
This is useful when different log targets have different interpretations of priority. For example, for a specific command line program, a wrong command line switch might well result in a "fatal" log message, while the same message, logged to syslog, is likely not fatal to the system or syslog facility as a whole, but more likely a mere "error".
This can be modeled by having a stderr logger that logs messages ``as-is'' and a syslog logger that logs messages with a level cap of, say, "error", or, for truly system-critical components, actually "critical".
SLAVE CONTEXTS
The following methods attach and detach another logging context to a logging context.
Log messages are propagated to all slave contexts, unless the logging callback consumes the message.
A context can be specified either as package name or as a context object.
A context can be specified either as package name or as a context object.
LOG TARGETS
The following methods configure how the logging context actually does the logging (which consists of formatting the message and printing it or whatever it wants to do with it).
The logging callback is responsible for handling formatted log messages (see "fmt_cb" below) - normally simple text strings that end with a newline (and are possibly multiline themselves).
It also has to return true iff it has consumed the log message, and false if it hasn't. Consuming a message means that it will not be sent to any slave context. When in doubt, return 0 from your logging callback.
Example: a very simple logging callback, simply dump the message to STDOUT and do not consume it.
$ctx->log_cb (sub { print STDERR shift; 0 });
You can filter messages by having a log callback that simply returns 1 and does not do anything with the message, but this counts as ``message being logged'' and might not be very efficient.
Example: propagate all messages except for log levels ``debug'' and ``trace''. The messages will still be generated, though, which can slow down your program.
$ctx->levels ("debug", "trace");
$ctx->log_cb (sub { 1 }); # do not log, but eat debug and trace messages
The callback is passed the (possibly fractional) timestamp, the original logging context (object, not title), 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 reason, you want to use "caller" to find out more about the logger then you should walk up the call stack until you are no longer inside the "AnyEvent::Log" package.
To implement your own logging callback, you might find the "AnyEvent::Log::format_time" and "AnyEvent::Log::default_format" functions useful.
Example: format the message just as AnyEvent::Log would, by letting AnyEvent::Log do the work. This is a good basis to design a formatting callback that only changes minor aspects of the formatting.
$ctx->fmt_cb (sub {
my ($time, $ctx, $lvl, $msg) = @_;
AnyEvent::Log::default_format $time, $ctx, $lvl, $msg
});
Example: format just the raw message, with numeric log level in angle brackets.
$ctx->fmt_cb (sub {
my ($time, $ctx, $lvl, $msg) = @_;
"<$lvl>$msg\n"
});
Example: return an array reference with just the log values, and use "PApp::SQL::sql_exec" to store the message in a database.
$ctx->fmt_cb (sub { \@_ });
$ctx->log_cb (sub {
my ($msg) = @_;
sql_exec "insert into log (when, subsys, prio, msg) values (?, ?, ?, ?)",
$msg->[0] + 0,
"$msg->[1]",
$msg->[2] + 0,
"$msg->[3]";
0
});
Needless(?) to say, if you do not want to be bitten by some evil person calling "chdir", the path should be absolute. Doesn't help with "chroot", but hey...
Note that this function also sets a "fmt_cb" - the logging part requires an array reference with [$level, $str] as input.
MESSAGE LOGGING
These methods allow you to log messages directly to a context, without going via your package context.
Example: log a message in the context of another package.
(AnyEvent::Log::ctx "Other::Package")->log (warn => "heely bo");
The value consists of one or more logging context specifications separated by ":" or whitespace. Each logging specification in turn starts with a context name, followed by "=", followed by zero or more comma-separated configuration directives, here are some examples:
# set default logging level filter=warn # log to file instead of to stderr log=file=/tmp/mylog # log to file in addition to stderr log=+%file:%file=file=/tmp/mylog # enable debug log messages, log warnings and above to syslog filter=debug:log=+%warnings:%warnings=warn,syslog=LOG_LOCAL0 # log trace messages (only) from AnyEvent::Debug to file AnyEvent::Debug=+%trace:%trace=only,trace,file=/tmp/tracelog
A context name in the log specification can be any of the following:
This makes it possible to create new log contexts that can be refered to multiple times by name within the same log specification.
The configuration specifications can be any number of the following:
log=syslog=LOG_LOCAL0
Example: only enable debug messages for a context.
context=only,debug
Example: enable all logging levels except fatal and trace (this is rather nonsensical).
filter=exept,fatal,trace
Example: log anything at or above warn level.
filter=warn # or, more verbose filter=only,level,warn
Example: log messages from My::Module to a file, do not send them to the default log collector.
My::Module=+,file=/tmp/mymodulelog
Any character can be escaped by prefixing it with a "\" (backslash), as 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'
Since whitespace (which includes newlines) is allowed, it is fine to specify multiple lines in "PERL_ANYEVENT_LOG", e.g.:
PERL_ANYEVENT_LOG="
filter=warn
AnyEvent::Debug=+%trace
%trace=only,trace,+log
" myprog
Also, in the unlikely case when you want to concatenate specifications, use whitespace as separator, as "::" will be interpreted as part of a module name, an empty spec with two separators:
PERL_ANYEVENT_LOG="$PERL_ANYEVENT_LOG MyMod=debug"
PERL_ANYEVENT_VERBOSE=5 ./myprog
PERL_ANYEVENT_LOG=log=warn
$AnyEvent::Log::FILTER->level ("warn");
$AnyEvent::Log::LOG->log_to_file ($path); PERL_ANYEVENT_LOG=log=file=/some/path
$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 attached to the toplevel context, which receives all messages before the global filtering.
$AnyEvent::Log::COLLECT->attach (
new AnyEvent::Log::Ctx log_to_file => $path);
PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
In both cases, messages are still written to STDERR.
$AnyEvent::Log::LOG->attach (
new AnyEvent::Log::Ctx
level => "warn",
cap => "error",
syslog => "user",
);
PERL_ANYEVENT_LOG=log=+%syslog:%syslog=warn,cap=error,syslog
my $debug = AnyEvent::Debug->AnyEvent::Log::ctx; $debug->attach ($AnyEvent::Log::LOG); PERL_ANYEVENT_LOG=AnyEvent::Debug=+log
This of course works for any package, not just AnyEvent::Debug, but assumes the log level for AnyEvent::Debug hasn't been changed from the default.
Marc Lehmann <schmorp@schmorp.de> http://anyevent.schmorp.de