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

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: