view release on metacpan or  search on metacpan

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

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',
			'log4perl.appender.DEFAULT.layout.ConversionPattern' => '%d{yyyy-MM-dd HH:mm:ss.SSS} [%p] %m (%M %L)%n',
		      };

	Log::Log4perl->init_once( $l4p_config );
	if ( !Log::Log4perl->initialized() ) {
	    warn( "ERROR: Activator::Log couldn't initialize logger with config $l4p_config");
	}