NAME

Mnet::Log - Logging compatible with Log4perl api

SYNOPSIS

    # imports DEBUG, INFO, WARN, and FATAL
    use Mnet::Log qw( DEBUG INFO WARN FATAL );

    # options can be set for Mnet::Log objects
    my $log = Mnet::Log->new();

    # output to standard out and err is captured
    syswrite STDOUT, $text;
    syswrite STDERR, $text;

    # dbg entries
    DEBUG($text);
    $log->debug($text);

    # inf entries
    INFO($text);
    $log->info($text);

    # WRN entries
    WARN($text);
    $log->warn($text);

    # ERR entries
    #  note that eval warnings are output as normal
    #  evals can use local $SIG{__WARN__} = sub { die @_ };
    warn $text;
    die $text;

    # DIE entries
    FATAL($text);
    $log->fatal($text);

    # first line of first WRN/ERR/DIE entry
    $text = Mnet::Log::error();

DESCRIPTION

Mnet::Log supports generating the following types of log entries

    dbg   stdout   detailed info, visible when debug option is set
    inf   stdout   normal informational entries intended for users
    log   stdout   reserved for script start and finish log entries
    WRN   stderr   logged warning entries, execution will continue
    ERR   stderr   perl die and warn outputs with stack trace
    DIE   stderr   logged fatal errors, execution aborts

The following options can be used to control log outputs:

    debug   enable dbg log outputs
    quiet   disable all stdout log outputs
    silent  disable all stdout and stderr log outputs

Note that this module also installs __DIE__, __WARN__, INT, and TERM signal handlers, in order to augment the logging of these events. These are made so that compile and eval signals are processed by perl as normal.

Note that timestamps and other varying data are filtered out of log outputs when the --record, --replay, or --test cli options are enabled or if the Mnet::Log::Test module is otherwise loaded.

METHODS

Mnet::Log implements the methods listed below.

new

    $log = Mnet::Log->new(\%opts)

This class method creates a new Mnet::Log object. The opts hash ref argument is not requried but may be used to override any parsed cli options parsed with the Mnet::Opts::Cli module.

The returned object may be used to call other documented methods in this module.

The input opts hash ref may contain a log_id key which may be set to a device name or other identifier which will be prepended to all entries made using the returned Mnet::Log object. A warning will be issued if the log_id contains any spaces.

Refer to the SYNOPSIS section of this perldoc for more information.

Mnet::Log::error

    $error = Mnet::Log::error();

This function returns the first line of error text from the perl warn or die commands or Mnet::Log warn or fatal outputs.

A value of undefined is returned if there have not yet been any errors.

debug

    $log->debug($text)

Output a debug entry to stdout with an Mnet::Log prefix of dbg.

info

    $log->info($text)

Output an info entry to stdout with an Mnet::Log prefix of inf.

warn

    $log->warn($text)

Output a warn entry to stderr with an Mnet::Log prefix of WRN.

fatal

    $log->fatal($text)

Output a fatal entry to stderr with an Mnet::log prefix of DIE. Note that calls to fatal are handled in an eval the same as calls to die.

FUNCTIONS

Mnet::Log also implements the functions listed below.

DEBUG

    DEBUG($text)

Output a debug entry to stdout with an Mnet::Log prefix of dbg.

INFO

    INFO($text)

Output an info entry to stdout with an Mnet::Log prefix of inf.

WARN

    WARN($text)

Output a warn entry to stderr with an Mnet::Log prefix of WRN.

FATAL

    FATAL($text)

Output a fatal entry to stderr with an Mnet::Log prefix of DIE. Note that calls to fatal are handled in an eval the same as calls to die.

TESTING

When used with the Mnet::Test --record option all stdout and stderr log entry output from this module is captured with the exception of dbg and log entries.

Refer to the Mnet::Test module for more information.

SEE ALSO

Mnet

Mnet::Log::Test

Mnet::Opts::Cli

Mnet::Opts::Set::Debug

Mnet::Opts::Set::Quiet

Mnet::Opts::Set::Silent

Mnet::Tee

Mnet::Test

Mnet::Version