lib/Object/Remote/Logging.pm

   1 package Object::Remote::Logging;
   2
   3 use Moo;
   4 use Scalar::Util qw(blessed);
   5 use Object::Remote::Logging::Logger;
   6 use Exporter::Declare;
   7 use Carp qw(carp croak);
   8
   9 extends 'Log::Contextual';
  10
  11 exports(qw( ____ router arg_levels ));
  12 #exception log - log a message then die with that message
  13 export_tag elog => ('____');
  14 #fatal log - log a message then call exit(1)
  15 export_tag flog => ('____');
  16
  17 sub router {
  18   our $Router_Instance ||= do {
  19     require Object::Remote::Logging::Router;
  20     Object::Remote::Logging::Router->new;
  21   }
  22 }
  23
  24 #log level descriptions
  25 #info - standard log level - normal program output for the end user
  26 #warn - output for program that is executing quietly
  27 #error - output for program that is running more quietly
  28 #fatal - it is not possible to continue execution; this level is as quiet as is possible
  29 #verbose - output for program executing verbosely (-v)
  30 #debug - output for program running more verbosely (-v -v)
  31 #trace - output for program running extremely verbosely (-v -v -v)
  32 sub arg_levels {
  33   #the order of the log levels is significant with the
  34   #most verbose level being first in the list and the
  35   #most quiet as the last item
  36   return [qw( trace debug verbose info warn error fatal )];
  37 }
  38
  39 sub before_import {
  40    my ($class, $importer, $spec) = @_;
  41    my $router = $class->router;
  42
  43    $class->SUPER::before_import($importer, $spec);
  44
  45    my @levels = @{$class->arg_levels($spec->config->{levels})};
  46    for my $level (@levels) {
  47       if ($spec->config->{elog}) {
  48          $spec->add_export("&Elog_$level", sub (&) {
  49             my ($code, @args) = @_;
  50             $router->handle_log_request({
  51                controller => $class,
  52                package => scalar(caller),
  53                caller_level => 1,
  54                level => $level,
  55             }, $code);
  56             #TODO this should get fed into a logger so it can be formatted
  57             croak $code->();
  58          });
  59       }
  60       if ($spec->config->{flog}) {
  61          #TODO that prototype isn't right
  62          $spec->add_export("&Flog_$level", sub (&@) {
  63             my ($code, $exit_value) = @_;
  64             $exit_value = 1 unless defined $exit_value;
  65             #don't let it going wrong stop us from calling exit()
  66             eval { $router->handle_log_request({
  67                controller => $class,
  68                package => scalar(caller),
  69                caller_level => 1,
  70                level => $level,
  71             }, $code) };
  72             warn "could not deliver log event during Flog_$level: $@" if defined $@;
  73             eval { carp $code->() };
  74             warn "could not emit warning during Flog_$level: $@" if defined $@;
  75             exit($exit_value);
  76          });
  77       }
  78    }
  79 }
  80
  81 #this is invoked on all nodes
  82 sub init_logging {
  83   my $level = $ENV{OBJECT_REMOTE_LOG_LEVEL};
  84   my $format = $ENV{OBJECT_REMOTE_LOG_FORMAT};
  85   my $selections = $ENV{OBJECT_REMOTE_LOG_SELECTIONS};
  86   my %controller_should_log;
  87
  88   return unless defined $level;
  89   $format = "[%l %r] %s" unless defined $format;
  90   $selections = __PACKAGE__ unless defined $selections;
  91   %controller_should_log = map { $_ => 1 } split(' ', $selections);
  92
  93   my $logger = Object::Remote::Logging::Logger->new(
  94     min_level => lc($level), format => $format,
  95     level_names => Object::Remote::Logging::arg_levels(),
  96   );
  97
  98   router()->connect(sub {
  99     my $controller = $_[1]->{controller};
 100     return unless $controller_should_log{'*'} || $controller_should_log{$controller};
 101     #skip things from remote hosts because they log to STDERR
 102     #when OBJECT_REMOTE_LOG_LEVEL is in effect
 103     return if $_[1]->{remote}->{connection_id};
 104     $logger
 105   });
 106 }
 107
 108 #this is invoked by the controlling node
 109 #on the remote nodes
 110 sub init_logging_forwarding {
 111   my ($self, %controller_info) = @_;
 112
 113   router()->_remote_metadata({ connection_id => $controller_info{connection_id} });
 114   router()->_forward_destination($controller_info{router}) if $ENV{OBJECT_REMOTE_LOG_FORWARDING};
 115 }
 116
 117 1;
 118
 119 __END__
 120
 121 =head1 NAME
 122
 123 Object::Remote::Logging - Logging subsystem for Object::Remote
 124
 125 =head1 SYNOPSIS
 126
 127   use Object::Remote::Logging qw( :log :dlog :elog :flog arg_levels router );
 128
 129   @levels = qw( trace debug verbose info warn error fatal );
 130   @levels = arg_levels(); #same result
 131
 132   $ENV{OBJECT_REMOTE_LOG_LEVEL} = 'trace'; #or other level name
 133   $ENV{OBJECT_REMOTE_LOG_FORMAT} = '%l %t: %p::%m %s'; #and more
 134   $ENV{OBJECT_REMOTE_LOG_SELECTIONS} = 'Object::Remote::Logging Some::Other::Subclass';
 135   $ENV{OBJECT_REMOTE_LOG_FORWARDING} = 0 || 1; #default 0
 136
 137   log_info { 'Trace log event' };
 138   Dlog_verbose { "Debug event with Data::Dumper::Concise: $_" } { foo => 'bar' };
 139   Elog_error { 'Error event that calls die() with this string' };
 140   Flog_fatal { 'Fatal event calls warn() then exit()' } 1;
 141
 142 =head1 DESCRIPTION
 143
 144 This is the logging framework for Object::Remote implemented as a subclass of
 145 L<Log::Contextual> with a slightly incompatible API. This system allows
 146 developers using Object::Remote and end users of that software to control
 147 Object::Remote logging so operation can be tracked if needed. This is also
 148 the API used to generate log messages inside the Object::Remote source code.
 149
 150 The rest of the logging system comes from L<Object::Remote::Logging::Logger>
 151 which implements log rendering and output and L<Object::Remote::Logging::Router>
 152 which delivers log events to the loggers.
 153
 154 =head1 USAGE
 155
 156 Object::Remote logging is not enabled by default. If you need to immediately start
 157 debugging set the OBJECT_REMOTE_LOG_LEVEL environment variable to either 'trace'
 158 or 'debug'. This will enable logging to STDERR on the local and all remote Perl
 159 interpreters. By default STDERR for all remote interpreters is passed through
 160 unmodified so this is sufficient to receive logs generated anywhere Object::Remote
 161 is running.
 162
 163 Every time the local interpreter creates a new Object::Remote::Connection the connection
 164 is given an id that is unique to that connection on the local interpreter. The connection
 165 id and other metadata is available in the log output via a log format string that can
 166 be set via the OBJECT_REMOTE_LOG_FORMAT environment variable. The format string and
 167 available metadata is documented in L<Object::Remote::Logging::Logger>. Setting this
 168 environment variable on the local interpreter will cause it to be propagated to the
 169 remote interpreter so all logs will be formated the same way.
 170
 171 This class is designed so any module can create their own logging sub-class using it.
 172 With out any additional configuration the consumers of this logging class will
 173 automatically be enabled via OBJECT_REMOTE_LOG_LEVEL and formated with
 174 OBJECT_REMOTE_LOG_FORMAT but those additional log messages are not sent to STDERR.
 175 By setting the  OBJECT_REMOTE_LOG_SELECTIONS environment variable to a list of
 176 class names seperated by spaces then logs generated by packages that use those classes
 177 will be sent to STDERR. This is also a configuration item that is forwarded to the
 178 remote interpreters so all logging is consistent.
 179
 180 Regardless of OBJECT_REMOTE_LOG_LEVEL the logging system is still active and loggers
 181 can access the stream of log messages to format and output them. Internally
 182 OBJECT_REMOTE_LOG_LEVEL causes an L<Object::Remote::Logging::Logger> to be built
 183 and connected to the L<Object::Remote::Logging::Router> instance. It is also possible
 184 to manually build a logger instance and connect it to the router. See the documentation
 185 for the logger and router classes.
 186
 187 The logging system also supports a method of forwarding log messages from remote
 188 interpreters to the local interpreter. Forwarded log messages are generated in the
 189 remote interpreter and the logger for the message is invoked in the local interpreter.
 190 Sub-classes of Object::Remote::Logging will have log messages forwarded automatically.
 191 Loggers receive forwarded log messages exactly the same way as non-forwarded messages
 192 except a forwarded message includes extra metadata about the remote interpreter. Log
 193 forwarding is not currently enabled by default; to enable it set the
 194 OBJECT_REMOTE_LOG_FORWARDING environment variable to 1. See L<Object::Remote::Logging::Router>.
 195
 196 =head1 EXPORTABLE SUBROUTINES
 197
 198 =over 4
 199
 200 =item arg_levels
 201
 202 Returns an array reference that contains the ordered list of level names
 203 with the lowest log level first and the highest log level last.
 204
 205 =item router
 206
 207 Returns the instance of L<Object::Remote::Logging::Router> that is in use. The router
 208 instance is used in combination with L<Object::Remote::Logging::Logger> objects to
 209 select then render and output log messages.
 210
 211 =item log_<level> and Dlog_<level>
 212
 213 These methods come direct from L<Log::Contextual>; see that documentation for a
 214 complete reference. For each of the log level names there are subroutines with the log_
 215 and Dlog_ prefix that will generate the log message. The first argument is a code block
 216 that returns the log message contents and the optional further arguments are both passed
 217 to the block as the argument list and returned from the log method as a list.
 218
 219   log_trace { "A fine log message $_[0] " } 'if I do say so myself';
 220   %hash = Dlog_trace { "Very handy: $_" } ( foo => 'bar' );
 221
 222 =item logS_<level> and DlogS_<level>
 223
 224 Works just like log_ and Dlog_ except returns only the first argument as a scalar value.
 225
 226   my $beverage = log_info { "Customer ordered $_[0]" } 'Coffee';
 227
 228 =item Elog_<level>
 229
 230 Log an event and then generate an exception by calling die() with the log message.
 231
 232   Elog_error { "Could not open file: $!" };
 233
 234 =item Flog_<level>
 235
 236 Log the event, generate a warning with the log message, then call exit(). The exit
 237 value will default to 1 or can be specified as an argument.
 238
 239   Flog_fatal { 'Could not lock resource' } 3;
 240
 241 =back
 242
 243 =head1 LEVEL NAMES
 244
 245 Object::Remote uses an ordered list of log level names with the minimum level
 246 first and the maximum level last. The list of level names can be accessed via
 247 the arg_levels method which is exportable to the consumer of this class. The log
 248 level names are:
 249
 250 =over 4
 251
 252 =item trace
 253
 254 As much information about operation as possible including multiple line dumps of
 255 large content. Tripple verbose operation (-v -v -v).
 256
 257 =item debug
 258
 259 Messages about operations that could hang as well as internal state changes,
 260 results from method invocations, and information useful when looking for faults.
 261 Double verbose operation (-v -v).
 262
 263 =item verbose
 264
 265 Additional optional messages to the user that can be enabled at their will. Single
 266 verbose operation (-v).
 267
 268 =item info
 269
 270 Messages from normal operation that are intended to be displayed to the end
 271 user if quiet operation is not indicated and more verbose operation is not
 272 in effect.
 273
 274 =item warn
 275
 276 Something wasn't supposed to happen but did. Operation was not impacted but
 277 otherwise the event is noteworthy. Single quiet operation (-q).
 278
 279 =item error
 280
 281 Something went wrong. Operation of the system may continue but some operation
 282 has most definitely failed. Double quiet operation (-q -q).
 283
 284 =item fatal
 285
 286 Something went wrong and recovery is not possible. The system should stop operating
 287 as soon as possible. Tripple quiet operation (-q -q -q).
 288
 289 =back