The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Log-ger-Manual-0.015
River stage one • 1 direct dependent • 1 total dependent
3 ++
/ Log::ger::Manual::FAQ

NAME

Log::ger::Manual::FAQ - FAQ on Log::ger

VERSION

version 0.015

GENERAL

How to use OO style?

The default in Log::ger is to use procedural style:

 use Log::ger;

 log_warn("blah");
 if (log_is_debug()) {
     log_debug("Format: %s %s", "blah ...", {data=>'structure'});
 }

However, you can also use objects:

 use Log::ger (); # don't initialize and export logger subroutines
 my $log = Log::ger->get_logger;
 $log->warn("blah");
 if ($log->is_debug) {
     $log->debug("Format: %s %s", "blah ...", {data=>'structure'});
 }

How to create multiple loggers?

For example, in Log::Any:

 my $log = Log::Any->get_logger;
 my $log_dump = Log::Any->get_logger(category => "dump"); # to dump contents

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

in Log::ger:

 # instead of installing to package, we setup objects (or hashes) for the
 # secondary loggers
 my $log_dump = Log::ger->get_logger(category => "dump");

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

OUTPUT

How to send logs to several outputs?

Use Log::ger::Output::Composite, which can log to multiple outputs as well as multiple output of the same type (e.g. two or more File's).

How to send trace/debug messages to screen, but warnings/errors to file?

Using Log::ger::Output::Composite's per-output level:

 Log::ger::Output Composite => (
     Screen => {
         level => ['trace', 'debug'],
     },
     File => {
         conf => { path=>'/path/to/file.log' },
         level => ['warn', 'error'],
     },
 );

How to send trace/debug messages to a file, but warnings/errors to another file?

Using Log::ger::Output::Composite's per-output level:

 Log::ger::Output Composite => (
     File => [
         {
             conf => { path=>'file1.log' },
             level => ['trace', 'debug'],
         },
         {
             conf => { path=>'file2.log' },
             level => ['warn', 'error'],
         },
     ],
 );

How to filter by category?

Using Log::ger::Output::Composite.

TODO example.

How to log warnings/die messages?

TODO

LEVEL

How to use custom levels?

One way:

 use Log::ger ();
 BEGIN {
     our %Log::ger::Levels = (
         critical => 1,
         error    => 2,
         warning  => 3,
         info     => 4,
         extra    => 5,
     );
     our %Log::ger::Level_Aliases = (
         warn     => 3,
         verbose  => 4,
     );

Do this before initializing any package with use Log::ger. The above example will create these logging routines: log_critical, log_error, log_warning, log_info, log_extra. The aliases won't get the logging routines but Log::ger::Util::numeric_level will recognize them.

FORMAT & LAYOUT

How to do sprintf-style formatting?

By default, the Log::ger formatter already does sprintf-style formatting:

 log_warn("Format %s %s", "blah ...", {data=>'structure'});

If there is only one argument, no formatting is done.

 log_warn("blah ...");

Why doesn't Log::ger log multiple arguments?

Logging multiple arguments is not supported by the default formatter because by default Log::ger adopts sprintf style:

 log_warn("blah ...", "more blah ...");

Either join the arguments first, use sprintf style, or use some of the other formatters that support this, e.g. Log::ger::Like::LogAny.

How to use deferred calculation of arguments?

Use a formatter like Log::ger::Format::Block, or Log::ger::Format::Flogger, or develop your own formatter to do what you want.

You can also do this:

 if (log_is_trace()) {
     log_trace("Format %s", $foo->something_that_is_expensive_to_calculate);
 }

How to dump data structures?

The default formatter already dumps data structures:

 log_warn("Format %s %s", "blah ...", {data=>'structure'});

How to log raw data structure?

You can use a formatter like Log::ger::Format::None which will prevent your log message from being stringified. To output this to destination, combine this with a layout plugin like Log::ger::Layout::JSON or Log::ger::Layout::LTSV. Or perhaps write your own output module that accepts raw data structure instead of formatted string and send it somewhere.

How to do custom formatting?

For example, a la Log::Contextual:

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

See Log::ger::Format::Block for an example.

How to add timestamps?

Use a layouter, e.g. Log::ger::Layout::Pattern.

How to use microsecond in timestamps?

TODO

How to redact sensitive information?

TODO

TARGETS

How to customize format/layout, output, plugin on a per-target basis?

To use a plugin only for the current package:

 package MyPackage;

 use Log::ger::Plugin;
 Log::ger::Plugin->set_for_current_package(
     'PluginName',
     conf1 => ..., ...);
 use Log::ger;

Do the same thing for format (using Log::ger::Format), layout (using Log::ger::Layout), or output (using Log::ger::Output).

SEE ALSO

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.