package Object::Remote::Logging;
-use strictures 1;
-
-use Object::Remote::LogRouter;
-use Object::Remote::LogDestination;
-use Log::Contextual::SimpleLogger;
-use Carp qw(cluck);
-
-use base qw(Log::Contextual);
-
-sub arg_router {
- return $_[1] if defined $_[1];
- our $Router_Instance;
-
- return $Router_Instance if defined $Router_Instance;
-
- $Router_Instance = Object::Remote::LogRouter->new(
- description => $_[0],
- );
+use Moo;
+use Scalar::Util qw(blessed);
+use Object::Remote::Logging::Logger;
+use Exporter::Declare;
+use Carp qw(carp croak);
+
+extends 'Log::Contextual';
+
+exports(qw( ____ router arg_levels ));
+
+sub router {
+ our $Router_Instance ||= do {
+ require Object::Remote::Logging::Router;
+ Object::Remote::Logging::Router->new;
+ }
}
-sub init_logging {
- my ($class) = @_;
- our $Did_Init;
-
- return if $Did_Init;
- $Did_Init = 1;
+#log level descriptions
+#info - standard log level - normal program output for the end user
+#warn - output for program that is executing quietly
+#error - output for program that is running more quietly
+#fatal - it is not possible to continue execution; this level is as quiet as is possible
+#verbose - output for program executing verbosely (-v)
+#debug - output for program running more verbosely (-v -v)
+#trace - output for program running extremely verbosely (-v -v -v)
+sub arg_levels {
+ #the order of the log levels is significant with the
+ #most verbose level being first in the list and the
+ #most quiet as the last item
+ return [qw( trace debug verbose info warn error fatal )];
+}
+
+sub before_import {
+ my ($class, $importer, $spec) = @_;
+ my $router = $class->router;
+ our $DID_INIT;
+
+ unless($DID_INIT) {
+ $DID_INIT = 1;
+ init_logging();
+ }
+
+ $class->SUPER::before_import($importer, $spec);
+}
+
+sub _parse_selections {
+ my ($selections_string) = @_;
+ my %log_ok;
- if ($ENV{OBJECT_REMOTE_LOG_LEVEL}) {
- $class->init_logging_stderr($ENV{OBJECT_REMOTE_LOG_LEVEL});
+ #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;
}
-sub init_logging_stderr {
- my ($class, $level) = @_;
- our $Log_Level = $level;
- chomp(my $hostname = `hostname`);
+#this is invoked on all nodes
+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;
- our $Log_Output = Object::Remote::LogDestination->new(
- logger => Log::Contextual::SimpleLogger->new({
- levels_upto => $Log_Level,
- coderef => sub {
- my @t = localtime();
- my $time = sprintf("%0.2i:%0.2i:%0.2i", $t[2], $t[1], $t[0]);
- print STDERR "[$hostname $$] $time ", @_
- },
- })
- );
+ unless (defined $ENV{OBJECT_REMOTE_LOG_FORWARDING} && $ENV{OBJECT_REMOTE_LOG_FORWARDING} ne '') {
+ $ENV{OBJECT_REMOTE_LOG_FORWARDING} = 1;
+ }
- $Log_Output->connect($class->arg_router);
+ 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(),
+ ));
+ }
+
+ return unless defined $level && $level ne '';
+ $format = "[%l %r] %s" unless defined $format;
+ $selections = __PACKAGE__ unless defined $selections;
+ %controller_should_log = _parse_selections($selections);
+
+ {
+ no warnings 'once';
+ if (defined $Object::Remote::FatNode::REMOTE_NODE) {
+ #the connection id for the remote node comes in later
+ #as the controlling node inits remote logging
+ router()->_remote_metadata({ connection_id => undef });
+ }
+ }
+
+ 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};
+ my $will_log = $controller_should_log{$controller};
+
+ $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
+ });
}
-sub init_logging_forwarding {
-# my ($class, $remote_parent) = @_;
-# chomp(my $host = `hostname`);
-# $class->arg_router->description("$$ $host");
-# $class->arg_router->parent_router($remote_parent);
-# $remote_parent->add_child_router($class->arg_router);
+#this is invoked by the controlling node
+#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__
-Hierarchical routed logging concept
+=head1 NAME
- Why?
-
- Object::Remote and systems built on it would benefit from a standard model
- for logging that enables simple and transparent log generation and consumption
- that can cross the Perl interpreter instance boundaries. More
- generally CPAN would benefit from a common logging framework that allows all
- log message generators to play nicely with all log message consumers with out
- making the generators or consumers jump through hoops to do what they want to do.
- If these two solutions are the same then all modules built using the
- logging framework will transparently operate properly when run under Object::Remote.
+Object::Remote::Logging - Logging subsystem for Object::Remote
+
+=head1 SYNOPSIS
+
+ use Object::Remote::Logging qw( :log :dlog arg_levels router );
- Such a solution needs to be flexible and have a low performance impact when it is not
- actively logging. The hiearchy of log message routers is the way to achieve all of these
- goals. The abstracted message router interface introduced to Log::Contextual allows
- the hierarchical routing system to be built and tested inside Object::Remote with possible
- larger scale deployment in the future.
+ @levels = qw( trace debug verbose info warn error fatal );
+ @levels = arg_levels(); #same result
- Hierarchy of log routers
+ $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';
+ $ENV{OBJECT_REMOTE_LOG_SELECTIONS} = '* -Object::Remote::Logging';
+ $ENV{OBJECT_REMOTE_LOG_FORWARDING} = 0; #default 1
- * Each Perl module ideally would use at least a router dedicated
- to that module and may have child routers if the module is complex.
-
- * Log messages inserted at low levels in the hierarchy
- are available at routers at higher levels in the hierarchy.
-
- * Each running Perl instance has a root router which receives
- all log messages generated in the Perl instance.
-
- * The routing hierarchy is available for introspection and connections
- from child routers to parent routers have human readable descriptions
-
- * The entire routing system is dynamic
- * Add and remove routers while the system is in operation
- * Add and remove subscriptions into routers while the system is in operation
-
- * Auto-solves Object::Remote logging by setting the parent router of the
- root router in the remote instance to a router in the local instance. The
- log messages will flow into the local router via a proxy object.
-
- * There needs to be two modes of operation for routed logging
- * forwarding across Perl instances using Object::Remote proxies
- for ease of use during normal operation
-
- * STDERR output by default because not all logs can be forwarded
- such as log messages for parts of Object::Remote that relate to
- Object::Remote delivering the log.
-
+ log_info { 'Trace log event' };
+ Dlog_verbose { "Debug event with Data::Dumper::Concise: $_" } { foo => 'bar' };
+=head1 DESCRIPTION
- Example hiearchy
-
- * Root [1]
- * System::Introspector
- * Object::Remote [2]
- * local [3]
- * remote [4]
- * connection #1 [5]
- * Root
- * System::Introspector
- * Object::Remote
- * local
- * connection #2
- * Root
- * System::Introspector
- * Object::Remote
- * local
-
- [1] This router has all logs generated anywhere
- even on remote hosts
- [2] Everything related to Object::Remote including
- log messages from remote nodes for things other
- than Object::Remote
- [3] Log messages generated by Object::Remote on the local
- node only
- [4] All log messages from all remote nodes
- [5] This is the connection from a remote instance to the
- local instance using a proxy object - the name contains
- the Object::Remote::Connection id for the remote node
-
- As a demonstration of the flexibility of the this system consider a CPAN testers GUI
- tool. This hypothetical tool would allow a tester to select a module by name and perform
- the automated tests for that package and all dependent packages. Inside the tool is a pane for
- the output of the process (STDOUT and STDERR), a pane for log messages, and a pane displaying
- the modules that are participating in routed logging. The tester could then click on individual
- packages and enable logging for that package dynamically. If neccassary more than one package
- could be monitored if neccassary. If the GUI is wrapping a program that runs for long periods of
- time or if the application is a daemon then being able to dynamically add and remove logging
- becomes very useful.
-
- Log message selection and output
-
- * Assumptions
- * Modules and packages know how they want to format log messages.
- * Consumers of log messages want to know
- * Which Perl module/package generated that message.
- * When running with Object::Remote if the log message is from
- a remote connection and if so which connection.
- * Consumers of a log message know how they want to output them. The logger
- should not be enforcing a specific type of log output.
- * Most log messages most of the time will be completely ignored and unused.
- * Router subscriptions
- * A consumer of log messages will subscribe to a router at any arbitrary point
- in the router hierarchy even across machines if Object::Remote is involved
- * The subscription is used to access a stream of log data and is not used to select
- which packages/modules should be logged
- * For instance the Object::Remote log router has log messages flowing through
- it that include logs generated on remote nodes even if those logs were generated
- by a module other than Object::Remote
-
- * Selection
- * The module has defined what the log message format is
- * The subscription has defined the scope of messages that will be
- available for selection, ie: all log messages everywhere,
- all logs generated on Object::Remote nodes, etc
- * Selection defines what log messages are going to be delivered
- to a logger object instance
- * Selectors act as a gate between a subscription and the logger object
- * Selectors are closures that perform introspection on the log
- message and metadata; if the selector returns true the logger
- will be invoked to log this message
- * The logger still has a log level assigned to it and still will have
- the is_$level method invoked to only log at that specific level
-
- * Destinations
- * A log destination is an instance of a logger object and the associated
- subscriptions.
- * Consuming logging data from this system is a matter of
- * Constructing an instance of a logging destination object which has
- the following attributes:
- * logger - the logger object
- * selectors - a list of closures; the first one that returns true
- causes the logger to be checked for this log_level and
- invoked if needed
- * Register selectors with the destination by invoking a method and specifying
- sub refs as an argument
-
- Technical considerations
- * The routing hierarchy has cycles where parent routers hold a reference to the child
- and the child holds a reference to the parent. The cycles are not a problem if weak
- references are used however proxy objects don't seem to currently work with weak
- references.
- * Once a logger hits a proxy object the caller information is totally blown; this
- crossing isn't transparent yet
- * If Object::Remote is logging its actions and those logs are being forwarded then
- logs can be generated from the forwarding itself creating an infinite loop. Only
- a portion of Object::Remote can be forwarded.
-
-
-
+This is the logging framework for Object::Remote implemented as a subclass of
+L<Log::Contextual> 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<Object::Remote::Logging::Logger>
+which implements log rendering and output and L<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
+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
+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.
+
+Every time the local interpreter creates a new Object::Remote::Connection the connection
+is given an id that is unique to that connection on the local interpreter. The connection
+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<Object::Remote::Logging::Logger>. Setting this
+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
+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<Object::Remote::Logging::Logger> to be built
+and connected to the L<Object::Remote::Logging::Router> 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.
+
+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.
+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<Object::Remote::Logging::Router>.
+
+=head1 EXPORTABLE SUBROUTINES
+
+=over 4
+
+=item arg_levels
+
+Returns an array reference that contains the ordered list of level names
+with the lowest log level first and the highest log level last.
+
+=item router
+
+Returns the instance of L<Object::Remote::Logging::Router> that is in use. The router
+instance is used in combination with L<Object::Remote::Logging::Logger> objects to
+select then render and output log messages.
+
+=item log_<level> and Dlog_<level>
+
+These methods come direct from L<Log::Contextual>; 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
+to the block as the argument list and returned from the log method as a list.
+
+ log_trace { "A fine log message $_[0] " } 'if I do say so myself';
+ %hash = Dlog_trace { "Very handy: $_" } ( foo => 'bar' );
+
+=item logS_<level> and DlogS_<level>
+
+Works just like log_ and Dlog_ except returns only the first argument as a scalar value.
+
+ my $beverage = logS_info { "Customer ordered $_[0]" } 'Coffee';
+
+=back
+
+=head1 LEVEL NAMES
+
+Object::Remote uses an ordered list of log level names with the lowest level
+first and the highest level last. The list of level names can be accessed via
+the arg_levels method which is exportable to the consumer of this class. The log
+level names are:
+
+=over 4
+
+=item trace
+
+As much information about operation as possible including multiple line dumps of
+large content. Tripple verbose operation (-v -v -v).
+
+=item debug
+
+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).
+
+=item verbose
+
+Additional optional messages to the user that can be enabled at their will. Single
+verbose operation (-v).
+
+=item info
+
+Messages from normal operation that are intended to be displayed to the end
+user if quiet operation is not indicated and more verbose operation is not
+in effect.
+
+=item warn
+
+Something wasn't supposed to happen but did. Operation was not impacted but
+otherwise the event is noteworthy. Single quiet operation (-q).
+
+=item error
+Something went wrong. Operation of the system may continue but some operation
+has most definitely failed. Double quiet operation (-q -q).
+=item fatal
+Something went wrong and recovery is not possible. The system should stop operating
+as soon as possible. Tripple quiet operation (-q -q -q).
+=back
projects / scpubgit/Object-Remote.git / blobdiff