view release on metacpan or  search on metacpan

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

    &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!

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

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

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

=head1 DISABLING DEBUG OR TRACE BY MODULE

By default, this module will print all C<DEBUG> and C<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.

=head2 Turn debugging OFF on a per-module basis

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

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

=head2 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.

=head1 USING THIS MODULE IN WRAPPERS

This module respects C<$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.

=cut

# constructor: implements singleton
sub new {
    my ( $pkg, $level ) = @_;

    my $self = bless( { }, $pkg);

    $self->_init_StrongSingleton();

    if ( Log::Log4perl->initialized() ) {
	# do nothing, logger already set
    }
    else {

	# old config format
	my $config =
	  Activator::Registry->get('Activator::Log') || 
	      Activator::Registry->get('Activator->Log');

	$self->{DEFAULT_LEVEL} =
	  $level ||
	    $config->{default_level} ||
	      'WARN';

	$l4p_config = $ENV{ACT_LOG_log4perl} ||
	  Activator::Registry->get('log4perl.conf') ||
	      Activator::Registry->get('log4perl') ||
		  $config->{'log4perl.conf'} ||
		    $config->{'log4perl'} ||
		      { 'log4perl.logger.Activator.Log' => 'ALL, DEFAULT',
			'log4perl.appender.DEFAULT' => 'Log::Log4perl::Appender::Screen',
			'log4perl.appender.DEFAULT.layout' => 'Log::Log4perl::Layout::PatternLayout',

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

    my $self = &new( 'Activator::Log' );
    $level = &_get_static_arg( $pkg, $level );
    $self->{DEFAULT_LOGGER}->level( $level );
}

sub default_logger {
    my ( $pkg, $logger ) = @_;
    my $self = &new( 'Activator::Log' );
    $logger = &_get_static_arg( $pkg, $logger );
    $self->{DEFAULT_LOGGER} = Log::Log4perl->get_logger( $logger )
}

sub FATAL {
    my ( $pkg, $msg, $logger_label ) = @_;
    my $self = &new( 'Activator::Log' );
    $msg = &_get_static_arg( $pkg, $msg );
    my $logger = $self->{DEFAULT_LOGGER};
    if ( $logger_label ) {
	$logger = Log::Log4perl->get_logger( $logger_label );
    }
    $logger->fatal( $msg );
}

sub ERROR {
    my ( $pkg, $msg, $logger_label ) = @_;
    my $self = &new( 'Activator::Log' );
    $msg = &_get_static_arg( $pkg, $msg );
    my $logger = $self->{DEFAULT_LOGGER};
    if ( $logger_label ) {
	$logger = Log::Log4perl->get_logger( $logger_label );
    }
    $logger->error( $msg );
}
 
sub WARN {
    my ( $pkg, $msg, $logger_label ) = @_;
    my $self = &new( 'Activator::Log' );
    $msg = &_get_static_arg( $pkg, $msg );
    my $logger = $self->{DEFAULT_LOGGER};
    if ( $logger_label ) {
	$logger = Log::Log4perl->get_logger( $logger_label );
    }
    $logger->warn( $msg );
}

sub INFO {
    my ( $pkg, $msg, $logger_label ) = @_;
    my $self = &new( 'Activator::Log' );
    $msg = &_get_static_arg( $pkg, $msg );
    my $logger = $self->{DEFAULT_LOGGER};
    if ( $logger_label ) {
	$logger = Log::Log4perl->get_logger( $logger_label );
    }
    $logger->info( $msg );
}

sub DEBUG {
    my ( $pkg, $msg, $logger_label ) = @_;
    my $caller = caller;
    my $self = &new( 'Activator::Log' );
    my $debug = &_enabled( 'DEBUG', $caller );
    if ( $debug ) {
       $msg = _get_static_arg( $pkg, $msg );
       my $logger = $self->{DEFAULT_LOGGER};
       if ( $logger_label ) {
	   $logger = Log::Log4perl->get_logger( $logger_label );
       }
       $logger->debug( $msg );
   }
}

sub TRACE {
    my ( $pkg, $msg, $logger_label ) = @_;
    my $caller = caller;
    my $self = &new( 'Activator::Log' );
    my $trace = &_enabled( 'TRACE', $caller );
    if ( $trace ) {
       $msg = _get_static_arg( $pkg, $msg );
       my $logger = $self->{DEFAULT_LOGGER};
       if ( $logger_label ) {
	   $logger = Log::Log4perl->get_logger( $logger_label );
       }
       $logger->trace( $msg );
   }
}


sub is_fatal {
    my $self = &new( 'Activator::Log' );
    return $self->{DEFAULT_LOGGER}->is_fatal();
}

sub is_error {
    my $self = &new( 'Activator::Log' );
    return $self->{DEFAULT_LOGGER}->is_error();
}

sub is_warn {
    my $self = &new( 'Activator::Log' );
    return $self->{DEFAULT_LOGGER}->is_warn();
}

sub is_info {
    my $self = &new( 'Activator::Log' );
    return $self->{DEFAULT_LOGGER}->is_info();
}

sub is_debug {
    my $self = &new( 'Activator::Log' );
    return $self->{DEFAULT_LOGGER}->is_debug();
}

sub is_trace {
    my $self = &new( 'Activator::Log' );
    return $self->{DEFAULT_LOGGER}->is_trace();
}

sub logwarn {
    my ( $pkg, $msg ) = @_;
    my $self = &new( 'Activator::Log' );
    $msg = &_get_static_arg( $pkg, $msg );
    $self->{DEFAULT_LOGGER}->logwarn( $msg );
}

sub logdie {
    my ( $pkg, $msg ) = @_;
    my $self = &new( 'Activator::Log' );
    $msg = &_get_static_arg( $pkg, $msg );
    $self->{DEFAULT_LOGGER}->logdie( $msg );
}

sub error_warn {
    my ( $pkg, $msg ) = @_;
    my $self = &new( 'Activator::Log' );
    $msg = &_get_static_arg( $pkg, $msg );
    $self->{DEFAULT_LOGGER}->error_warn( $msg );
}

sub error_die {
    my ( $pkg, $msg ) = @_;
    my $self = &new( 'Activator::Log' );
    $msg = &_get_static_arg( $pkg, $msg );
    $self->{DEFAULT_LOGGER}->error_die( $msg );
}

sub logcarp {
    my ( $pkg, $msg ) = @_;
    my $self = &new( 'Activator::Log' );
    $msg = &_get_static_arg( $pkg, $msg );B
    $self->{DEFAULT_LOGGER}->logcarp( $msg );
}

sub logcluck {
    my ( $pkg, $msg ) = @_;
    my $self = &new( 'Activator::Log' );
    $msg = &_get_static_arg( $pkg, $msg );
    $self->{DEFAULT_LOGGER}->logcluck( $msg );
}

sub logcroak {
    my ( $pkg, $msg ) = @_;
    my $self = &new( 'Activator::Log' );
    $msg = &_get_static_arg( $pkg, $msg );
    $self->{DEFAULT_LOGGER}->logcroak( $msg );
}

sub logconfess {
    my ( $pkg, $msg ) = @_;
    my $self = &new( 'Activator::Log' );
    $msg = &_get_static_arg( $pkg, $msg );