/ 
DTA-CAB-1.115
River stage zero No dependents
/ DTA::CAB::Logger

NAME

DTA::CAB::Logger - DTA::CAB logging facility using Log::Log4perl

SYNOPSIS

use DTA::CAB::Logger;

##========================================================================
## Gobals

$DTA::CAB::Logger::defaultLogOpts{$opt} = $val;
$DTA::CAB::Logger::MIN_LEVEL = $min_log_level;

##========================================================================
## Functions: Initialization

DTA::CAB::Logger->logInit(%opts);
DTA::CAB::Logger->ensureLog(%opts);
$DEFAULT_LOG_CONF = DTA::CAB::Logger->defaultLogConf(%opts)
$bool = $CLASS_OR_OJECT->logInitialized();

##========================================================================
## Methods: get logger

$logger = $class_or_obj->logger();

##========================================================================
## Methods: messages

$class_or_obj->trace (@msg);  ##-- 'TRACE'-level message
$class_or_obj->debug (@msg);  ##-- 'DEBUG'-level message
$class_or_obj->info  (@msg);  ##-- 'INFO'-level message
$class_or_obj->warn  (@msg);  ##-- 'WARN'-level message
$class_or_obj->error (@msg);  ##-- 'ERROR'-level message
$class_or_obj->fatal (@msg);  ##-- 'FATAL'-level message

$class_or_obj->llog($level, @msg);  ##-- variable-level message (numeric)
$class_or_obj->vlog($how,   @msg);  ##-- variable-level message (symbolic)

##========================================================================
## Methods: carp, croak & friends

$class_or_obj->logwarn  (@msg);   ##-- warn w/o stack trace
$class_or_obj->logcarp  (@msg);   ##-- warn w/ 1-level stack trace
$class_or_obj->logcluck (@msg);   ##-- warn w/ full stack trace

$class_or_obj->logdie    (@msg);  ##-- die w/o stack trace
$class_or_obj->logcroak  (@msg);  ##-- die w/ 1-level stack trace
$class_or_obj->logconfess(@msg);  ##-- die w/ full stack trace

DESCRIPTION

DTA::CAB::Logger provides an abstract base class for object-oriented access to the Log::Log4perl logging facility.

Globals

$DTA::CAB::Logger::MIN_LEVEL

Minimum log level. Default is minimum-keyed value in %LOG::Log4perl::Level::LEVELS if $^W is set, otherwise 'INFO'.

%DTA::CAB::Logger::defaultLogOpts

Default logging options. See defaultLogConf().

Functions: Initialization

logInit
$PACKAGE->logInit(%opts)

Initialize the logging facility.

%opts:

l4pfile   => undef,            ##-- alternate Log4perl config file
watch     => undef,            ##-- watch l4pfile (SECONDS delay or SIGNAL)? (default=undef: false)
rootLevel => $LEVEL_OR_UNDEF,  ##-- min root log level (default='WARN' or 'FATAL', depending on $^W)
level     => $LEVEL_OR_UNDEF,  ##-- min log level (default=$MIN_LEVEL or 'INFO', depending on $^W)
stderr    => $bool,            ##-- whether to log to stderr (default=1)
file      => $filename,        ##-- log to $filename if true
rotate    => $bool,            ##-- use Log::Dispatch::FileRotate if available and $filename is true
syslog    => $bool,            ##-- use Log::Dispatch::Syslog if available and true (default=false)
sysLevel  => $level,           ##-- minimum level for syslog (default='debug' or 'info', depending on $^W)
                               ##   available levels: debug,info,notice,warning,error,critical,alert,emergency (== 0..7)
sysName   => $sysName,         ##-- name for syslog (default=basename($0))
sysIdent  => $sysIdent,        ##-- ident string for syslog (default=$sysName)
sysFacility => $facility,      ##-- facility for syslog (default='daemon')

All log calls in the 'DTA::CAB' namespace should use a subcategory of 'DTA::CAB'. This function only needs to be called once; see Log::Log4perl->initialized() for details.

ensureLog
PACKAGE->ensureLog(%opts)

Ensures that Log::Log4perl has been initialized.

defaultLogConf
$DEFAULT_LOG_CONF = PACKAGE->defaultLogConf(%opts)

Returns default Log::Log4perl configuration string for %opts.

logInitialized
$bool = CLASS_OR_OBJECT->logInitialized();

Wrapper for Log::Log4perl->initialized().

Methods: get logger

logger
$logger = $class_or_obj->logger();
$logger = $class_or_obj->logger($category)

Wrapper for Log::Log4perl::get_logger($category).

$category defaults to ref($class_or_obj)||$class_or_obj

Methods: messages

trace
debug
info
warn
error
fatal
$class_or_obj->trace (@msg);  ##-- 'TRACE'-level message
$class_or_obj->debug (@msg);  ##-- 'DEBUG'-level message
$class_or_obj->info  (@msg);  ##-- 'INFO'-level message
$class_or_obj->warn  (@msg);  ##-- 'WARN'-level message
$class_or_obj->error (@msg);  ##-- 'ERROR'-level message
$class_or_obj->fatal (@msg);  ##-- 'FATAL'-level message

Log messages at an explicit log-level.

Be sure you have called Log::Log4perl::init() or similar first, e.g. DTA::CAB::Logger::logInit().

llog
$class_or_obj->llog($level, @msg);

Log message @msg at log-level $level, which should be a (numeric) constant exported by Log::Log4perl::Level.

vlog
$class_or_obj->vlog($how, @msg);

Log message @msg at log-level $how, which may be one of the following:

  • a CODE reference (e.g. $how=\&logsub) will cause $how->($class_or_obj,@msg) to be called.

  • a method name (e.g. $how='trace') will case calls $class_or_obj->${how}(@msg) to be called.

  • anything else (e.g. $how='none', $how=undef, ...) will be ignored.

Methods: carp, croak & friends

logwarn
logcarp
logcluck
$class_or_obj->logwarn  (@msg);   ##-- warn w/o stack trace
$class_or_obj->logcarp  (@msg);   ##-- warn w/ 1-level stack trace
$class_or_obj->logcluck (@msg);   ##-- warn w/ full stack trace
logdie
logcroak
logconfess
$class_or_obj->logdie    (@msg);  ##-- die w/o stack trace
$class_or_obj->logcroak  (@msg);  ##-- die w/ 1-level stack trace
$class_or_obj->logconfess(@msg);  ##-- die w/ full stack trace

AUTHOR

Bryan Jurish <moocow@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2009-2019 by Bryan Jurish

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.24.1 or, at your option, any later version of Perl 5 you may have available.