/ 
Activator-0.10
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 );

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

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 STDERR exactly as shown below.

Note that even if log4perl.conf or log4perl is set, Log::Log4perl by default doesn't log anything. You must properly configure it for this module. As an example, the (hash format) configuration used by this module for logging to STDERR (#4 above) is:

'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',

Consult with Log::Log4perl documentation for more information on how to create the log4pler.conf file, or the log4perl registry entry.

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.