X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=scpubgit%2FObject-Remote.git;a=blobdiff_plain;f=lib%2FObject%2FRemote%2FLogging.pm;h=d87629a276f959d061e9729976794df58c6bfddd;hp=f5416d650de5db7b6cb930a066bf28b169276876;hb=2d3c094d476d2dcd43956b7381f397651b544ffc;hpb=0e090a216bf8825855f8ca70bcb7f0980b5f786d diff --git a/lib/Object/Remote/Logging.pm b/lib/Object/Remote/Logging.pm index f5416d6..d87629a 100644 --- a/lib/Object/Remote/Logging.pm +++ b/lib/Object/Remote/Logging.pm @@ -4,7 +4,6 @@ use Moo; use Scalar::Util qw(blessed); use Object::Remote::Logging::Logger; use Exporter::Declare; -use Carp qw(carp croak); extends 'Log::Contextual'; @@ -41,28 +40,28 @@ sub before_import { $DID_INIT = 1; init_logging(); } - + $class->SUPER::before_import($importer, $spec); } sub _parse_selections { - my ($selections_string) = @_; - my %log_ok; - - #example string: - #" * -Object::Remote::Logging Foo::Bar::Baz " - foreach(split(/\s+/, $selections_string)) { - next if $_ eq ''; - if ($_ eq '*') { - $log_ok{$_} = 1; - } elsif (s/^-//) { - $log_ok{$_} = 0; - } else { - $log_ok{$_} = 1; - } + my ($selections_string) = @_; + my %log_ok; + + #example string: + #" * -Object::Remote::Logging Foo::Bar::Baz " + foreach(split(/\s+/, $selections_string)) { + next if $_ eq ''; + if ($_ eq '*') { + $log_ok{$_} = 1; + } elsif (s/^-//) { + $log_ok{$_} = 0; + } else { + $log_ok{$_} = 1; } - - return %log_ok; + } + + return %log_ok; } #this is invoked on all nodes @@ -70,16 +69,20 @@ sub init_logging { my $level = $ENV{OBJECT_REMOTE_LOG_LEVEL}; my $format = $ENV{OBJECT_REMOTE_LOG_FORMAT}; my $selections = $ENV{OBJECT_REMOTE_LOG_SELECTIONS}; + my $test_logging = $ENV{OBJECT_REMOTE_TEST_LOGGER}; my %controller_should_log; - + unless (defined $ENV{OBJECT_REMOTE_LOG_FORWARDING} && $ENV{OBJECT_REMOTE_LOG_FORWARDING} ne '') { - $ENV{OBJECT_REMOTE_LOG_FORWARDING} = 1; + $ENV{OBJECT_REMOTE_LOG_FORWARDING} = 0; } - return unless defined $level && $level ne ''; - $format = "[%l %r] %s" unless defined $format; - $selections = __PACKAGE__ unless defined $selections; - %controller_should_log = _parse_selections($selections); + if ($test_logging) { + require Object::Remote::Logging::TestLogger; + router->connect(Object::Remote::Logging::TestLogger->new( + min_level => 'trace', max_level => 'error', + level_names => Object::Remote::Logging->arg_levels(), + )); + } { no warnings 'once'; @@ -87,25 +90,32 @@ sub init_logging { #the connection id for the remote node comes in later #as the controlling node inits remote logging router()->_remote_metadata({ connection_id => undef }); - } + } } + return unless defined $level && $level ne ''; + + $format = "[%l %r] %s" unless defined $format; + $selections = __PACKAGE__ unless defined $selections; + %controller_should_log = _parse_selections($selections); + my $logger = Object::Remote::Logging::Logger->new( min_level => lc($level), format => $format, level_names => Object::Remote::Logging::arg_levels(), ); - router()->connect(sub { - my $controller = $_[1]->{controller}; + router()->connect(sub { + my $controller = $_[1]->{exporter}; my $will_log = $controller_should_log{$controller}; - + my $remote_info = $_[1]->{object_remote}; + $will_log = $controller_should_log{'*'} unless defined $will_log; - + return unless $will_log; #skip things from remote hosts because they log to STDERR #when OBJECT_REMOTE_LOG_LEVEL is in effect - return if $_[1]->{remote}->{connection_id}; - $logger + return if $remote_info->{forwarded}; + return $logger; }); } @@ -113,15 +123,13 @@ sub init_logging { #on the remote nodes sub init_remote_logging { my ($self, %controller_info) = @_; - + router()->_remote_metadata(\%controller_info); router()->_forward_destination($controller_info{router}) if $ENV{OBJECT_REMOTE_LOG_FORWARDING}; } 1; -__END__ - =head1 NAME Object::Remote::Logging - Logging subsystem for Object::Remote @@ -129,36 +137,38 @@ Object::Remote::Logging - Logging subsystem for Object::Remote =head1 SYNOPSIS use Object::Remote::Logging qw( :log :dlog arg_levels router ); - - @levels = qw( trace debug verbose info warn error fatal ); - @levels = arg_levels(); #same result - + + $levels = [qw( trace debug verbose info warn error fatal )]; + $levels = arg_levels(); #same result + $ENV{OBJECT_REMOTE_LOG_LEVEL} = 'trace'; #or other level name $ENV{OBJECT_REMOTE_LOG_FORMAT} = '%l %t: %p::%m %s'; #and more - $ENV{OBJECT_REMOTE_LOG_SELECTIONS} = 'Object::Remote::Logging Some::Other::Subclass'; + #Output logs from two specific logging pacakges + $ENV{OBJECT_REMOTE_LOG_SELECTIONS} = 'Object::Remote::Logging Some::Other::Package'; + #Output all log messages except those generated by Object::Remote $ENV{OBJECT_REMOTE_LOG_SELECTIONS} = '* -Object::Remote::Logging'; - $ENV{OBJECT_REMOTE_LOG_FORWARDING} = 0; #default 1 - + $ENV{OBJECT_REMOTE_LOG_FORWARDING} = 1; #default 0 + log_info { 'Trace log event' }; Dlog_verbose { "Debug event with Data::Dumper::Concise: $_" } { foo => 'bar' }; =head1 DESCRIPTION -This is the logging framework for Object::Remote implemented as a subclass of -L with a slightly incompatible API. This system allows +This is the logging framework for Object::Remote implemented as an extension of +L with a slightly incompatible API. This system allows developers using Object::Remote and end users of that software to control Object::Remote logging so operation can be tracked if needed. This is also the API used to generate log messages inside the Object::Remote source code. The rest of the logging system comes from L -which implements log rendering and output and L +which implements log rendering and output and Object::Remote::Logging::Router which delivers log events to the loggers. =head1 USAGE -Object::Remote logging is not enabled by default. If you need to immediately start +Object::Remote logging output is not enabled by default. If you need to immediately start debugging set the OBJECT_REMOTE_LOG_LEVEL environment variable to either 'trace' -or 'debug'. This will enable logging to STDERR on the local and all remote Perl +or 'debug'. This will enable logging to STDERR on the local and all remote Perl interpreters. By default STDERR for all remote interpreters is passed through unmodified so this is sufficient to receive logs generated anywhere Object::Remote is running. @@ -168,36 +178,36 @@ is given an id that is unique to that connection on the local interpreter. The c id and other metadata is available in the log output via a log format string that can be set via the OBJECT_REMOTE_LOG_FORMAT environment variable. The format string and available metadata is documented in L. Setting this -environment variable on the local interpreter will cause it to be propagated to the +environment variable on the local interpreter will cause it to be propagated to the remote interpreter so all logs will be formated the same way. -This class is designed so any module can create their own logging sub-class using it. -With out any additional configuration the consumers of this logging class will -automatically be enabled via OBJECT_REMOTE_LOG_LEVEL and formated with -OBJECT_REMOTE_LOG_FORMAT but those additional log messages are not sent to STDERR. -By setting the OBJECT_REMOTE_LOG_SELECTIONS environment variable to a list of -class names seperated by spaces then logs generated by packages that use those classes -will be sent to STDERR. If the asterisk character (*) is used in the place of a class -name then all class names will be selected by default instead of ignored. An individual -class name can be turned off by prefixing the name with a hypen character (-). This is +This system is designed so any module can create their own logging packages using it. +With out any additional configuration the consumers of this logging system will +automatically be enabled via OBJECT_REMOTE_LOG_LEVEL and formated with +OBJECT_REMOTE_LOG_FORMAT but those additional log messages are not sent to STDERR. +By setting the OBJECT_REMOTE_LOG_SELECTIONS environment variable to a list of logging +package names seperated by spaces then logs generated using those packages +will be sent to STDERR. If the asterisk character (*) is used in the place of a package +name then all package names will be selected by default instead of ignored. An individual +package name can be turned off by prefixing the name with a hypen character (-). This is also a configuration item that is forwarded to the remote interpreters so all logging is consistent. Regardless of OBJECT_REMOTE_LOG_LEVEL the logging system is still active and loggers can access the stream of log messages to format and output them. Internally OBJECT_REMOTE_LOG_LEVEL causes an L to be built -and connected to the L instance. It is also possible -to manually build a logger instance and connect it to the router. See the documentation -for the logger and router classes. +and connected to the Object::Remote::Logging::Router instance. It is also possible +to manually build a logger instance and connect it to the router. See the +Object::Remote::Logging documentation for more information. The logging system also supports a method of forwarding log messages from remote interpreters to the local interpreter. Forwarded log messages are generated in the remote interpreter and the logger for the message is invoked in the local interpreter. -Sub-classes of Object::Remote::Logging will have log messages forwarded automatically. +Packages using or extending Object::Remote::Logging will have log messages forwarded automatically. Loggers receive forwarded log messages exactly the same way as non-forwarded messages -except a forwarded message includes extra metadata about the remote interpreter. Log -forwarding is enabled by default but comes with a performance hit; to disable it set the -OBJECT_REMOTE_LOG_FORWARDING environment variable to 0. See L. +except a forwarded message includes extra metadata about the remote connection. Log +forwarding is disabled by default because it comes with a performance hit; to enable +it set the OBJECT_REMOTE_LOG_FORWARDING environment variable to 1. =head1 EXPORTABLE SUBROUTINES @@ -216,7 +226,7 @@ select then render and output log messages. =item log_ and Dlog_ -These methods come direct from L; see that documentation for a +These methods come direct from L; see that documentation for a complete reference. For each of the log level names there are subroutines with the log_ and Dlog_ prefix that will generate the log message. The first argument is a code block that returns the log message contents and the optional further arguments are both passed @@ -249,7 +259,7 @@ large content. Tripple verbose operation (-v -v -v). =item debug -Messages about operations that could hang as well as internal state changes, +Messages about operations that could hang as well as internal state changes, results from method invocations, and information useful when looking for faults. Double verbose operation (-v -v).