From: Tyler Riddle Date: Fri, 9 Nov 2012 01:04:58 +0000 (-0800) Subject: add self to contributor list; document new env variables in Object::Remote POD; add... X-Git-Tag: v0.003001_01~77 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=scpubgit%2FObject-Remote.git;a=commitdiff_plain;h=d672a9bff87112bf8cfea0a5749e934d4c8c996e add self to contributor list; document new env variables in Object::Remote POD; add documentation for logging system to Object::Remote::Logging POD --- diff --git a/lib/Object/Remote.pm b/lib/Object/Remote.pm index feee52a..03095a5 100644 --- a/lib/Object/Remote.pm +++ b/lib/Object/Remote.pm @@ -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. + +=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. + +=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. + +=back + =head1 SUPPORT IRC: #web-simple on irc.perl.org @@ -142,6 +177,8 @@ mst - Matt S. Trout (cpan:MSTROUT) phaylon - Robert Sedlacek (cpan:PHAYLON) +triddle - Tyler Riddle (cpan:TRIDDLE) + =head1 SPONSORS Parts of this code were paid for by diff --git a/lib/Object/Remote/Logging.pm b/lib/Object/Remote/Logging.pm index d99ca44..4811048 100644 --- a/lib/Object/Remote/Logging.pm +++ b/lib/Object/Remote/Logging.pm @@ -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 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 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 that is in use. The router +instance is used in combination with L objects to +select then render and output log messages. + +=item log_ and Dlog_ + +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 +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_ and DlogS_ + +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_ + +Log an event and then generate an exception by calling die() with the log message. + + Elog_error { "Could not open file: $!" }; + +=item Flog_ + +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 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