Oliver Gorwits > Net-CLI-Interact-1.122100 > Net::CLI::Interact::Logger

Download:
Net-CLI-Interact-1.122100.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

New  1
Open  1
View/Report Bugs
Module Version: 1.122100   Source   Latest Release: Net-CLI-Interact-2.142010

NAME ^

Net::CLI::Interact::Logger - Per-instance multi-target logging, with categories

VERSION ^

version 1.122100

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.

log_stamps( $boolean )

Enable (the default) or disable the display of high resolution interval timestamps 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) 2012 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.

syntax highlighting: