1Log::Report::DispatcherU(s3e)r Contributed Perl DocumentaLtoigo:n:Report::Dispatcher(3)
2
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 # The following will be created for you automatically
23 dispatcher 'PERL', 'default', accept => 'NOTICE-';
24 dispatcher close => 'default'; # after deamonize
25 dispatcher 'FILE', 'log'
27 , mode => 'DEBUG', to => '/var/log/mydir/myfile';
28 # 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 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 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 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 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 -Option --Default
63 accept depend on mode
64 charset <undef>
65 format_reason 'LOWERCASE'
66 locale <system locale>
67 mode 'NORMAL'
68 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 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 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 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 locale => LOCALE
89 Overrules the global setting. Can be overruled by
90 Log::Report::report(locale).
91 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 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 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 $obj->name()
110 Returns the unique name of this dispatcher.
111 $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 [0.999] when only one $reason is specified, it is returned if in
118 the list.
119 $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 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 Warning: this logic is applied globally: on all dispatchers.
133 example:
135 By default, all lines in the Log::Report packages are skipped from
137 display, with a simple CODE as this:
138 sub in_lr { $_[0][0] =~ m/^Log\:\:Report(?:\:\:|$)/ }
140 Log::Report::Dispatcher->addSkipStack(\&in_lr);
141 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 $obj->collectLocation()
146 Log::Report::Dispatcher->collectLocation()
147 Collect the information to be displayed as line where the error
148 occurred.
149 $obj->collectStack( [$maxdepth] )
151 Log::Report::Dispatcher->collectStack( [$maxdepth] )
152 Returns an ARRAY of ARRAYs with text, filename, line-number.
153 $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 $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 $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 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 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 Log::Report::Dispatcher::Perl (abbreviation 'PERL')
202 Use Perl's own print(), warn() and die() to ventilate reports.
203 This is the default dispatcher.
204 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 Log::Report::Dispatcher::Syslog (abbreviation 'SYSLOG')
210 Send messages into the system's syslog infrastructure, using
211 Sys::Syslog.
212 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 "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 "Log::Log4perl"
223 Use the Log::Log4perl main object to write to dispatchers. This
224 infrastructure uses a configuration file.
225 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 Processing the message
231 Addition information
232 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 . 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 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 Exactly what will be added depends on the actual mode of the dispatcher
249 (change it with mode(), initiate it with new(mode)).
250 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 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 Filters
273 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 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 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 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 . Example: a filter on syslog
299 dispatcher filter => \&myfilter, 'syslog';
301 # 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 . Example: take all mistakes and warnings serious
311 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.36, built on
322 October 27, 2023. Website: http://perl.overmeer.net/CPAN/
323
325 Copyrights 2007-2023 by [Mark Overmeer <markov@cpan.org>]. For other
326 contributors see ChangeLog.
327 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/
330perl v5.36.1 2023-10-27 Log::Report::Dispatcher(3)