1Log::Report::DispatcherU(s3e)r Contributed Perl DocumentaLtoigo:n:Report::Dispatcher(3)
2
3
4

NAME

6       Log::Report::Dispatcher - manage message dispatching, display or
7       logging
8

INHERITANCE

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

SYNOPSIS

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

DESCRIPTION

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

METHODS

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

DETAILS

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

SEE ALSO

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

LICENSE

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)
Impressum