1Object::Remote::LoggingU(s3e)r Contributed Perl DocumentaOtbijoenct::Remote::Logging(3)
2
3
4

NAME

6       Object::Remote::Logging - Logging subsystem for Object::Remote
7

SYNOPSIS

9         use Object::Remote::Logging qw( :log :dlog arg_levels router );
10
11         $levels = [qw( trace debug verbose info warn error fatal )];
12         $levels = arg_levels(); #same result
13
14         $ENV{OBJECT_REMOTE_LOG_LEVEL} = 'trace'; #or other level name
15         $ENV{OBJECT_REMOTE_LOG_FORMAT} = '%l %t: %p::%m %s'; #and more
16         #Output logs from two specific logging pacakges
17         $ENV{OBJECT_REMOTE_LOG_SELECTIONS} = 'Object::Remote::Logging Some::Other::Package';
18         #Output all log messages except those generated by Object::Remote
19         $ENV{OBJECT_REMOTE_LOG_SELECTIONS} = '* -Object::Remote::Logging';
20         $ENV{OBJECT_REMOTE_LOG_FORWARDING} = 1; #default 0
21
22         log_info { 'Trace log event' };
23         Dlog_verbose { "Debug event with Data::Dumper::Concise: $_" } { foo => 'bar' };
24

DESCRIPTION

26       This is the logging framework for Object::Remote implemented as an
27       extension of Log::Contextual with a slightly incompatible API. This
28       system allows developers using Object::Remote and end users of that
29       software to control Object::Remote logging so operation can be tracked
30       if needed. This is also the API used to generate log messages inside
31       the Object::Remote source code.
32
33       The rest of the logging system comes from
34       Object::Remote::Logging::Logger which implements log rendering and
35       output and Object::Remote::Logging::Router which delivers log events to
36       the loggers.
37

USAGE

39       Object::Remote logging output is not enabled by default. If you need to
40       immediately start debugging set the OBJECT_REMOTE_LOG_LEVEL environment
41       variable to either 'trace' or 'debug'. This will enable logging to
42       STDERR on the local and all remote Perl interpreters. By default STDERR
43       for all remote interpreters is passed through unmodified so this is
44       sufficient to receive logs generated anywhere Object::Remote is
45       running.
46
47       Every time the local interpreter creates a new
48       Object::Remote::Connection the connection is given an id that is unique
49       to that connection on the local interpreter. The connection id and
50       other metadata is available in the log output via a log format string
51       that can be set via the OBJECT_REMOTE_LOG_FORMAT environment variable.
52       The format string and available metadata is documented in
53       Object::Remote::Logging::Logger. Setting this environment variable on
54       the local interpreter will cause it to be propagated to the remote
55       interpreter so all logs will be formated the same way.
56
57       This system is designed so any module can create their own logging
58       packages using it.  With out any additional configuration the consumers
59       of this logging system will automatically be enabled via
60       OBJECT_REMOTE_LOG_LEVEL and formated with OBJECT_REMOTE_LOG_FORMAT but
61       those additional log messages are not sent to STDERR.  By setting the
62       OBJECT_REMOTE_LOG_SELECTIONS environment variable to a list of logging
63       package names seperated by spaces then logs generated using those
64       packages will be sent to STDERR. If the asterisk character (*) is used
65       in the place of a package name then all package names will be selected
66       by default instead of ignored. An individual package name can be turned
67       off by prefixing the name with a hypen character (-). This is also a
68       configuration item that is forwarded to the remote interpreters so all
69       logging is consistent.
70
71       Regardless of OBJECT_REMOTE_LOG_LEVEL the logging system is still
72       active and loggers can access the stream of log messages to format and
73       output them. Internally OBJECT_REMOTE_LOG_LEVEL causes an
74       Object::Remote::Logging::Logger to be built and connected to the
75       Object::Remote::Logging::Router instance. It is also possible to
76       manually build a logger instance and connect it to the router. See the
77       Object::Remote::Logging documentation for more information.
78
79       The logging system also supports a method of forwarding log messages
80       from remote interpreters to the local interpreter. Forwarded log
81       messages are generated in the remote interpreter and the logger for the
82       message is invoked in the local interpreter.  Packages using or
83       extending Object::Remote::Logging will have log messages forwarded
84       automatically.  Loggers receive forwarded log messages exactly the same
85       way as non-forwarded messages except a forwarded message includes extra
86       metadata about the remote connection. Log forwarding is disabled by
87       default because it comes with a performance hit; to enable it set the
88       OBJECT_REMOTE_LOG_FORWARDING environment variable to 1.
89

EXPORTABLE SUBROUTINES

91       arg_levels
92           Returns an array reference that contains the ordered list of level
93           names with the lowest log level first and the highest log level
94           last.
95
96       router
97           Returns the instance of Object::Remote::Logging::Router that is in
98           use. The router instance is used in combination with
99           Object::Remote::Logging::Logger objects to select then render and
100           output log messages.
101
102       log_<level> and Dlog_<level>
103           These methods come direct from Log::Contextual; see that
104           documentation for a complete reference. For each of the log level
105           names there are subroutines with the log_ and Dlog_ prefix that
106           will generate the log message. The first argument is a code block
107           that returns the log message contents and the optional further
108           arguments are both passed to the block as the argument list and
109           returned from the log method as a list.
110
111             log_trace { "A fine log message $_[0] " } 'if I do say so myself';
112             %hash = Dlog_trace { "Very handy: $_" } ( foo => 'bar' );
113
114       logS_<level> and DlogS_<level>
115           Works just like log_ and Dlog_ except returns only the first
116           argument as a scalar value.
117
118             my $beverage = logS_info { "Customer ordered $_[0]" } 'Coffee';
119

LEVEL NAMES

121       Object::Remote uses an ordered list of log level names with the lowest
122       level first and the highest level last. The list of level names can be
123       accessed via the arg_levels method which is exportable to the consumer
124       of this class. The log level names are:
125
126       trace
127           As much information about operation as possible including multiple
128           line dumps of large content. Tripple verbose operation (-v -v -v).
129
130       debug
131           Messages about operations that could hang as well as internal state
132           changes, results from method invocations, and information useful
133           when looking for faults.  Double verbose operation (-v -v).
134
135       verbose
136           Additional optional messages to the user that can be enabled at
137           their will. Single verbose operation (-v).
138
139       info
140           Messages from normal operation that are intended to be displayed to
141           the end user if quiet operation is not indicated and more verbose
142           operation is not in effect.
143
144       warn
145           Something wasn't supposed to happen but did. Operation was not
146           impacted but otherwise the event is noteworthy. Single quiet
147           operation (-q).
148
149       error
150           Something went wrong. Operation of the system may continue but some
151           operation has most definitely failed. Double quiet operation (-q
152           -q).
153
154       fatal
155           Something went wrong and recovery is not possible. The system
156           should stop operating as soon as possible. Tripple quiet operation
157           (-q -q -q).
158
159
160
161perl v5.36.0                      2023-01-20        Object::Remote::Logging(3)
Impressum