ePages 7.17.0 - 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
GetCountLog
GetLog
InitLog
LogCommunication
LogDebug
LogError
LogWarnings
TestLog
SetLogLevel
LogContext

Functions

GetAppender
GetCommunicationLog
GetCountLog
GetLog
InitLog
LogCommunication
LogContext
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

GetCountLog

Returns the logger for the "COUNT::$Category" category. That category has been created to address the need explained in EPG-18496, which is keeping track of certain clicks which are relevant for business reasons. It might also be used to keep track of other things. See also GetLog.

Syntax
$Logger = GetCountLog( $Category );
Example
GetCountLog( 'Bla' )->fatal( 'negative count?' );
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 OR ref.code)
(optional) filter (perl regular expression for
s/$Filter[^\n]+\n/\n/gis)
OR
(optional) a function pointer like
sub {my $LogString = shift; $$LogString =~s/(?)[^)/---replaced---/xgis;}
$CallerDepth (int)
(optional) number of caller functions to remove from the
stack trace
Return
nothing (nothing)
nothing

LogContext

Adds context variables to NDC stack used by the log4perl framework. In addition to simple NDC, this is not limited to simple strings, and can be composed. Inside log4perl this is used as %x, and will use json for serialization of the context hash.

Syntax
LogContext( $hContext, $cSub );
Example
LogContext({Store => $Store}, sub {
  my $iShops = LoadRootObject->child('Shops')->childrenIterator;
  while( my $Shop = <$iShops> ) {
    LogContext({Shop => $Shop->alias}, sub {
      # contains Store:X,Shop:Y in %x
      GetLog->debug('simple logging..')
    });
  }
});
Input
$hContext (ref.hash)
context hash
$cSub (ref.sub)
code to run

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)
Return
nothing (nothing)
nothing

LogError

Writes an error to the log file.

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

LogWarnings

Writes a warnings to the log file.

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

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();"