1Object::Remote::LoggingU:s:eLrogCgoenrt(r3i)buted Perl DOobcjuemcetn:t:aRteimoonte::Logging::Logger(3)
2
3
4

NAME

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

SYNOPSIS

9         use Object::Remote::Logging::Logger;
10         use Object::Remote::Logging qw( router arg_levels );
11
12         my $app_output = Object::Remote::Logging::Logger->new(
13           level_names => arg_levels, format => '%t %s',
14           min_level => 'verbose', max_level => 'info',
15         );
16
17         #Selector method can return 0 or more logger
18         #objects that will receive the messages
19         my $selector = sub {
20           my ($generating_package, $metadata) = @_;
21           return unless $metadata->{exporter} eq 'App::Logging::Subclass';
22           return $app_output;
23         };
24
25         #true value as second argument causes the selector
26         #to be stored with a weak reference
27         router->connect($selector, 1);
28
29         #disconnect the selector from the router
30         undef($selector);
31
32         #router will hold this logger forever
33         #and send it all log messages
34         router->connect(Object::Remote::Logging::Logger->new(
35           level_names => arg_levels, format => '%s at %f line %i, log level: %l'
36           min_level => 'warn', max_level => 'error',
37         ));
38

DESCRIPTION

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

USAGE

48       A logger object receives the log messages that are generated and
49       converts them to formatted log entries then displays them to the end
50       user. Each logger has a set of active log levels and will only output a
51       log entry if the log message is at an active log level.
52
53       To gain access to the stream of log messages a connection is made to
54       the log router.  A logger can directly connect to the router and
55       receive an unfiltered stream of log messages or a selector closure can
56       be used instead. The selector will be executed for each log message
57       with the message metadata and returns a list of 0 or more loggers that
58       should receive the log message. When the selector is executed the first
59       argument is the name of the package that generated the log message and
60       the second argument is a hash reference containing the message
61       metadata.
62

METADATA

64       The message metadata is a hash reference with the following keys:
65
66       message_level
67           Name of the log level of the message.
68
69       exporter
70           Package name of the logging API that was used to generate the log
71           message.
72
73       caller_package
74           Name of the package that generated the log message.
75
76       method
77           Name of the method the message was generated inside of.
78
79       timestamp
80           Unix time of the message generation.
81
82       pid Process id of the Perl interpreter the message was generated in.
83
84       hostname
85           Hostname of the system where the message was generated.
86
87       filename
88           Name of the file the message was generated in.
89
90       line
91           Line of the source file the message was generated at.
92
93       object_remote
94           This is a reference to another hash that contains the
95           Object::Remote specific information. The keys are
96
97           connection_id
98               If the log message was generated on a remote Perl interpreter
99               then the Object::Remote::Connection id of that interpreter will
100               be available here.
101

ATTRIBUTES

103       level_names
104           This is a required attribute. Must be an array ref with the list of
105           log level names in it. The list must be ordered with the lowest
106           level as element 0 and the highest level as the last element. There
107           is no default value.
108
109       min_level
110           The lowest log level that will be output by the logger. There is no
111           default value.
112
113       max_level
114           The highest log level that will be output by the logger. The
115           default value is the highest level present in level_names.
116
117       format
118           The printf style format string to use when rendering the log
119           message. The following sequences are significant:
120
121           %l  Level name that the log message was generated at.
122
123           %s  Log message rendered into a string with a leading space before
124               any additional lines in a multiple line message.
125
126           %t  Time the log message was generated rendered into a string. The
127               time value is taken from the Perl interpreter that generated
128               the log message; it is not the time that the logger received
129               the log message on the local interpreter if the log message was
130               forwarded.
131
132           %r  Object::Remote connection information rendered into a string.
133
134           %c  Package name of the logging API that was used to generate the
135               log message.
136
137           %p  Name of the package that generated the log message.
138
139           %m  Method name that generated the log message.
140
141           %f  Filename that the log message was generated in.
142
143           %i  Line number the log message was generated at.
144
145           %h  Hostname the log message was generated on.
146
147           %P  Process id of the Perl interpreter that generated the log
148               message.
149
150           %%  A literal %.
151
152           %n  A newline.
153
154
155
156perl v5.34.0                      2022-01-21Object::Remote::Logging::Logger(3)
Impressum