NAME

Log::ger - A lightweight, flexible logging framework

VERSION

version 0.001

SYNOPSIS

In your module (producer):

 package Foo;
 use Log::ger; # will import some logging methods e.g. log_warn, log_error

 # produce some logs
 sub foo {
     ...
     log_warn "an error occurred";
     log_error "an error occurred: %03d - %s", $errcode, $errmsg;
 }
 1;

In your application:

 use Foo;
 use Log::ger::Output::Screen;

 foo();

DESCRIPTION

EARLY RELEASE, EXPERIMENTAL.

This is yet another logging framework. Like Log::Any, it separates producers and consumers. Unlike Log::Any (and like Log::Contextual), it uses plain functions (non-OO). Some features:

• Low startup overhead;

• Low overhead;

• Customizable levels;

• Changing levels and outputs during run-time;

  For example, you can debug your running server application to turn on trace logs temporarily when you need to investigate something.

• Option to optimize away the logging statements when unnecessary;

  See Log::ger::Import::OptAway.

• Interoperability with other logging frameworks;

  See Log::ger::Import::LogAny to interop with Log::Any.

INTERNALS

Hooks

Hooks are how Log::ger provides its flexibility. A hook is passed a hash argument and is expected to return an array:

 [$err*, ...]

$err is a string and can be set to "" to signify success or a non-empty error message to signify error. Log::ger usually dies after a hook returns error.

Create_Log_Routine hook

Used to create "log_level" routines.

Arguments received: name (name of subroutine, e.g. log_warn), level (numeric level), package, prev (coderef).

Expected return:

 [$err*, $code, $continue]

Hook that wants to decline can return undef in $code. Log::ger will stop after the hook that produces a non-undef code unless when set to $continue 1 then Log::ger will continue to the next hook and passing the code to prev to allow onion-style nesting of code.

Create_Log_Is_Routine hook

Used to create "log_level" routines.

Install_Routine hook

Used to install to the caller (log producer) package.

Arguments: package (target package to install to), name (routine name), code (routine code), level (the numeric level of the routine).

Expected return:

 [$err*, $installed]

$installed can be set to 1 to signify that the hook has installed the routine, so Log::err will stop. Otherwise, Log::ger will try the next hook.

Plans

• Multiple loggers

  To support logging to two+ different loggers in the same producer package, a la in Log::Any:

   $log->debugf("Headers is: %s", $http_res->{headers});
   $log_dump->debug($http_res->{content});

  we can do something like (XXX find a more appropriate name):

   my $log      = Log::ger::install_to_object(...); # instead of installing to package
   my $log_dump = Log::ger::install_to_object(...); # or perhaps install to hash?
   $log->log_debug(...);
   $log_dump->log_debug(...);

• Custom formatting

  For example, a la Log::Contextual:

   log_warn { 'The number of stuffs is: ' . $obj->stuffs_count };

• Multiple outputs, filtering based on category

  With the exception of the default/null routines (and perhaps the simple Screen output too), the other logging routines should be constructed using a code generation approach so we can have multiple outputs, etc.

SEE ALSO

Some other recommended logging frameworks: Log::Any, Log::Contextual.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Log::ger

perl -MCPAN -e shell
install Log::ger