view release on metacpan or  search on metacpan

lib/Activator/Log.pm  view on Meta::CPAN

  WARN( $msg );

  #### Use alternate default log levels
  Activator::Log->default_level( $level );

  #### Use alternate default loggers
  Activator::Log->default_logger( $logger_name );

=head1 DESCRIPTION

This module provides a simple wrapper for L<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, C<TRACE> and C<DEBUG> functions have the extra
capabilities to turn logging on and off on a per-module basis. See the
section L<DISABLING DEBUG OR TRACE BY MODULE> for more information.

=head2 Centralized Configuration

Your project C<log4perl.conf> gets loaded based on your
L<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 L<CONFIGURATION> for more details.

=head2 Exporting Level Functions

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

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

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

=head2 Using Alternate Loggers

You can set the default logger dynamically:

  Activator::Log->default_logger( 'My.Default.Logger' );

Note that since C<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' );

=head2 Setting Log Level Dynamically

You can set the minimum level with the C<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 C<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.

=head2 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 L<Log::Log4perl> documentation for more details.

=head1 CONFIGURATION

=head2 Log::Log4perl

Activator::Log looks in your Registry for a L<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, C<Activator::Log> defaults to showing WARN level to
C<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 C<log4perl.conf> or C<log4perl> is set, it is possible you
will see no logging since L<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 L<Log::Log4perl> for this module!