NAME

       Object::Remote::Logging - Logging subsystem for Object::Remote

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

         $ENV{OBJECT_REMOTE_LOG_LEVEL} = 'trace'; #or other level name
         $ENV{OBJECT_REMOTE_LOG_FORMAT} = '%l %t: %p::%m %s'; #and more
         #Output logs from two specific logging packages
         $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} = 1; #default 0

         log_info { 'Trace log event' };
         Dlog_verbose { "Debug event with Data::Dumper::Concise: $_" } { foo => 'bar' };

DESCRIPTION

       This is the logging framework for Object::Remote implemented as an extension of
       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 Object::Remote::Logging::Logger which implements
       log rendering and output and Object::Remote::Logging::Router which delivers log events to
       the loggers.

USAGE

       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 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 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 formatted the same way.

       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 formatted 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 separated 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 hyphen 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 Object::Remote::Logging::Logger to be built 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.  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 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.

EXPORTABLE SUBROUTINES

       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.

       router
           Returns the instance of Object::Remote::Logging::Router that is in use. The router
           instance is used in combination with Object::Remote::Logging::Logger objects to select
           then render and output log messages.

       log_<level> and Dlog_<level>
           These methods come direct from 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' );

       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';

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:

       trace
           As much information about operation as possible including multiple line dumps of large
           content. Tripple verbose operation (-v -v -v).

       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).

       verbose
           Additional optional messages to the user that can be enabled at their will. Single
           verbose operation (-v).

       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.

       warn
           Something wasn't supposed to happen but did. Operation was not impacted but otherwise
           the event is noteworthy. Single quiet operation (-q).

       error
           Something went wrong. Operation of the system may continue but some operation has most
           definitely failed. Double quiet operation (-q -q).

       fatal
           Something went wrong and recovery is not possible. The system should stop operating as
           soon as possible. Tripple quiet operation (-q -q -q).