add self to contributor list; document new env variables in Object::Remote POD; add...
Tyler Riddle [Fri, 9 Nov 2012 01:04:58 +0000 (17:04 -0800)]
lib/Object/Remote.pm
lib/Object/Remote/Logging.pm

index feee52a..03095a5 100644 (file)
@@ -130,6 +130,41 @@ to block until an asynchronous call completes or fails.
 
   my $hostname = Sys::Hostname->can::on('myserver', 'hostname');
 
+=head1 ENVIRONMENT
+
+=over 4
+
+=item OBJECT_REMOTE_PERL_BIN
+
+When starting a new Perl interpreter the contents of this environment
+variable will be used as the path to the executable. If the variable
+is not set the path is 'perl'
+
+=item OBJECT_REMOTE_LOG_LEVEL
+
+Setting this environment variable will enable logging and send all log messages
+at the specfied level or higher to STDERR. Valid level names are: trace debug
+verbose info warn error fatal
+
+=item OBJECT_REMOTE_LOG_FORMAT
+
+The format of the logging output is configurable. By setting this environment variable
+the format can be controlled via printf style position variables. See
+L<Object::Remote::Logging::Logger>.
+
+=item OBJECT_REMOTE_LOG_FORWARDING
+
+Forward log events from remote connections to the local Perl interpreter. Set to 1 to enable
+this feature which is disabled by default. See L<Object::Remote::Logging>.
+
+=item OBJECT_REMOTE_LOG_SELECTIONS
+
+Space seperated list of class names to display logs for if logging output is enabled. Default
+value is "Object::Remote::Logging" which selects all logs generated by Object::Remote.
+See L<Object::Remote::Logging::Router>.
+
+=back
+
 =head1 SUPPORT
 
 IRC: #web-simple on irc.perl.org
@@ -142,6 +177,8 @@ mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
 
 phaylon - Robert Sedlacek (cpan:PHAYLON) <r.sedlacek@shadowcat.co.uk>
 
+triddle - Tyler Riddle (cpan:TRIDDLE) <t.riddle@shadowcat.co.uk>
+
 =head1 SPONSORS
 
 Parts of this code were paid for by
index d99ca44..4811048 100644 (file)
@@ -69,7 +69,8 @@ sub before_import {
                level => $level,
             }, $code);
             #TODO this should get fed into a logger so it can be formatted
-            carp $code->();
+            #don't let it going wrong stop us from calling exit()
+            eval { carp $code->() };
             exit($exit_value);
          });
       }
@@ -114,4 +115,165 @@ sub init_logging_forwarding {
 }
 
 1;
+__END__
+
+=head1 NAME
+
+Object::Remote::Logging - Logging subsystem for Object::Remote
+
+=head1 SYNOPSIS
+
+  use Object::Remote::Logging qw( :log :dlog :elog :flog arg_levels router );
+  
+  @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_FORWARDING} = 0 || 1; #default 0
+  $ENV{OBJECT_REMOTE_LOG_SELECTIONS} = 'Object::Remote::Logging Some::Other::Subclass';
+  
+  log_info { 'Trace log event' };
+  Dlog_verbose { "Debug event with Data::Dumper::Concise: $_" } { foo => 'bar' };
+  Elog_error { 'Error event that calls die() with this string' };
+  Flog_fatal { 'Fatal event calls warn() then exit()' } 1;
+
+=head1 DESCRIPTION
+
+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 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';
+  $hashref = 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 = log_info { "Customer ordered $_[0]" } 'Coffee';
+
+=item Elog_<level>
+
+Log an event and then generate an exception by calling die() with the log message.
+
+  Elog_error { "Could not open file: $!" };
+
+=item Flog_<level>
+
+Log the event, generate a warning with the log message, then call exit(). The exit
+value will default to 1 or can be specified as an argument.
+
+  Flog_fatal { 'Could not lock resource' } 3;
+
+=back
+
+=head1 LEVEL NAMES
+
+Object::Remote uses an ordered list of log level names with the minimum level
+first and the maximum 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
+
+=head1 ENVIRONMENT
+
+=over 4
+
+=item OBJECT_REMOTE_LOG_LEVEL
+
+By default Object::Remote will generate log events but messages will not be
+output to STDERR. If there is a defined value for this variable then logs will
+be sent to STDERR if they are at this level or higher.
+
+=item OBJECT_REMOTE_LOG_FORMAT
+
+If logging output is enabled and this value is defined then the logger will
+use this format string instead of the default '[%l %r] %s'; See 
+L<Object::Remote::Logging::Logger> for documentation on the format string.
+
+=item OBJECT_REMOTE_LOG_SELECTIONS
+
+By default Object::Remote log output will only be enabled for messages generated inside
+Object::Remote packages. If logs should be generated for other log messages instead of just
+Object::Remote messages set this variable to the names of any Object::Remote::Logging subclass or 
+Object::Remote::Logging itself seperated by a space. To output all logs generated set the value
+to *.
+
+=item OBJECT_REMOTE_LOG_FORWARDING
+
+Object::Remote can forward log events from the remote Perl interpreter to the local Perl
+interpreter in a transparent way. Currently this feature is disabled by default but
+that will change Really Soon Now(TM); to enable it set the variable to '1'.
+
+=back