::Logging::TestLogger package decleration had wrong name
[scpubgit/Object-Remote.git] / lib / Object / Remote / Logging.pm
5e2b2229 1package Object::Remote::Logging;
4e446335 3use Moo;
4use Scalar::Util qw(blessed);
5use Object::Remote::Logging::Logger;
f4a85080 6use Exporter::Declare;
663fb34f 7use Carp qw(carp croak);
5e2b2229 8
4e446335 9extends 'Log::Contextual';
5e2b2229 10
663fb34f 11exports(qw( ____ router arg_levels ));
f4a85080 12
4e446335 13sub router {
c0b2df05 14 our $Router_Instance ||= do {
15 require Object::Remote::Logging::Router;
16 Object::Remote::Logging::Router->new;
17 }
4e446335 18}
5e2b2229 19
9de32e1d 20#log level descriptions
21#info - standard log level - normal program output for the end user
22#warn - output for program that is executing quietly
23#error - output for program that is running more quietly
24#fatal - it is not possible to continue execution; this level is as quiet as is possible
25#verbose - output for program executing verbosely (-v)
26#debug - output for program running more verbosely (-v -v)
27#trace - output for program running extremely verbosely (-v -v -v)
4e446335 28sub arg_levels {
9de32e1d 29 #the order of the log levels is significant with the
30 #most verbose level being first in the list and the
31 #most quiet as the last item
32 return [qw( trace debug verbose info warn error fatal )];
4a9fa1a5 33}
5e2b2229 34
663fb34f 35sub before_import {
36 my ($class, $importer, $spec) = @_;
37 my $router = $class->router;
c2a69537 38 our $DID_INIT;
663fb34f 39
c2a69537 40 unless($DID_INIT) {
41 $DID_INIT = 1;
42 init_logging();
43 }
663fb34f 45 $class->SUPER::before_import($importer, $spec);
663fb34f 46}
ae198201 48sub _parse_selections {
8f43bcd9 49 my ($selections_string) = @_;
50 my %log_ok;
ae198201 51
8f43bcd9 52 #example string:
53 #" * -Object::Remote::Logging Foo::Bar::Baz "
54 foreach(split(/\s+/, $selections_string)) {
55 next if $_ eq '';
56 if ($_ eq '*') {
57 $log_ok{$_} = 1;
58 } elsif (s/^-//) {
59 $log_ok{$_} = 0;
60 } else {
61 $log_ok{$_} = 1;
ae198201 62 }
8f43bcd9 63 }
ae198201 64
8f43bcd9 65 return %log_ok;
ae198201 66}
4e446335 68#this is invoked on all nodes
4a9fa1a5 69sub init_logging {
c0b2df05 70 my $level = $ENV{OBJECT_REMOTE_LOG_LEVEL};
0fe333eb 71 my $format = $ENV{OBJECT_REMOTE_LOG_FORMAT};
eb49c7df 72 my $selections = $ENV{OBJECT_REMOTE_LOG_SELECTIONS};
abef6e5b 73 my $test_logging = $ENV{OBJECT_REMOTE_TEST_LOGGER};
eb49c7df 74 my %controller_should_log;
09f583a7 75
78 }
abef6e5b 79
80 if ($test_logging) {
81 require Object::Remote::Logging::TestLogger;
8c352906 82 router->connect(Object::Remote::Logging::TestLogger->new(
abef6e5b 83 min_level => 'trace', max_level => 'error',
84 level_names => Object::Remote::Logging->arg_levels(),
85 ));
86 }
5cd5276e 87
09f583a7 88 return unless defined $level && $level ne '';
0fe333eb 89 $format = "[%l %r] %s" unless defined $format;
eb49c7df 90 $selections = __PACKAGE__ unless defined $selections;
ae198201 91 %controller_should_log = _parse_selections($selections);
f1d70835 92
93 {
94 no warnings 'once';
95 if (defined $Object::Remote::FatNode::REMOTE_NODE) {
96 #the connection id for the remote node comes in later
97 #as the controlling node inits remote logging
98 router()->_remote_metadata({ connection_id => undef });
99 }
100 }
c0b2df05 102 my $logger = Object::Remote::Logging::Logger->new(
0fe333eb 103 min_level => lc($level), format => $format,
c0b2df05 104 level_names => Object::Remote::Logging::arg_levels(),
105 );
c0b2df05 107 router()->connect(sub {
eb49c7df 108 my $controller = $_[1]->{controller};
ae198201 109 my $will_log = $controller_should_log{$controller};
111 $will_log = $controller_should_log{'*'} unless defined $will_log;
113 return unless $will_log;
c0b2df05 114 #skip things from remote hosts because they log to STDERR
115 #when OBJECT_REMOTE_LOG_LEVEL is in effect
116 return if $_[1]->{remote}->{connection_id};
117 $logger
118 });
4a9fa1a5 119}
4e446335 121#this is invoked by the controlling node
122#on the remote nodes
f1d70835 123sub init_remote_logging {
4e446335 124 my ($self, %controller_info) = @_;
f1d70835 126 router()->_remote_metadata(\%controller_info);
466ee2c4 127 router()->_forward_destination($controller_info{router}) if $ENV{OBJECT_REMOTE_LOG_FORWARDING};
4a9fa1a5 128}
5e2b2229 129
455d031c 131
d672a9bf 132__END__
134=head1 NAME
136Object::Remote::Logging - Logging subsystem for Object::Remote
138=head1 SYNOPSIS
b8176a97 140 use Object::Remote::Logging qw( :log :dlog arg_levels router );
d672a9bf 141
142 @levels = qw( trace debug verbose info warn error fatal );
143 @levels = arg_levels(); #same result
145 $ENV{OBJECT_REMOTE_LOG_LEVEL} = 'trace'; #or other level name
146 $ENV{OBJECT_REMOTE_LOG_FORMAT} = '%l %t: %p::%m %s'; #and more
d672a9bf 147 $ENV{OBJECT_REMOTE_LOG_SELECTIONS} = 'Object::Remote::Logging Some::Other::Subclass';
ae198201 148 $ENV{OBJECT_REMOTE_LOG_SELECTIONS} = '* -Object::Remote::Logging';
09f583a7 149 $ENV{OBJECT_REMOTE_LOG_FORWARDING} = 0; #default 1
d672a9bf 150
151 log_info { 'Trace log event' };
152 Dlog_verbose { "Debug event with Data::Dumper::Concise: $_" } { foo => 'bar' };
d672a9bf 153
156This is the logging framework for Object::Remote implemented as a subclass of
157L<Log::Contextual> with a slightly incompatible API. This system allows
158developers using Object::Remote and end users of that software to control
159Object::Remote logging so operation can be tracked if needed. This is also
160the API used to generate log messages inside the Object::Remote source code.
162The rest of the logging system comes from L<Object::Remote::Logging::Logger>
163which implements log rendering and output and L<Object::Remote::Logging::Router>
164which delivers log events to the loggers.
455d031c 166=head1 USAGE
168Object::Remote logging is not enabled by default. If you need to immediately start
169debugging set the OBJECT_REMOTE_LOG_LEVEL environment variable to either 'trace'
170or 'debug'. This will enable logging to STDERR on the local and all remote Perl
171interpreters. By default STDERR for all remote interpreters is passed through
172unmodified so this is sufficient to receive logs generated anywhere Object::Remote
173is running.
175Every time the local interpreter creates a new Object::Remote::Connection the connection
176is given an id that is unique to that connection on the local interpreter. The connection
177id and other metadata is available in the log output via a log format string that can
178be set via the OBJECT_REMOTE_LOG_FORMAT environment variable. The format string and
179available metadata is documented in L<Object::Remote::Logging::Logger>. Setting this
180environment variable on the local interpreter will cause it to be propagated to the
181remote interpreter so all logs will be formated the same way.
183This class is designed so any module can create their own logging sub-class using it.
f21127fd 184With out any additional configuration the consumers of this logging class will
185automatically be enabled via OBJECT_REMOTE_LOG_LEVEL and formated with
186OBJECT_REMOTE_LOG_FORMAT but those additional log messages are not sent to STDERR.
187By setting the OBJECT_REMOTE_LOG_SELECTIONS environment variable to a list of
188class names seperated by spaces then logs generated by packages that use those classes
ae198201 189will be sent to STDERR. If the asterisk character (*) is used in the place of a class
190name then all class names will be selected by default instead of ignored. An individual
191class name can be turned off by prefixing the name with a hypen character (-). This is
192also a configuration item that is forwarded to the remote interpreters so all logging
193is consistent.
455d031c 194
195Regardless of OBJECT_REMOTE_LOG_LEVEL the logging system is still active and loggers
196can access the stream of log messages to format and output them. Internally
197OBJECT_REMOTE_LOG_LEVEL causes an L<Object::Remote::Logging::Logger> to be built
198and connected to the L<Object::Remote::Logging::Router> instance. It is also possible
199to manually build a logger instance and connect it to the router. See the documentation
f21127fd 200for the logger and router classes.
455d031c 201
202The logging system also supports a method of forwarding log messages from remote
203interpreters to the local interpreter. Forwarded log messages are generated in the
204remote interpreter and the logger for the message is invoked in the local interpreter.
205Sub-classes of Object::Remote::Logging will have log messages forwarded automatically.
206Loggers receive forwarded log messages exactly the same way as non-forwarded messages
207except a forwarded message includes extra metadata about the remote interpreter. Log
09f583a7 208forwarding is enabled by default but comes with a performance hit; to disable it set the
209OBJECT_REMOTE_LOG_FORWARDING environment variable to 0. See L<Object::Remote::Logging::Router>.
455d031c 210
213=over 4
215=item arg_levels
217Returns an array reference that contains the ordered list of level names
218with the lowest log level first and the highest log level last.
220=item router
222Returns the instance of L<Object::Remote::Logging::Router> that is in use. The router
223instance is used in combination with L<Object::Remote::Logging::Logger> objects to
224select then render and output log messages.
226=item log_<level> and Dlog_<level>
228These methods come direct from L<Log::Contextual>; see that documentation for a
229complete reference. For each of the log level names there are subroutines with the log_
230and Dlog_ prefix that will generate the log message. The first argument is a code block
231that returns the log message contents and the optional further arguments are both passed
232to the block as the argument list and returned from the log method as a list.
234 log_trace { "A fine log message $_[0] " } 'if I do say so myself';
455d031c 235 %hash = Dlog_trace { "Very handy: $_" } ( foo => 'bar' );
d672a9bf 236
237=item logS_<level> and DlogS_<level>
239Works just like log_ and Dlog_ except returns only the first argument as a scalar value.
302ecfbf 241 my $beverage = logS_info { "Customer ordered $_[0]" } 'Coffee';
d672a9bf 242
d672a9bf 243=back
245=head1 LEVEL NAMES
293fb1ee 247Object::Remote uses an ordered list of log level names with the lowest level
248first and the highest level last. The list of level names can be accessed via
d672a9bf 249the arg_levels method which is exportable to the consumer of this class. The log
250level names are:
252=over 4
254=item trace
256As much information about operation as possible including multiple line dumps of
257large content. Tripple verbose operation (-v -v -v).
259=item debug
261Messages about operations that could hang as well as internal state changes,
262results from method invocations, and information useful when looking for faults.
263Double verbose operation (-v -v).
265=item verbose
267Additional optional messages to the user that can be enabled at their will. Single
268verbose operation (-v).
270=item info
272Messages from normal operation that are intended to be displayed to the end
273user if quiet operation is not indicated and more verbose operation is not
274in effect.
276=item warn
278Something wasn't supposed to happen but did. Operation was not impacted but
279otherwise the event is noteworthy. Single quiet operation (-q).
281=item error
283Something went wrong. Operation of the system may continue but some operation
284has most definitely failed. Double quiet operation (-q -q).
286=item fatal
288Something went wrong and recovery is not possible. The system should stop operating
289as soon as possible. Tripple quiet operation (-q -q -q).