Log::ger::Manual::Tutorial::790_WritingALayoutPlugin - Writing a layout plugin
version 0.040.000
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:
ConvertCase
Log::ger::Layout::ConvertCase
# 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.
meta()
v
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.
get_hooks
create_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:
$key
__PACKAGE__
$prio
$coderef
%hook_args
[$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]).
$fmsg
%per_target_conf
Log::ger->get_logger
Log::ger
import()
$lnum
$lname
%per_msg_conf
$_[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.
Log::ger::Manual::Internals
Log::ger::Manual::Tutorial::490_WritingAnOutputPlugin
Log::ger::Manual::Tutorial::690_WritingAFormatPlugin
perlancar <perlancar@cpan.org>
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.
To install Log::ger::Manual, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Log::ger::Manual
CPAN shell
perl -MCPAN -e shell install Log::ger::Manual
For more information on module installation, please visit the detailed CPAN module installation guide.