Activator::Log - provide a simple wrapper for Log::Log4perl for use within an Activator project.
use Activator::Log; Activator::Log::WARN( $msg ); # logs to default logger Activator::Log->WARN( $msg, $other_logger ); # logs to other logger, don't change default # NOTE: you MUST use arrow notation! use Activator::Log qw( :levels ); WARN( $msg ); #### Use alternate default log levels Activator::Log->default_level( $level ); #### Use alternate default loggers Activator::Log->default_logger( $logger_name );
This module provides a simple wrapper for Log::Log4perl that allows you to have a project level configuration for Log4perl, and have any class or script in your project be configured and output log messages in a consistent centralized way.
Additionally, TRACE and DEBUG functions have the extra capabilities to turn logging on and off on a per-module basis. See the section "DISABLING DEBUG OR TRACE BY MODULE" for more information.
TRACE
DEBUG
Your project log4perl.conf gets loaded based on your Activator::Registry configuration. If you do not have a Log4perl config available, the log level is set to WARN and all output goes to STDERR.
log4perl.conf
See the section CONFIGURATION for more details.
Log::Log4perl logging functions are exported into the global namespace if you use the :levels tag
:levels
use Activator::Log qw( :levels ); &FATAL( $msg ); &ERROR( $msg ); &WARN( $msg ); &INFO( $msg ); &DEBUG( $msg ); &TRACE( $msg );
You can always make static calls to this class no matter how you 'use' this module:
Activator::Log->FATAL( $msg ); Activator::Log->ERROR( $msg ); Activator::Log->WARN( $msg ); Activator::Log->INFO( $msg ); Activator::Log->DEBUG( $msg ); Activator::Log->TRACE( $msg );
You can set the default logger dynamically:
Activator::Log->default_logger( 'My.Default.Logger' );
Note that since Activator::Log is a singleton, this sub will set the level for the entire process. This is probably fine for cron jobs, not so good for web processes.
Activator::Log
You can avoid trouble by logging to an alternate Log4perl logger without changing the default logger:
Activator::Log->DEBUG( $msg, 'My.Configured.Debug.Logger' );
You can set the minimum level with the default_level sub:
default_level
# only show only levels WARN, ERROR and FATAL Activator::Log->default_level( 'WARN' ); # only show only levels ERROR and FATAL Activator::Log->default_level( 'ERROR' );
The following Log::Log4perl subs you would normally call with $logger->SUB are supported through a static call:
Activator::Log->logwarn( $msg ); Activator::Log->logdie( $msg ); Activator::Log->error_warn( $msg ); Activator::Log->error_die( $msg ); Activator::Log->logcarp( $msg ); Activator::Log->logcluck( $msg ); Activator::Log->logcroak( $msg ); Activator::Log->logconfess( $msg ); Activator::Log->is_trace() Activator::Log->is_debug() Activator::Log->is_info() Activator::Log->is_warn() Activator::Log->is_error() Activator::Log->is_fatal()
See the Log::Log4perl documentation for more details.
Activator::Log looks in your Registry for a Log::Log4perl configuration in this heirarchy:
1) A 'log4perl.conf' file in the registry:
Activator: Log: log4perl.conf: <file>
2) A 'log4perl' config in the registry:
Activator: Log: log4perl: 'log4perl.key1': 'value1' 'log4perl.key2': 'value2' ... etc.
3) If none of the above are set, Activator::Log defaults to showing WARN level to STDERR as shown in this log4perl configuration:
STDERR
log4perl.logger.Activator.Log = WARN, Screen log4perl.appender.Screen = Log::Log4perl::Appender::Screen log4perl.appender.Screen.layout = Log::Log4perl::Layout::PatternLayout log4perl.appender.Screen.layout.ConversionPattern = %d{yyyy-mm-dd HH:mm:ss.SSS} [%p] %m (%M %L)%n
NOTE: If log4perl.conf or log4perl is set, it is possible you will see no logging since Log::Log4perl by default doesn't log anything. That is, you could have configured this module properly, but still see no logging.
log4perl
NOTE 2: You must properly configure Log::Log4perl for this module!
NOTE TO SELF: create a test sub to make life easier
Log4Perl can have multiple definitions for loggers. If your script or program has a preferred logger, set the Registry key c<default_logger>:
Activator: Log: default_logger: <logger name IN log4perl.conf>
Set up your registry as such:
Activator: Log: default_level: LEVEL
Note that you can also initialize an instance of this module with the same affect:
Activator::Log->new( $level );
By default, this module will print all DEBUG and TRACE log messages provided that the current log level is high enough. However, when developing it is convenient to be able to turn debugging/tracing on and off on a per-module basis. The following examples show how to do this.
Activator: Log: DEBUG: 'My::Module': 0 # My::Module will now prove "silence is bliss"
Activator: Log: DEBUG: FORCE_EXPLICIT: 1 'My::Module': 1 # only My::Module messages will be debugged TRACE: FORCE_EXPLICIT: 1 'Other::Module': 1 # only Other::Module messages will be traced
Note that the entire Activator framework uses this module, so use FORCE_EXPLICIT with caution, as you may inadvertantly disable logging from a package you DO want to hear from.
This module respects $Log::Log4perl::caller_depth. When using this module from a wrapper, you can insure that the message appears to come from your module as such:
$Log::Log4perl::caller_depth
{ local $Log::Log4perl::caller_depth; $Log::Log4perl::caller_depth += $depth; Debug( 'some message' ); }
You'll likely want to do this in a sub routine if you do a lot of logging.
See also the full description of this technique in "Using Log::Log4perl from wrapper classes" in the Log4perl FAQ.
To install Activator, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Activator
CPAN shell
perl -MCPAN -e shell install Activator
For more information on module installation, please visit the detailed CPAN module installation guide.