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

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.