1Log::Report::DispatcherU(s3e)r Contributed Perl DocumentaLtoigo:n:Report::Dispatcher(3)
2
3
4
6 Log::Report::Dispatcher - manage message dispatching, display or
7 logging
8
10 Log::Report::Dispatcher is extended by
11 Log::Report::Dispatcher::Callback
12 Log::Report::Dispatcher::File
13 Log::Report::Dispatcher::Log4perl
14 Log::Report::Dispatcher::LogDispatch
15 Log::Report::Dispatcher::Perl
16 Log::Report::Dispatcher::Syslog
17 Log::Report::Dispatcher::Try
18
20 use Log::Report;
21
22 # The following will be created for you automatically
23 dispatcher 'PERL', 'default', accept => 'NOTICE-';
24 dispatcher close => 'default'; # after deamonize
25
26 dispatcher 'FILE', 'log'
27 , mode => 'DEBUG', to => '/var/log/mydir/myfile';
28
29 # Full package name is used, same as 'FILE'
30 dispatcher Log::Report::Dispatch::File => 'stderr'
31 , to => \*STDERR, accept => 'NOTICE-';
32
34 In Log::Report, dispatchers are used to handle (exception) messages
35 which are created somewhere else. Those message were produced (thrown)
36 by Log::Report::error() and friends.
37
38 This base-class handles the creation of dispatchers, plus the common
39 filtering rules. See the "DETAILS" section, below.
40
42 Constructors
43 $obj->close()
44 Terminate the dispatcher activities. The dispatcher gets disabled,
45 to avoid the case that it is accidentally used. Returns "undef"
46 (false) if the dispatcher was already closed.
47
48 Log::Report::Dispatcher->new($type, $name, %options)
49 Create a dispatcher. The $type of back-end to start is required,
50 and listed in the "DESCRIPTION" part of this manual-page. For
51 various external back-ends, special wrappers are created.
52
53 The $name must be uniquely identifying this dispatcher. When a
54 second dispatcher is created (via Log::Report::dispatcher()) with
55 the name of an existing dispatcher, the existing one will get
56 replaced.
57
58 All %options which are not consumed by this base constructor are
59 passed to the wrapped back-end. Some of them will check whether
60 all %options are understood, other ignore unknown %options.
61
62 -Option --Default
63 accept depend on mode
64 charset <undef>
65 format_reason 'LOWERCASE'
66 locale <system locale>
67 mode 'NORMAL'
68
69 accept => REASONS
70 See Log::Report::Util::expand_reasons() for possible values. If
71 the initial mode for this dispatcher does not need verbose or
72 debug information, then those levels will not be accepted.
73
74 When the mode equals "NORMAL" (the default) then "accept"'s
75 default is "NOTICE-". In case of "VERBOSE" it will be "INFO-",
76 "ASSERT" results in "ASSERT-", and "DEBUG" in "ALL".
77
78 charset => CHARSET
79 Convert the messages in the specified character-set (codeset).
80 By default, no conversion will take place, because the right
81 choice cannot be determined automatically.
82
83 format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
84 How to show the reason text which is printed before the message.
85 When a CODE is specified, it will be called with a translated
86 text and the returned text is used.
87
88 locale => LOCALE
89 Overrules the global setting. Can be overruled by
90 Log::Report::report(locale).
91
92 mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
93 Possible values are "NORMAL" (or 0 or "undef"), which will not
94 show "INFO" or debug messages, "VERBOSE" (1; shows "INFO" not
95 debug), "ASSERT" (2; only ignores "TRACE" messages), or "DEBUG"
96 (3) which shows everything. See section "Run modes" in
97 Log::Report.
98
99 You are advised to use the symbolic mode names when the mode is
100 changed within your program: the numerical values are available
101 for smooth Getopt::Long integration.
102
103 Accessors
104 $obj->isDisabled()
105 $obj->mode()
106 Returns the mode in use for the dispatcher as number. See
107 new(mode) and "Run modes" in Log::Report.
108
109 $obj->name()
110 Returns the unique name of this dispatcher.
111
112 $obj->needs( [$reason] )
113 Returns the list with all REASONS which are needed to fulfill this
114 dispatcher's needs. When disabled, the list is empty, but not
115 forgotten.
116
117 [0.999] when only one $reason is specified, it is returned if in
118 the list.
119
120 $obj->type()
121 The dispatcher $type, which is usually the same as the class of
122 this object, but not in case of wrappers like for Log::Dispatch.
123
124 Logging
125 $obj->addSkipStack(@CODE)
126 Log::Report::Dispatcher->addSkipStack(@CODE)
127 [1.13] Add one or more CODE blocks of caller lines which should not
128 be collected for stack-traces or location display. A CODE gets
129 called with an ARRAY of caller information, and returns true when
130 that line should get skipped.
131
132 Warning: this logic is applied globally: on all dispatchers.
133
134 example:
135
136 By default, all lines in the Log::Report packages are skipped from
137 display, with a simple CODE as this:
138
139 sub in_lr { $_[0][0] =~ m/^Log\:\:Report(?:\:\:|$)/ }
140 Log::Report::Dispatcher->addSkipStack(\&in_lr);
141
142 The only parameter to in_lr is the return of caller(). The first
143 element of that ARRAY is the package name of a stack line.
144
145 $obj->collectLocation()
146 Log::Report::Dispatcher->collectLocation()
147 Collect the information to be displayed as line where the error
148 occurred.
149
150 $obj->collectStack( [$maxdepth] )
151 Log::Report::Dispatcher->collectStack( [$maxdepth] )
152 Returns an ARRAY of ARRAYs with text, filename, line-number.
153
154 $obj->log(HASH-$of-%options, $reason, $message, $domain)
155 This method is called by Log::Report::report() and should not be
156 called directly. Internally, it will call translate(), which does
157 most $of the work.
158
159 $obj->skipStack()
160 [1.13] Returns the number of nestings in the stack which should be
161 skipped to get outside the Log::Report (and related) modules. The
162 end-user does not want to see those internals in stack-traces.
163
164 $obj->stackTraceLine(%options)
165 Log::Report::Dispatcher->stackTraceLine(%options)
166 -Option --Default
167 abstract 1
168 call <required>
169 filename <required>
170 linenr <required>
171 max_line undef
172 max_params 8
173 package <required>
174 params <required>
175
176 abstract => INTEGER
177 The higher the abstraction value, the less details are given
178 about the caller. The minimum abstraction is specified, and then
179 increased internally to make the line fit within the "max_line"
180 margin.
181
182 call => STRING
183 filename => STRING
184 linenr => INTEGER
185 max_line => INTEGER
186 max_params => INTEGER
187 package => CLASS
188 params => ARRAY
189 $obj->translate(HASH-$of-%options, $reason, $message)
190 See "Processing the message", which describes the actions taken by
191 this method. A string is returned, which ends on a new-line, and
192 may be multi-line (in case a stack trace is produced).
193
195 Available back-ends
196 When a dispatcher is created (via new() or Log::Report::dispatcher()),
197 you must specify the TYPE of the dispatcher. This can either be a
198 class name, which extends a Log::Report::Dispatcher, or a pre-defined
199 abbreviation of a class name. Implemented are:
200
201 Log::Report::Dispatcher::Perl (abbreviation 'PERL')
202 Use Perl's own "print()", "warn()" and "die()" to ventilate
203 reports. This is the default dispatcher.
204
205 Log::Report::Dispatcher::File (abbreviation 'FILE')
206 Logs the message into a file, which can either be opened by the
207 class or be opened before the dispatcher is created.
208
209 Log::Report::Dispatcher::Syslog (abbreviation 'SYSLOG')
210 Send messages into the system's syslog infrastructure, using
211 Sys::Syslog.
212
213 Log::Report::Dispatcher::Callback (abbreviation 'CALLBACK')
214 Calls any CODE reference on receipt of each selected message, for
215 instance to send important message as email or SMS.
216
217 "Log::Dispatch::*"
218 All of the Log::Dispatch::Output extensions can be used directly.
219 The Log::Report::Dispatcher::LogDispatch will wrap around that
220 back-end.
221
222 "Log::Log4perl"
223 Use the Log::Log4perl main object to write to dispatchers. This
224 infrastructure uses a configuration file.
225
226 Log::Report::Dispatcher::Try (abbreviation 'TRY')
227 Used by function Log::Report::try(). It collects the exceptions
228 and can produce them on request.
229
230 Processing the message
231 Addition information
232
233 The modules which use "Log::Report" will only specify the base of the
234 message string. The base dispatcher and the back-ends will extend this
235 message with additional information:
236
237 . the reason
238 . the filename/line-number where the problem appeared
239 . the filename/line-number where it problem was reported
240 . the error text in $!
241 . a stack-trace
242 . a trailing new-line
243
244 When the message is a translatable object (Log::Report::Message, for
245 instance created with Log::Report::__()), then the added components
246 will get translated as well. Otherwise, all will be in English.
247
248 Exactly what will be added depends on the actual mode of the dispatcher
249 (change it with mode(), initiate it with new(mode)).
250
251 mode mode mode mode
252 REASON SOURCE TE! NORM VERB ASSE DEBUG
253 trace program ... S
254 assert program ... SL SL
255 info program T.. S S S
256 notice program T.. S S S S
257 mistake user T.. S S S SL
258 warning program T.. S S SL SL
259 error user TE. S S SL SC
260 fault system TE! S S SL SC
261 alert system T.! SL SL SC SC
262 failure system TE! SL SL SC SC
263 panic program .E. SC SC SC SC
264
265 T - usually translated
266 E - exception (execution interrupted)
267 ! - will include $! text at display
268 L - include filename and linenumber
269 S - show/print when accepted
270 C - stack trace (like Carp::confess())
271
272 Filters
273
274 With a filter, you can block or modify specific messages before
275 translation. There may be a wish to change the REASON of a report or
276 its content. It is not possible to avoid the exit which is related to
277 the original message, because a module's flow depends on it to happen.
278
279 When there are filters defined, they will be called in order of
280 definition. For each of the dispatchers which are called for a certain
281 REASON (which "accept" that REASON), it is checked whether its name is
282 listed for the filter (when no names where specified, then the filter
283 is applied to all dispatchers).
284
285 When selected, the filter's CODE reference is called with four
286 arguments: the dispatcher object (a Log::Report::Dispatcher), the HASH-
287 of-OPTIONS passed as optional first argument to Log::Report::report(),
288 the REASON, and the MESSAGE. Returned is the new REASON and MESSAGE.
289 When the returned REASON is "undef", then the message will be ignored
290 for that dispatcher.
291
292 Be warned about processing the MESSAGE: it is a Log::Report::Message
293 object which may have a "prepend" string and "append" string or object.
294 When the call to Log::Report::report() contained multiple comma-
295 separated components, these will already have been joined together
296 using concatenation (see Log::Report::Message::concat().
297
298 . Example: a filter on syslog
299
300 dispatcher filter => \&myfilter, 'syslog';
301
302 # ignore all translatable and non-translatable messages containing
303 # the word "skip"
304 sub myfilter($$$$)
305 { my ($disp, $opts, $reason, $message) = @_;
306 return () if $message->untranslated =~ m/\bskip\b/;
307 ($reason, $message);
308 }
309
310 . Example: take all mistakes and warnings serious
311
312 dispatch filter => \&take_warns_seriously;
313 sub take_warns_seriously($$$$)
314 { my ($disp, $opts, $reason, $message) = @_;
315 $reason eq 'MISTAKE' ? (ERROR => $message)
316 : $reason eq 'WARNING' ? (FAULT => $message)
317 : ($reason => $message);
318 }
319
321 This module is part of Log-Report distribution version 1.34, built on
322 September 15, 2022. Website: http://perl.overmeer.net/CPAN/
323
325 Copyrights 2007-2022 by [Mark Overmeer <markov@cpan.org>]. For other
326 contributors see ChangeLog.
327
328 This program is free software; you can redistribute it and/or modify it
329 under the same terms as Perl itself. See http://dev.perl.org/licenses/
330
331
332
333perl v5.36.0 2022-09-15 Log::Report::Dispatcher(3)