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

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

Using Alternate Loggers

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.

You can avoid trouble by logging to an alternate Log4perl logger without changing the default logger:

Activator::Log->DEBUG( $msg, 'My.Configured.Debug.Logger' );

Setting Log Level Dynamically

You can set the minimum level with the default_level sub:

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

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:
  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:

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.

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

NOTE TO SELF: create a test sub to make life easier

Setting the Default Logger

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>

Setting the Default Log Level

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

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:
  Log:
    DEBUG:
      'My::Module': 0    # My::Module will now prove "silence is bliss"

Turn debugging ON on a per-module basis

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, you can insure that the message appears to come from your module as such:

{
  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.