NAME

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

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.