NAME

       Object::Remote::Logging::Logger - Format and output a log message

SYNOPSIS

         use Object::Remote::Logging::Logger;
         use Object::Remote::Logging qw( router arg_levels );

         my $app_output = Object::Remote::Logging::Logger->new(
           level_names => arg_levels, format => '%t %s',
           min_level => 'verbose', max_level => 'info',
         );

         #Selector method can return 0 or more logger
         #objects that will receive the messages
         my $selector = sub {
           my ($generating_package, $metadata) = @_;
           return unless $metadata->{exporter} eq 'App::Logging::Subclass';
           return $app_output;
         };

         #true value as second argument causes the selector
         #to be stored with a weak reference
         router->connect($selector, 1);

         #disconnect the selector from the router
         undef($selector);

         #router will hold this logger forever
         #and send it all log messages
         router->connect(Object::Remote::Logging::Logger->new(
           level_names => arg_levels, format => '%s at %f line %i, log level: %l'
           min_level => 'warn', max_level => 'error',
         ));

DESCRIPTION

       This class receives log messages from an instance of Object::Remote::Logging::Router,
       formats them according to configuration, and then outputs them to STDERR. In between the
       router and the logger is a selector method which inspects the log message metadata and can
       return 0 or more loggers that should receive the log message.

USAGE

       A logger object receives the log messages that are generated and converts them to
       formatted log entries then displays them to the end user. Each logger has a set of active
       log levels and will only output a log entry if the log message is at an active log level.

       To gain access to the stream of log messages a connection is made to the log router.  A
       logger can directly connect to the router and receive an unfiltered stream of log messages
       or a selector closure can be used instead. The selector will be executed for each log
       message with the message metadata and returns a list of 0 or more loggers that should
       receive the log message. When the selector is executed the first argument is the name of
       the package that generated the log message and the second argument is a hash reference
       containing the message metadata.

METADATA

       The message metadata is a hash reference with the following keys:

       message_level
           Name of the log level of the message.

       exporter
           Package name of the logging API that was used to generate the log message.

       caller_package
           Name of the package that generated the log message.

       method
           Name of the method the message was generated inside of.

       timestamp
           Unix time of the message generation.

       pid Process id of the Perl interpreter the message was generated in.

       hostname
           Hostname of the system where the message was generated.

       filename
           Name of the file the message was generated in.

       line
           Line of the source file the message was generated at.

       object_remote
           This is a reference to another hash that contains the Object::Remote specific
           information. The keys are

           connection_id
               If the log message was generated on a remote Perl interpreter then the
               Object::Remote::Connection id of that interpreter will be available here.

ATTRIBUTES

       level_names
           This is a required attribute. Must be an array ref with the list of log level names in
           it. The list must be ordered with the lowest level as element 0 and the highest level
           as the last element. There is no default value.

       min_level
           The lowest log level that will be output by the logger. There is no default value.

       max_level
           The highest log level that will be output by the logger. The default value is the
           highest level present in level_names.

       format
           The printf style format string to use when rendering the log message. The following
           sequences are significant:

           %l  Level name that the log message was generated at.

           %s  Log message rendered into a string with a leading space before any additional
               lines in a multiple line message.

           %t  Time the log message was generated rendered into a string. The time value is taken
               from the Perl interpreter that generated the log message; it is not the time that
               the logger received the log message on the local interpreter if the log message
               was forwarded.

           %r  Object::Remote connection information rendered into a string.

           %c  Package name of the logging API that was used to generate the log message.

           %p  Name of the package that generated the log message.

           %m  Method name that generated the log message.

           %f  Filename that the log message was generated in.

           %i  Line number the log message was generated at.

           %h  Hostname the log message was generated on.

           %P  Process id of the Perl interpreter that generated the log message.

           %%  A literal %.

           %n  A newline.