1Log::Contextual::Role::URsoeurteCro(n3t)ributed Perl DocLuomge:n:tCaotnitoenxtual::Role::Router(3)
2
3
4

NAME

6       Log::Contextual::Role::Router - Abstract interface between loggers and
7       logging code blocks
8

VERSION

10       version 0.008001
11

SYNOPSIS

13         package MyApp::Log::Router;
14
15         use Moo;
16         use Log::Contextual::SimpleLogger;
17
18         with 'Log::Contextual::Role::Router';
19
20         has logger => (is => 'lazy');
21
22         sub _build_logger {
23            return Log::Contextual::SimpleLogger->new({ levels_upto => 'debug' });
24         }
25
26         sub before_import {
27            my ($self, %export_info) = @_;
28            my $exporter = $export_info{exporter};
29            my $target = $export_info{target};
30            print STDERR "Package '$target' will import from '$exporter'\n";
31         }
32
33         sub after_import {
34            my ($self, %export_info) = @_;
35            my $exporter = $export_info{exporter};
36            my $target = $export_info{target};
37            print STDERR "Package '$target' has imported from '$exporter'\n";
38         }
39
40         sub handle_log_request {
41            my ($self, %message_info) = @_;
42            my $log_code_block = $message_info{message_sub};
43            my $args = $message_info{message_args};
44            my $log_level_name = $message_info{message_level};
45            my $logger = $self->logger;
46            my $is_active = $logger->can("is_${log_level_name}");
47
48            return unless defined $is_active && $logger->$is_active;
49            my $log_message = $log_code_block->(@$args);
50            $logger->$log_level_name($log_message);
51         }
52
53         package MyApp::Log::Contextual;
54
55         use Moo;
56         use MyApp::Log::Router;
57
58         extends 'Log::Contextual';
59
60         #This example router is a singleton
61         sub router {
62            our $Router ||= MyApp::Log::Router->new
63         }
64
65         package main;
66
67         use strict;
68         use warnings;
69         use MyApp::Log::Contextual qw(:log);
70
71         log_info { "Hello there" };
72

DESCRIPTION

74       Log::Contextual has three parts
75
76       Export manager and logging method generator
77           These tasks are handled by the "Log::Contextual" package.
78
79       Logger selection and invocation
80           The logging functions generated and exported by Log::Contextual
81           call a method on an instance of a log router object which is
82           responsible for invoking any loggers that should get an opportunity
83           to receive the log message. The "Log::Contextual::Router" class
84           implements the set_logger() and with_logger() functions as well as
85           uses the arg_ prefixed functions to configure itself and provide
86           the standard "Log::Contextual" logger selection API.
87
88       Log message formatting and output
89           The logger objects themselves accept or reject a log message at a
90           certain log level with a guard method per level. If the logger is
91           going to accept the log message the router is then responsible for
92           executing the log message code block and passing the generated
93           message to the logging object's log method.
94

METHODS

96       before_import($self, %import_info)
97       after_import($self,  %import_info)
98           These two required methods are called with identical arguments at
99           two different places during the import process. The before_import()
100           method is invoked prior to the logging subroutines being exported
101           into the target package and after_import() is called when the
102           export is completed but before control returns to the package that
103           imported the API.
104
105           The arguments are passed as a hash with the following keys:
106
107           exporter
108               This is the name of the package that has been imported. It can
109               also be 'Log::Contextual' itself. In the case of the synopsis
110               the value for exporter would be 'MyApp::Log::Contextual'.
111
112           target
113               This is the package name that is importing the logging API. In
114               the case of the synopsis the value would be 'main'.
115
116           arguments
117               This is a hash reference containing the configuration values
118               that were provided for the import.  The key is the name of the
119               configuration item that was specified without the leading
120               hyphen ('-').  For instance if the logging API is imported as
121               follows
122
123                 use Log::Contextual qw( :log ), -logger => Custom::Logger->new({ levels => [qw( debug )] });
124
125               then $import_info{arguments}->{logger} would contain that
126               instance of Custom::Logger.
127
128       handle_log_request($self, %message_info)
129           This method is called by "Log::Contextual" when a log event
130           happens. The arguments are passed as a hash with the following keys
131
132           exporter
133               This is the name of the package that created the logging
134               methods used to generate the log event.
135
136           caller_package
137               This is the name of the package that the log event has happened
138               inside of.
139
140           caller_level
141               This is an integer that contains the value to pass to caller()
142               that will provide information about the location the log event
143               was created at.
144
145           log_level
146               This is the name of the log level associated with the log
147               event.
148
149           message_sub
150               This is the message generating code block associated with the
151               log event passed as a subref. If the logger accepts the log
152               request the router should execute the subref to create the log
153               message and then pass the message as a string to the logger.
154
155           message_args
156               This is an array reference that contains the arguments given to
157               the message generating code block.  When invoking the message
158               generator it will almost certainly be expecting these argument
159               values as well.
160

AUTHOR

162       Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
163
165       This software is copyright (c) 2018 by Arthur Axel "fREW" Schmidt.
166
167       This is free software; you can redistribute it and/or modify it under
168       the same terms as the Perl 5 programming language system itself.
169
170
171
172perl v5.32.0                      2020-07-28  Log::Contextual::Role::Router(3)
Impressum