Michael Shipper
and 1 contributors

NAME

Log::LogMethods - Writes your logging code for you!

SYNOPSIS

  package test_moo;

  use Moo;
  BEGIN { with qw(Log::LogMethods) }
  sub test_always : BENCHMARK_ALWAYS { ...  }

  my $logger=Log::Log4perl->get_logger(__PACKAGE__);
  my $class=new test_moo(logger=>$logger);

Log4Perl Sugested PatternLayout

To get everything you were expecting from classes that extend this one, use the following PatternLayout:

  %H %P %d %p %f %k %S [%h] %s %b %j %B%n

The above format will produce logs like this:

  d00nappu0019 108201 2017/03/13 18:36:45 INFO t/Log-LogMethods.t 292 test_header::res_info [HEADER TEST] Starting 1
  d00nappu0019 108201 2017/03/13 18:36:45 ERROR t/Log-LogMethods.t 292 test_header::res_info [HEADER TEST] error message 1 
  d00nappu0019 108201 2017/03/13 18:36:45 INFO t/Log-LogMethods.t 292 test_header::res_info [HEADER TEST] Finished 1 elapsed 0.000362

Log4Perl Custom PatternLayouts

Since log4perl can get pertty confused with what the (package::method and line) number should be from Log::LogMethods, the following Custom PatternLayout have been added:

  +------------------------------------------------------+
  | Layout | Replaces | Description                      |
  +--------+----------+----------------------------------+
  | %f     |   %F     | File the alert came from         |
  | %s     |   %m     | actual Message                   |
  | %k     |   %L     | Line Number ( if any )           |
  | %S     |          | fully qualified package::method  |
  | %v     |   %C     | package                          |
  +--------+----------+----------------------------------+

Special case PatternLayouts

  +--------+----------------------------------------+
  | %h     | Log Header value ( if any )            |
  | %b     | Benchmark recursion_level              |
  | %B     | Benchmaked time in microseconds        |
  | %j     | set to "elapsed" for benchmark methods |
  +--------+----------------------------------------+

DESCRIPTION

This library provides a common logging interfcaes that expects: Log::Log4perl::Logger or something that extends those features.

Get and set log levels

If you want to manualy get/set log levels

  use Log::Log4perl::Level;

  if($self->level!=$WARN) { $self->level($WARN) }

OO Methods provided

This class adds the following arguments and accessors to any class that loads using 'with';

  logger:  DOES(Log::Log4perl::Logger)

When the object DOES Log::Log4perl::Logger, the correct Log::Log4perl->get_logger(__PACKAGE__) call will be done. If you wish to modify the logger method, use an around declaration. This will keep the trigger $self->_trigger_logger($logger|undef) in tact.

Example:

  around logger=>sub {
    my ($code,$self,$logger)=@_;

    if(defined($logger)) {

      # Do something here
      return $org->($self,$logger);
    } else {
      return $org->($self);
    }
  };
  • $self->log_error("Some error");

    This is a lazy man's wrapper function for

      my $log=$self->logger;
      $log->log_error("Some error") if $log; 
  • $log->log_die("Log this and die");

    Logs the given message then dies.

  • $self->log_always("Some msg");

    This is a lazy man's wrapper function for

      my $log=$self->logger;
      $log->log_always("Some msg") if $log; 
  • my $string=$self->log_header;

    This is a stub function that allows a quick addin for logging, the string returned will be inserted after the log_level in the log file if this function is created.

  • $self->log_warn("Some msg");

    This is a lazy man's wrapper function for:

      my $log=$self->logger;
      $log->log_warn("Some msg") if $log; 
  • $self->log_info("Some msg");

    This is a lazy man's wrapper function for:

      my $log=$self->logger;
      $log->log_info("Some msg") if $log; 
  • $self->log_debug("Some msg");

    This is a lazy man's wrapper function for:

      my $log=$self->logger;
      $log->log_debug("Some msg") if $log; 

ATTRIBUTES

Logging attributes can be set for a given function. All logging wrappers autmatically log failed Data::Result objects as log_level ERROR.

BASIC WRAPPERS

These attributes provide the baseic Starting and Ending log entries for a given function.

  • sub some_method : RESULT_ALWAYS { ... }

    Will always produce a start and end log entry

  • sub some_method : RESULT_ERROR { ... }

    Will always produce a starting and ending log entry at log level ERROR.

  • sub some_method : RESULT_WARN { ... }

    Will always produce a starting and ending log entry at log level WARN.

  • sub some_method : RESULT_INFO { ... }

    Will always produce a starting and ending log entry at log level INFO.

  • sub some_method : RESULT_DEBUG { ... }

    Will always produce a starting and ending log entry at log level DEBUG.

