1Log::Contextual::Role::URsoeurteCro(n3t)ributed Perl DocLuomge:n:tCaotnitoenxtual::Role::Router(3)
2
6 Log::Contextual::Role::Router - Abstract interface between loggers and
7 logging code blocks
8
10 version 0.008001
11
13 package MyApp::Log::Router;
14 use Moo;
16 use Log::Contextual::SimpleLogger;
17 with 'Log::Contextual::Role::Router';
19 has logger => (is => 'lazy');
21 sub _build_logger {
23 return Log::Contextual::SimpleLogger->new({ levels_upto => 'debug' });
24 }
25 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 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 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 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 package MyApp::Log::Contextual;
54 use Moo;
56 use MyApp::Log::Router;
57 extends 'Log::Contextual';
59 #This example router is a singleton
61 sub router {
62 our $Router ||= MyApp::Log::Router->new
63 }
64 package main;
66 use strict;
68 use warnings;
69 use MyApp::Log::Contextual qw(:log);
70 log_info { "Hello there" };
72
74 Log::Contextual has three parts
75 Export manager and logging method generator
77 These tasks are handled by the "Log::Contextual" package.
78 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 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
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 The arguments are passed as a hash with the following keys:
106 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 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 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 use Log::Contextual qw( :log ), -logger => Custom::Logger->new({ levels => [qw( debug )] });
124 then $import_info{arguments}->{logger} would contain that
126 instance of Custom::Logger.
127 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 exporter
133 This is the name of the package that created the logging
134 methods used to generate the log event.
135 caller_package
137 This is the name of the package that the log event has happened
138 inside of.
139 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 log_level
146 This is the name of the log level associated with the log
147 event.
148 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 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
162 Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
163
165 This software is copyright (c) 2018 by Arthur Axel "fREW" Schmidt.
166 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.
169perl v5.32.0 2020-07-28 Log::Contextual::Role::Router(3)