/ 
Activator-0.90
River stage zero No dependents
/ Activator::Log

NAME

Activator::Log - provide a simple wrapper for Log::Log4perl for use within an Activator project.

SYNOPSIS

use Activator::Log;
Activator::Log::WARN( $msg );

use Activator::Log qw( :levels );
WARN( $msg );

#### Alternate log levels
Activator::Log->level( $level );

TODO: test that logger exists before logging. that is, fallback to warn or die or something.

DESCRIPTION

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.

Centralized Configuration

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.

See the section CONFIGURATION for more details.

Exporting Level Functions

Log::Log4perl logging functions are exported into the global namespace if you use the :levels tag

use Activator::Log qw( :levels );
&FATAL( $msg );
&ERROR( $msg );
&WARN( $msg );
&INFO( $msg );
&DEBUG( $msg );
&TRACE( $msg );

Static Usage

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

Setting Log Level Dynamically

You can set the minimum level with the level sub:

# only show only levels WARN, ERROR and FATAL
Activator::Log->level( 'WARN' ); 

# only show only levels ERROR and FATAL
Activator::Log->level( 'ERROR' );

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.

Additional Functionality provided

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.

CONFIGURATION

Log::Log4perl

Activator::Log looks in your Registry for a Log::Log4perl configuration in this heirarchy:

1) A 'log4perl.conf' file in the registry:

'Activator::Registry':
   log4perl.conf: <file>

2) A 'log4perl' config in the registry:

'Activator::Registry':
   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:

log4perl.logger.Activator.DB = 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.

NOTE 2: You must properly configure Log::Log4perl for this module!

Setting the Default Logger

Log4Perl can have multiple definitions for loggers. If your script or program has a preferred logger, set the Registry key 'logger':

'Activator::Registry':
   'Activator::Log':
     'logger': <logger name IN log4perl.conf>

Setting the Default Log Level

Set up your registry as such:

'Activator::Registry':
  'Activator::Log':
    default_level: LEVEL

Note that you can also initialize an instance of this module with the same affect:

Activator::Log->new( $level );

DISABLING DEBUG OR TRACE BY MODULE

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.

Turn debugging OFF on a per-module basis

'Activator::Registry':
   'Activator::Log':
     DEBUG:
       'My::Module': 0    # My::Module will now prove "silence is bliss"

Turn debugging ON on a per-module basis

'Activator::Registry':
   '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

Disabling Caveats

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.

USING THIS MODULE IN WRAPPERS

This module respects $Log::Log4perl::caller_depth. When using this module from a wrapper, please consult with Log4perl "Using Log::Log4perl from wrapper classes" in the Log4perl FAQ.