BENCHMARKING

Functions can be declared with a given benchmark method.

  • BENCHMARK_INFO

    Declares Start and End log entries for the given function, along with a benchmark timestamp. Benchmark time differences are in microseconds.

  • sub method : BENCHMARK_ALWAYS { ... }

    Always benchmark this method.

  • sub method : BENCHMARK_ERROR { ... }

    Only benchmark this function if log level is >= ERROR

  • sub method : BENCHMARK_WARN { ... }

    Only benchmark this function if log level is >= WARN

  • sub method : BENCHMARK_INFO { ... }

    Only benchmark this function if log level is >= INFO

  • sub method : BENCHMARK_DEBUG { ... }

    Only benchmark this function if log level is >= DEBUG

INTERNAL METHODS

This section documents internal methods.

  • $self->MODIFY_CODE_ATTRIBUTES($code,$att)

    Method that generates the wrapper funcitons.

    Attrivutes:

      code: glob to overwrite
      att:  The Attribute being overwritten
  • $self->_attribute_result_common( $stack,$level,$code );

    Compile time code, generates basic Startin Finsihed log messages for a given "LEVEL" and also creates ERROR Log entries if the object returned DOES('Data::Result') and is in an error state.

    Arguments:

      stack: stack hashref
      level: level(WARN|ALWAYS|INFO|ERROR|TRACE|DEBUG)
      code:  code ref to replcae
  • $self->_attribute_benchmark_common( $stack,$level,$code);

    Compile time code, generates Benchmarking log for a given function: Startin Finsihed log messages for a given "LEVEL" and also creates ERROR Log entries if the object returned DOES('Data::Result') and is in an error state.

    Arguments:

      stack: stack hashref
      level: level(WARN|ALWAYS|INFO|ERROR|TRACE|DEBUG)
      code:  code ref to replcae
  • $self->log_to_log4perl($level,$stack,@args)

    Low level Automatic logger selection.

    Arguments:

      level: Log level (ALWAYS|ERROR|WARN|INFO|DEBUG)
      stack: number or hashref $trace
      args:  argument list for logging
  • $self->data_result_auto_log_error($stack,$result);

    Creates a required log entry for a false Data::Result object

    Arguments:

      stack:  level or $trace
      result: Object, if DOES('Data::Result') and !$result->is_true a log entry is created
  • my $strace=$self->strack_trace_to_level($number)

    Given the number, trturns the currect $trace

    trace

      sub:      Name of the function
      filename: source file
      package:  Package name
      line:     Line number
  • if($self->log_to_log4perl($level,$trace,@args)) { ... }

    Low Level check and log to log4perl logger object

    Arguments:

      level: Log Level (ALWAYS|ERROR|WARN|INFO|DEBUG) 
      trace: level number or $trace
      args:  list of strings to log

Method Generation

This section documents the code generation methods

  • $self->_create_is_check($name,$level)

    Generates the "is_xxx" method based on $name and $level.

    Argumetns:

      name:  Human readable word such as: DEBUG
      level: Levels come from Log::Log4perl::Level
  • $self->_create_logging_methods($name,$level)

    Generates the logging methods based on $name and $level.

    Argumetns:

      name:  Human readable word such as: DEBUG
      level: Levels come from Log::Log4perl::Level

log level checks

The logging and is_xxx methods are auto generated based on the key/value pairs in %Log::LogMethods::LEVEL_MAP.

  • if($self->is_always) { ... }

  • if($self->is_error) { ... }

  • if($self->is_warning) { ... }

  • if($self->is_info) { ... }

  • if($self->is_debug) { ... }

  • if($self->is_default_debug) { ... }

  • if($self->is_trace) { ... }

Logging methods

The following methods are autogenerated based on the key/value pairs in %Log::LogMethods::LEVEL_MAP.

  • $self->always("Some log entry")

  • $self->error("Some log entry")

  • $self->warning("Some log entry")

  • $self->info("Some log entry")

  • $self->debug("Some log entry")

  • $self->default_debug("Some log entry")

  • $self->trace("Some log entry")

AUTHOR

Mike Shipper <AKALINUX@CPAN.ORG>