ePages 6.10 - DE_EPAGES/Core/API/Log.pm

Package DE_EPAGES::Core::API::Log

This module provides an interface for logging. It's actually a wrapper for the Log::Log4perl module.

Example
use DE_EPAGES::Core::API::Log qw( InitLog GetLog );
InitLog( '/etc/log4perl.conf' );
GetLog()->info( 'The logging system is initialized' );
; example appender log4perl.conf
log4perl.appender.error_log=DE_EPAGES::Core::API::Log4PerlFileAppender
log4perl.appender.error_log.filename=sub { join ('/', $ENV{'EPAGES_LOG'}, 'error.log'); }
log4perl.appender.error_log.layout=PatternLayout
log4perl.appender.error_log.layout.ConversionPattern=[%d PID:%P Type:%p %H:%Y] %c - logged at %F Line %L. %n%m%n
log4perl.appender.error_log.Threshold=ERROR
log4perl.category = ERROR, error_log
Possible placeholders at ConversionPattern are:
%c Category of the logging event.
%C Fully qualified package (or class) name of the caller
%d Current date in yyyy/MM/dd hh:mm:ss format
%F File where the logging event occurred
%H Hostname
%l Fully qualified name of the calling method followed by the
   callers source the file name and line number between
   parentheses.
%L Line number within the file where the log statement was issued
%m The message to be logged
%M Method or function where the logging request was issued
%n Newline (OS-independent)
%p Priority of the logging event
%P pid of the current process
%r Number of milliseconds elapsed from program start to logging
   event
%x The elements of the NDC stack (see below)
%X{key} The entry 'key' of the MDC (see below)
%% A literal percent (%) sign
@EXPORT_OK
GetAppender
GetCommunicationLog
GetLog
InitLog
LogCommunication
LogDebug
LogError
LogWarnings
TestLog
SetLogLevel

Functions

GetAppender
GetCommunicationLog
GetLog
InitLog
LogCommunication
LogDebug
LogError
LogWarnings
SetLogLevel
TestLog

GetAppender

Returns a log appender by name. The appender must be specified in the log4perl.conf file. Returns undef if the appender name is not found. The appender object supports the following methods:

(The function should not die, because it may be used inside an error handler)

Syntax
$Appender = GetAppender( $Name );
Example
my $Appender = GetAppender( 'error_log' );
if( defined $Appender ) {
    $Appender->log( message => 'An error occured while processing.' );
}
Input
$Name (string)
log appender name
Return
$Appender (object)
appender object, see perloc Log::Log4perl

GetCommunicationLog

Returns the logger for the "COMMUNICATION::$Category" category. See also GetLog.

Syntax
$Logger = GetCommunicationLog( $Category );
Example
GetCommunicationLog( 'Ebay' )->fatal( 'The Internet was switched off.' );
Input
$Category (string)
(optional) logger category
Return
$Appender (object)
logger object, see perloc Log::Log4perl

GetLog

Returns a logger for a category. If no category is specified, the caller package and function name is used as category. The logger object supports the following methods:

Syntax
$Logger = GetLog();
$Logger = GetLog( $Category );
Example
GetLog( 'WebInterface' )->fatal( 'The Internet was switched off.' );
Input
$Category (string)
logger category
Return
$Appender (object)
logger object, see perloc Log::Log4perl

InitLog

Initializes the logging system. See `perldoc Log::Log4perl` for the syntax of the configuration file.

Syntax
InitLog();
InitLog( $ConfigFile );
Example
InitLog( '/etc/log4perl.conf' );
Input
$ConfigFile (string)
configuration file name, see perldoc Log::Log4Perl for details
(optional, default: $ENV{'LOG4PERL'} || $ENV{'EPAGES_CONFIG'}/log4perl.conf)

LogCommunication

Dumps the data structure $rStructure to the log file if the log level for category $Category (or current package) is 'DEBUG'.

Syntax
LogCommunication( $Name, $rStructure, $Category );
LogCommunication( $Name, $rStructure, $Category, $aFilter, $CallerDepth);
Example
LogCommunication( 'TransReturn', $TransReturn, 'WorldPay::PaymentCallback', ['callbackPW']);
Input
$Name (string)
name of data structure for identification in the log file
$rStructure (scalar (usually hash or array ref))
the object
$Category (string)
debug category
$aFilter (ref.array.string)
(optional) filter (perl regular expression for
s/$Filter[^\n]+\n/\n/gis)
$CallerDepth (int)
(optional) number of caller functions to remove from the
stack trace

LogDebug

Dumps the data structure $rStructure to the log file if the log level for category $Category (or current package) is 'DEBUG'.

Syntax
LogDebug( $Name, $rStructure);
LogDebug( $Name, $rStructure, $Category );
Example
LogDebug( 'ProductInfo', \%ProductInfo, 'Product');
Input
$Name (string)
name of data structure for identification in the log file
$rStructure (scalar (usually hash or array ref))
the object
$Category (string)
debug category (default: calling package)

LogError

Writes an error to the log file.

Syntax
LogError( $Error );
Example
eval { ... };
if( ExistsError() ) {
    LogError( GetError() );
}
Input
$Error (object)
an error object

LogWarnings

Writes a warnings to the log file.

Syntax
LogWarnings( $aWarnings);
Example
LogWarnings( GetWarnings() );
Input
$aWarnings (ref.array.object)
warning objects

SetLogLevel

Set temporary log level for category $Category (or current package).

Syntax
SetLogLevel( $LevelString, $Sub, $Category );
Example
SetLogLevel( 'DEBUG', sub { GetLog->debug('hello'); });
Input
$LevelString (string)
name of level (DEBUG,WARN,ERROR,FATAL,INFO)
$Sub (ref.code)
code block
$Category (string)
debug category (default: calling package)

TestLog

Calls each log level (DEBUG, INFO, WARN, ERROR, FATAL) at log category 'BUGTRACKER::Log4perl'. This is useful to test the log4perl.conf.

Syntax
TestLog();
Example
perl -e "use DE_EPAGES::Core::API::Log qw (TestLog); TestLog();"