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.