NAME¶
Net::CLI::Interact::Logger - Per-instance multi-target logging, with categories
VERSION¶
version 2.142720
SYNOPSIS¶
$logger->log($category, $level, @message);
DESCRIPTION¶
This module implements a generic logging service, based on Log::Dispatch but
with additional options and configuration. Log messages coming from your
application are categorized, and each category can be enabled/disabled
separately and have its own log level (i.e. "emergency" ..
"debug"). High resolution timestamps can be added to log messages.
DEFAULT CONFIGURATION¶
Being based on Log::Dispatch::Config, this logger can have multiple targets,
each configured for independent level thresholds. The overall default
configuration is to print log messages to the screen (console), with a minimum
level of "debug". Each category (see below) has its own log level as
well.
Note that categories, as discussed below, are arbitrary so if a category is not
explicitly enabled or disabled, it is assumed to be
disabled. If you
wish to invent a new category for your application, simply think of the name
and begin to use it, with a $level and @message as above in the SYNOPSIS.
INTERFACE¶
log( $category, $level, @message )¶
The combination of category and level determine whether the the log messages are
emitted to any of the log destinations. Destinations are set using the
"log_config" method, and categories are configured using the
"log_flags" method.
The @message list will be joined by a space character, and a newline appended if
the last message doesn't contain one itself. Messages are prepended with the
first character of their $category, and then indented proportionally to their
$level.
log_config( \%config )¶
A "Log::Dispatch::Config" configuration (hash ref), meaning multiple
log targets may be specified with different minimum level thresholds. There is
a default configuration which emits messages to your screen (console) with no
minimum threshold:
{
dispatchers => ['screen'],
screen => {
class => 'Log::Dispatch::Screen',
min_level => 'debug',
},
};
log_flags( \@categories | \%category_level_map )¶
The user is expected to specify which log categories they are interested in, and
at what levels. If a category is used in the application for logging but not
specified, then it is deemed
disabled. Hence, even though the default
destination log level is "debug", no messages are emitted until a
category is enabled.
In the array reference form, the list should contain category names, and they
will all be mapped to the "error" level:
$logger->log_flags([qw/
network
disk
io
cpu
/]);
In the hash reference form, the keys should be category names and the values log
levels from the list below (ordered such that each level "includes"
the levels
above):
emergency
alert
critical
error
warning
notice
info
debug
For example:
$logger->log_flags({
network => 'info',
disk => 'debug',
io => 'critical',
cpu => 'debug',
});
Messages at or above the specified level will be passed on to the
"Log::Dispatch" target, which may then specify an overriding
threshold.
" Net::CLI::Interact-" default_log_categories() >>¶
Not a part of this class, but the only way to retrieve a list of the current log
categories used in the Net::CLI::Interact distribution source. Does not take
into account any log categories added by the user.
log_stamp( $boolean )¶
Enable (the default) or disable the display of high resolution interval
timestamps with each log message.
log_category( $boolean )¶
Enable (the default) or disable the display of the first letters of the category
name with each log message.
log_start( [$seconds, $microseconds] )¶
Time of the start for generating a time interval when logging stamps. Defaults
to the result of "Time::HiRes::gettimeofday" at the point the module
is loaded, in list context.
would_log( $category, $level )¶
Returns True if, according to the current "log_flags", the given
$category is enabled at or above the threshold of $level, otherwise returns
False. Note that the "Log::Dispatch" targets maintain their own
thresholds as well.
AUTHOR¶
Oliver Gorwits <oliver@cpan.org>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2014 by Oliver Gorwits.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.