1 package Log::Contextual::Role::Router;
5 requires 'before_import';
6 requires 'after_import';
7 requires 'handle_log_request';
15 Log::Contextual::Role::Router - Abstract interface between loggers and logging code blocks
19 package MyApp::Log::Router;
22 use Log::Contextual::SimpleLogger;
24 with 'Log::Contextual::Role::Router';
26 has logger => (is => 'lazy');
29 return Log::Contextual::SimpleLogger->new({ levels_upto => 'debug' });
33 my ($self, %export_info) = @_;
34 my $exporter = $export_info{exporter};
35 my $target = $export_info{target};
36 print STDERR "Package '$target' will import from '$exporter'\n";
40 my ($self, %export_info) = @_;
41 my $exporter = $export_info{exporter};
42 my $target = $export_info{target};
43 print STDERR "Package '$target' has imported from '$exporter'\n";
46 sub handle_log_request {
47 my ($self, %message_info) = @_;
48 my $log_code_block = $message_info{message_sub};
49 my $args = $message_info{message_args};
50 my $log_level_name = $message_info{message_level};
51 my $logger = $self->logger;
52 my $is_active = $logger->can("is_${log_level_name}");
54 return unless defined $is_active && $logger->$is_active;
55 my $log_message = $log_code_block->(@$args);
56 $logger->$log_level_name($log_message);
59 package MyApp::Log::Contextual;
62 use MyApp::Log::Router;
64 extends 'Log::Contextual';
66 #This example router is a singleton
68 our $Router ||= MyApp::Log::Router->new
75 use MyApp::Log::Contextual qw(:log);
77 log_info { "Hello there" };
81 Log::Contextual has three parts
85 =item Export manager and logging method generator
87 These tasks are handled by the C<Log::Contextual> package.
89 =item Logger selection and invocation
91 The logging functions generated and exported by Log::Contextual call a method
92 on an instance of a log router object which is responsible for invoking any loggers
93 that should get an opportunity to receive the log message. The C<Log::Contextual::Router>
94 class implements the set_logger() and with_logger() functions as well as uses the
95 arg_ prefixed functions to configure itself and provide the standard C<Log::Contextual>
98 =item Log message formatting and output
100 The logger objects themselves accept or reject a log message at a certain log
101 level with a guard method per level. If the logger is going to accept the
102 log message the router is then responsible for executing the log message code
103 block and passing the generated message to the logging object's log method.
111 =item before_import($self, %import_info)
113 =item after_import($self, %import_info)
115 These two required methods are called with identical arguments at two different places
116 during the import process. The before_import() method is invoked prior to the logging
117 subroutines being exported into the target package and after_import() is called when the
118 export is completed but before control returns to the package that imported the API.
120 The arguments are passed as a hash with the following keys:
126 This is the name of the package that has been imported. It can also be 'Log::Contextual' itself. In
127 the case of the synopsis the value for exporter would be 'MyApp::Log::Contextual'.
131 This is the package name that is importing the logging API. In the case of the synopsis the
132 value would be 'main'.
136 This is a hash reference containing the configuration values that were provided for the import.
137 The key is the name of the configuration item that was specified without the leading hyphen ('-').
138 For instance if the logging API is imported as follows
140 use Log::Contextual qw( :log ), -logger => Custom::Logger->new({ levels => [qw( debug )] });
142 then $import_info{arguments}->{logger} would contain that instance of Custom::Logger.
146 =item handle_log_request($self, %message_info)
148 This method is called by C<Log::Contextual> when a log event happens. The arguments are passed
149 as a hash with the following keys
155 This is the name of the package that created the logging methods used to generate the log event.
159 This is the name of the package that the log event has happened inside of.
163 This is an integer that contains the value to pass to caller() that will provide
164 information about the location the log event was created at.
168 This is the name of the log level associated with the log event.
172 This is the message generating code block associated with the log event passed as a subref. If
173 the logger accepts the log request the router should execute the subref to create
174 the log message and then pass the message as a string to the logger.
178 This is an array reference that contains the arguments given to the message generating code block.
179 When invoking the message generator it will almost certainly be expecting these argument values
190 =item C<Log::Contextual>