view release on metacpan or  search on metacpan

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

package Activator::Log;

require Exporter;
push @ISA, qw( Exporter );
@EXPORT_OK = qw( FATAL ERROR WARN INFO DEBUG TRACE );
%EXPORT_TAGS = ( levels => [ qw( FATAL ERROR WARN INFO DEBUG TRACE ) ] );

use Log::Log4perl;
use Scalar::Util;
use Data::Dumper;
use Activator::Registry;
use base 'Class::StrongSingleton';

=head1 NAME

Activator::Log - provide a simple wrapper for L<Log::Log4perl> for use
within an Activator project.

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

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