NAME

DiaColloDB::Logger - DiaColloDB logging (using Log::Log4perl)

SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::Logger;
 
 ##========================================================================
 ## Globals
 
 $DEFAULT_LOG_CONF = PACKAGE->defaultLogConf(%opts);
 $bool = CLASS::haveFileRotate();
 $bool = CLASS::haveSyslog();
 
 ##========================================================================
 ## Functions: Initialization
 
 undef = PACKAGE->logInit(%opts)  ##-- use default configuration with %opts;
 undef = PACKAGE->ensureLog(@args)        ##-- ensure a Log::Log4perl has been initialized;
 
 ##========================================================================
 ## Methods: get logger
 
 $logger = $class_or_obj->logger();
 
 ##========================================================================
 ## Methods: messages
 
 undef = $class_or_obj->trace(@msg);
 undef = $class_or_obj->llog($level, @msg);
 undef = $class_or_obj->vlog($methodname_or_coderef_or_undef, @msg);
 
 ##========================================================================
 ## Methods: carp & friends
 
 undef = $class_or_obj->logwarn(@msg);
 undef = $class_or_obj->logcarp(@msg);
 undef = $class_or_obj->logcluck(@msg);
 
 undef = $class_or_obj->logdie(@msg);
 undef = $class_or_obj->logcroak(@msg);
 undef = $class_or_obj->logconfess(@msg);
 
 ##========================================================================
 ## Utils: Getopt::Long specification
 
 %getoptLongHash = $PACKAGE->cldbLogOptions(%localOpts);
 
 ##========================================================================
 ## Utils: Profiling
 
 undef = $logger->logProfile($level, $elapsed_secs, $ntoks, $nchrs);
 

DESCRIPTION

Globals

Variable: $MIN_LEVEL

symbolic name of minimum log level (default = minimum-valued key of %Log::Log4perl::Level::LEVELS).

Variable: %defaultLogOpts

default log options.

defaultLogConf

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

Return default configuration for Log::Log4perl; see Log::Log4perl(3pm), Log::Log4perl::Config(3pm) for details.

%opts:

 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)
 logtime   => $bool,            ##-- whether to log time-stamps on stderr (default=0)
 logdate   => $bool,            ##-- whether to log date+time-stamps on stderr (default=0)
 logwhich  => \@classes,        ##-- log4perl-style classes to log (default=qw(DiaColloDB DocClassify DTA.CAB DTA.TokWrap))
 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')

haveFileRotate

 $bool = CLASS::haveFileRotate();

returns true if Log::Dispatch::FileRotate is available

haveSyslog

 $bool = CLASS::haveSyslog();

returns true if Log::Dispatch::Syslog is available

Functions: Initialization

logInit

 undef = PACKAGE->logInit(%opts)  ##-- use default configuration with %opts;

• %opts: see defaultLogConf()

• all log calls in the DiaColloDB namespace should use a subcategory of 'DiaColloDB'

• only needs to be called once; see Log::Log4perl->initialized()

ensureLog

 undef = PACKAGE->ensureLog(@args)

ensures that Log::Log4perl has been 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

 undef = $class_or_obj->trace(@msg);

Log::Log4perl wrappers. Be sure you have called Log::Log4perl::init() or similar first.

llog

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

Log at level $level, which should be some constant exported by Log::Log4perl::Level.

vlog

 undef = $class_or_obj->vlog($methodname_or_coderef_or_undef, @msg);

Log via $methodname_or_coderef_or_undef; calls $methodname_or_coderef_or_undef($class_or_obj,@msg) if defined, e.g.

 $class_or_obj->vlog('trace', @msg);

Methods: carp & friends

logwarn

logcarp

logcluck

logdie

logcroak

logconfess

 $class_or_obj->logwarn(@msg);

Wraps $class_or_obj->logger->logwarn(@msg), etc.

Utils: Getopt::Long specification

cldbLogOptions

 %getoptLongHash = $PACKAGE->cldbLogOptions(%localOpts);

Return Getopt::Long|Getopt::Long> option hash for common logging options.

%localOpts:

 verbose => $bool,   ##-- if true, add 'verbose|v' as alias for 'log-level'

Supports the following options:

 'log-level|loglevel|ll|L=s' => \$defaultLogOpts{level},
 'log-config|logconfig|log4perl-config|l4p-config|l4p=s' => \$defaultLogOpts{l4pfile},
 'log-watch|logwatch|watch|lw=i' => \$defaultLogOpts{watch},
 'nolog-watch|nologwatch|nowatch|nolw' => sub { $defaultLogOpts{watch}=undef; },
 'log-stderr|stderr|lse!' => \$defaultLogOpts{stderr},
 'log-file|lf=s' => \$defaultLogOpts{file},
 'nolog-file|nolf' => sub { $defaultLogOpts{file}=undef; },
 'log-rotate|rotate|lr!' => \$defaultLogOpts{rotate},
 'log-syslog|syslog|ls!' => \$defaultLogOpts{syslog},
 'log-option|logopt|lo=s' => \%defaultLogOpts,

Utils: Profiling

logProfile

 undef = $logger->logProfile($level, $elapsed_secs, $ntoks, $nchrs);

Produces a profiling string used by command-line utilities, logged at level $level via vlog().

AUTHOR

Bryan Jurish <moocow@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2015-2016 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.14.2 or, at your option, any later version of Perl 5 you may have available.

SEE ALSO

DiaColloDB(3pm), perl(1), ...