NAME
Log::ger::Manual::Tutorial::790_WritingALayoutPlugin - Writing a layout plugin
VERSION
version 0.040.000
DESCRIPTION
The function of a layout plugin is to take the log message and format it, usually into a string. The most often used layout is Log::ger::Layout::Pattern which allows you to add things like timestamp, newline, level, location (source filename and line number) along with the log message itself.
This is not to be confused with a format plugin. A format plugin takes arguments from a log statement and produce a log message from it. You can say that format plugin is a form of formatting that is applied first, before the layout plugin.
Let's create a silly example layout plugin that can convert your log message to uppercase or lowercase. We'll call it ConvertCase. Create Log::ger::Layout::ConvertCase as follows:
# in lib/Log/ger/Layout/ConvertCase.pm
package Log::ger::Layout::ConvertCase;
use strict;
use warnings;
sub meta { +{
v => 2,
} }
sub get_hooks {
my %plugin_conf = @_;
$plugin_conf{case} or die "Please specify case";
$plugin_conf{case} =~ /\A(upper|lower)\z/
or die "Invalid value for 'case', please use 'upper' or 'lower'";
return {
create_layouter => [
__PACKAGE__, # key
50, # priority
sub { # hook
my %hook_args = @_;
my $layouter = sub {
$plugin_conf{case} eq 'upper' ? uc($_[0]) : lc($_[0]);
};
[$layouter];
},
],
};
}
1;First of all, the plugin needs to define meta() that returns a hashref where the required key is v set to 2. This is a way to do API versioning so Log::ger can reject plugins with incompatible API version.
The plugin module needs to define get_hooks which returns a hashref of hook names and hook records. For the list of available hooks (as well as basically the same information presented here), see Log::ger::Manual::Internals. For a layout plugin, the relevant hook is create_layouter. This hook will be called when Log::ger wants to construct a layouter.
The hook record is an arrayref of 3 elements:
[$key, $prio, $coderef]$key is usually the name of the module (__PACKAGE__). $prio is priority for ordering when there are multiple plugins for the same hook, a number between 0-100 (the lower the number, the higher the priority), normally 50. $coderef is the actual hook. Our hook will receive a hash arguments (%hook_args) and is expected to return the result:
[$layouter, ...]We are only concerned with the first element, hence will not discuss the rest. The layouter will be passed:
($fmsg, \%per_target_conf, $lnum, $lname, \%per_msg_conf)where $fmsg is formatted message from the formatter, %per_target_conf are arguments given to Log::ger->get_logger or to Log::ger's import(), $lnum is numeric level, $lname is string level, and %per_msg_conf is optional. In the example above, we are only concerned with $fmsg ($_[0]).
To see our plugin in action, try this simple program:
use Log::ger;
use Log::ger::Layout ConvertCase => (case => 'upper');
log_warn "Hello, World!";When run, it will print:
HELLO, WORLD!For examples of more involved layout plugins, see: Log::ger::Layout::Pattern, Log::ger::Layout::JSON.
SEE ALSO
Log::ger::Manual::Tutorial::490_WritingAnOutputPlugin
Log::ger::Manual::Tutorial::690_WritingAFormatPlugin
AUTHOR
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2022, 2020, 2019, 2018, 2017 by perlancar <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.