.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Object::Remote::Logging::Logger 3pm"
.TH Object::Remote::Logging::Logger 3pm "2013-03-19" "perl v5.20.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Object::Remote::Logging::Logger \- Format and output a log message
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  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 => \*(Aq%t %s\*(Aq,
\&    min_level => \*(Aqverbose\*(Aq, max_level => \*(Aqinfo\*(Aq,
\&  );
\&
\&  #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 \*(AqApp::Logging::Subclass\*(Aq;
\&    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 => \*(Aq%s at %f line %i, log level: %l\*(Aq
\&    min_level => \*(Aqwarn\*(Aq, max_level => \*(Aqerror\*(Aq,
\&  ));
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class receives log messages from an instance of Object::Remote::Logging::Router,
formats them according to configuration, and then outputs them to \s-1STDERR.\s0 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.
.SH "USAGE"
.IX Header "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.
.PP
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.
.SH "METADATA"
.IX Header "METADATA"
The message metadata is a hash reference with the following keys:
.IP "message_level" 4
.IX Item "message_level"
Name of the log level of the message.
.IP "exporter" 4
.IX Item "exporter"
Package name of the logging \s-1API\s0 that was used to generate the log message.
.IP "caller_package" 4
.IX Item "caller_package"
Name of the package that generated the log message.
.IP "method" 4
.IX Item "method"
Name of the method the message was generated inside of.
.IP "timestamp" 4
.IX Item "timestamp"
Unix time of the message generation.
.IP "pid" 4
.IX Item "pid"
Process id of the Perl interpreter the message was generated in.
.IP "hostname" 4
.IX Item "hostname"
Hostname of the system where the message was generated.
.IP "filename" 4
.IX Item "filename"
Name of the file the message was generated in.
.IP "line" 4
.IX Item "line"
Line of the source file the message was generated at.
.IP "object_remote" 4
.IX Item "object_remote"
This is a reference to another hash that contains the Object::Remote
specific information. The keys are
.RS 4
.IP "connection_id" 4
.IX Item "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.
.RE
.RS 4
.RE
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.IP "level_names" 4
.IX Item "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.
.IP "min_level" 4
.IX Item "min_level"
The lowest log level that will be output by the logger. There is no default value.
.IP "max_level" 4
.IX Item "max_level"
The highest log level that will be output by the logger. The default value is the
highest level present in level_names.
.IP "format" 4
.IX Item "format"
The printf style format string to use when rendering the log message. The following
sequences are significant:
.RS 4
.ie n .IP "%l" 4
.el .IP "\f(CW%l\fR" 4
.IX Item "%l"
Level name that the log message was generated at.
.ie n .IP "%s" 4
.el .IP "\f(CW%s\fR" 4
.IX Item "%s"
Log message rendered into a string with a leading space before any additional lines in a
multiple line message.
.ie n .IP "%t" 4
.el .IP "\f(CW%t\fR" 4
.IX Item "%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.
.ie n .IP "%r" 4
.el .IP "\f(CW%r\fR" 4
.IX Item "%r"
Object::Remote connection information rendered into a string.
.ie n .IP "%c" 4
.el .IP "\f(CW%c\fR" 4
.IX Item "%c"
Package name of the logging \s-1API\s0 that was used to generate the log message.
.ie n .IP "%p" 4
.el .IP "\f(CW%p\fR" 4
.IX Item "%p"
Name of the package that generated the log message.
.ie n .IP "%m" 4
.el .IP "\f(CW%m\fR" 4
.IX Item "%m"
Method name that generated the log message.
.ie n .IP "%f" 4
.el .IP "\f(CW%f\fR" 4
.IX Item "%f"
Filename that the log message was generated in.
.ie n .IP "%i" 4
.el .IP "\f(CW%i\fR" 4
.IX Item "%i"
Line number the log message was generated at.
.ie n .IP "%h" 4
.el .IP "\f(CW%h\fR" 4
.IX Item "%h"
Hostname the log message was generated on.
.ie n .IP "%P" 4
.el .IP "\f(CW%P\fR" 4
.IX Item "%P"
Process id of the Perl interpreter that generated the log message.
.IP "%%" 4
A literal %.
.ie n .IP "%n" 4
.el .IP "\f(CW%n\fR" 4
.IX Item "%n"
A newline.
.RE
.RS 4
.RE