409 lines
13 KiB
Plaintext
409 lines
13 KiB
Plaintext
=encoding utf8
|
|
|
|
=head1 NAME
|
|
|
|
Log::Report::Dispatcher - manage message dispatching, display or logging
|
|
|
|
=head1 INHERITANCE
|
|
|
|
Log::Report::Dispatcher is extended by
|
|
Log::Report::Dispatcher::Callback
|
|
Log::Report::Dispatcher::File
|
|
Log::Report::Dispatcher::Log4perl
|
|
Log::Report::Dispatcher::LogDispatch
|
|
Log::Report::Dispatcher::Perl
|
|
Log::Report::Dispatcher::Syslog
|
|
Log::Report::Dispatcher::Try
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
use Log::Report;
|
|
|
|
# The following will be created for you automatically
|
|
dispatcher 'PERL', 'default', accept => 'NOTICE-';
|
|
dispatcher close => 'default'; # after deamonize
|
|
|
|
dispatcher 'FILE', 'log'
|
|
, mode => 'DEBUG', to => '/var/log/mydir/myfile';
|
|
|
|
# Full package name is used, same as 'FILE'
|
|
dispatcher Log::Report::Dispatch::File => 'stderr'
|
|
, to => \*STDERR, accept => 'NOTICE-';
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
In L<Log::Report|Log::Report>, dispatchers are used to handle (exception) messages
|
|
which are created somewhere else. Those message were produced (thrown)
|
|
by L<Log::Report::error()|Log::Report/"Abbreviations for report()"> and friends.
|
|
|
|
This base-class handles the creation of dispatchers, plus the common
|
|
filtering rules. See the L</DETAILS> section, below.
|
|
|
|
=head1 METHODS
|
|
|
|
=head2 Constructors
|
|
|
|
=over 4
|
|
|
|
=item $obj-E<gt>B<close>()
|
|
|
|
Terminate the dispatcher activities. The dispatcher gets disabled,
|
|
to avoid the case that it is accidentally used. Returns C<undef> (false)
|
|
if the dispatcher was already closed.
|
|
|
|
=item Log::Report::Dispatcher-E<gt>B<new>($type, $name, %options)
|
|
|
|
Create a dispatcher. The $type of back-end to start is required, and listed
|
|
in the L</DESCRIPTION> part of this manual-page. For various external
|
|
back-ends, special wrappers are created.
|
|
|
|
The $name must be uniquely identifying this dispatcher. When a second
|
|
dispatcher is created (via L<Log::Report::dispatcher()|Log::Report/"Report Production and Configuration">) with the name
|
|
of an existing dispatcher, the existing one will get replaced.
|
|
|
|
All %options which are not consumed by this base constructor are passed
|
|
to the wrapped back-end. Some of them will check whether all %options
|
|
are understood, other ignore unknown %options.
|
|
|
|
-Option --Default
|
|
accept depend on mode
|
|
charset <undef>
|
|
format_reason 'LOWERCASE'
|
|
locale <system locale>
|
|
mode 'NORMAL'
|
|
|
|
=over 2
|
|
|
|
=item accept => REASONS
|
|
|
|
See L<Log::Report::Util::expand_reasons()|Log::Report::Util/"Reasons"> for possible values. If
|
|
the initial mode for this dispatcher does not need verbose or debug
|
|
information, then those levels will not be accepted.
|
|
|
|
When the mode equals "NORMAL" (the default) then C<accept>'s default
|
|
is C<NOTICE->. In case of "VERBOSE" it will be C<INFO->, C<ASSERT>
|
|
results in C<ASSERT->, and "DEBUG" in C<ALL>.
|
|
|
|
=item charset => CHARSET
|
|
|
|
Convert the messages in the specified character-set (codeset). By
|
|
default, no conversion will take place, because the right choice cannot
|
|
be determined automatically.
|
|
|
|
=item format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
|
|
|
|
How to show the reason text which is printed before the message. When
|
|
a CODE is specified, it will be called with a translated text and the
|
|
returned text is used.
|
|
|
|
=item locale => LOCALE
|
|
|
|
Overrules the global setting. Can be overruled by
|
|
L<Log::Report::report(locale)|Log::Report/"Report Production and Configuration">.
|
|
|
|
=item mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
|
|
|
|
Possible values are C<NORMAL> (or C<0> or C<undef>), which will not show
|
|
C<INFO> or debug messages, C<VERBOSE> (C<1>; shows C<INFO> not debug),
|
|
C<ASSERT> (C<2>; only ignores C<TRACE> messages), or C<DEBUG> (C<3>)
|
|
which shows everything. See section L<Log::Report/Run modes>.
|
|
|
|
You are advised to use the symbolic mode names when the mode is
|
|
changed within your program: the numerical values are available
|
|
for smooth Getopt::Long integration.
|
|
|
|
=back
|
|
|
|
=back
|
|
|
|
=head2 Accessors
|
|
|
|
=over 4
|
|
|
|
=item $obj-E<gt>B<isDisabled>()
|
|
|
|
=item $obj-E<gt>B<mode>()
|
|
|
|
Returns the mode in use for the dispatcher as number. See L<new(mode)|Log::Report::Dispatcher/"Constructors">
|
|
and L<Log::Report/Run modes>.
|
|
|
|
=item $obj-E<gt>B<name>()
|
|
|
|
Returns the unique name of this dispatcher.
|
|
|
|
=item $obj-E<gt>B<needs>( [$reason] )
|
|
|
|
Returns the list with all REASONS which are needed to fulfill this
|
|
dispatcher's needs. When disabled, the list is empty, but not forgotten.
|
|
|
|
[0.999] when only one $reason is specified, it is returned if in the
|
|
list.
|
|
|
|
=item $obj-E<gt>B<type>()
|
|
|
|
The dispatcher $type, which is usually the same as the class of this
|
|
object, but not in case of wrappers like for Log::Dispatch.
|
|
|
|
=back
|
|
|
|
=head2 Logging
|
|
|
|
=over 4
|
|
|
|
=item $obj-E<gt>B<addSkipStack>(@CODE)
|
|
|
|
=item Log::Report::Dispatcher-E<gt>B<addSkipStack>(@CODE)
|
|
|
|
[1.13] Add one or more CODE blocks of caller lines which should not be
|
|
collected for stack-traces or location display. A CODE gets
|
|
called with an ARRAY of caller information, and returns true
|
|
when that line should get skipped.
|
|
|
|
B<Warning:> this logic is applied globally: on all dispatchers.
|
|
|
|
example:
|
|
|
|
By default, all lines in the Log::Report packages are skipped from
|
|
display, with a simple CODE as this:
|
|
|
|
sub in_lr { $_[0][0] =~ m/^Log\:\:Report(?:\:\:|$)/ }
|
|
Log::Report::Dispatcher->addSkipStack(\&in_lr);
|
|
|
|
The only parameter to in_lr is the return of caller(). The first
|
|
element of that ARRAY is the package name of a stack line.
|
|
|
|
=item $obj-E<gt>B<collectLocation>()
|
|
|
|
=item Log::Report::Dispatcher-E<gt>B<collectLocation>()
|
|
|
|
Collect the information to be displayed as line where the error occurred.
|
|
|
|
=item $obj-E<gt>B<collectStack>( [$maxdepth] )
|
|
|
|
=item Log::Report::Dispatcher-E<gt>B<collectStack>( [$maxdepth] )
|
|
|
|
Returns an ARRAY of ARRAYs with text, filename, line-number.
|
|
|
|
=item $obj-E<gt>B<log>(HASH-$of-%options, $reason, $message, $domain)
|
|
|
|
This method is called by L<Log::Report::report()|Log::Report/"Report Production and Configuration"> and should not be called
|
|
directly. Internally, it will call L<translate()|Log::Report::Dispatcher/"Logging">, which does most $of
|
|
the work.
|
|
|
|
=item $obj-E<gt>B<skipStack>()
|
|
|
|
[1.13] Returns the number of nestings in the stack which should be skipped
|
|
to get outside the Log::Report (and related) modules. The end-user
|
|
does not want to see those internals in stack-traces.
|
|
|
|
=item $obj-E<gt>B<stackTraceLine>(%options)
|
|
|
|
=item Log::Report::Dispatcher-E<gt>B<stackTraceLine>(%options)
|
|
|
|
-Option --Default
|
|
abstract 1
|
|
call <required>
|
|
filename <required>
|
|
linenr <required>
|
|
max_line undef
|
|
max_params 8
|
|
package <required>
|
|
params <required>
|
|
|
|
=over 2
|
|
|
|
=item abstract => INTEGER
|
|
|
|
The higher the abstraction value, the less details are given
|
|
about the caller. The minimum abstraction is specified, and
|
|
then increased internally to make the line fit within the C<max_line>
|
|
margin.
|
|
|
|
=item call => STRING
|
|
|
|
=item filename => STRING
|
|
|
|
=item linenr => INTEGER
|
|
|
|
=item max_line => INTEGER
|
|
|
|
=item max_params => INTEGER
|
|
|
|
=item package => CLASS
|
|
|
|
=item params => ARRAY
|
|
|
|
=back
|
|
|
|
=item $obj-E<gt>B<translate>(HASH-$of-%options, $reason, $message)
|
|
|
|
See L</Processing the message>, which describes the actions taken by
|
|
this method. A string is returned, which ends on a new-line, and
|
|
may be multi-line (in case a stack trace is produced).
|
|
|
|
=back
|
|
|
|
=head1 DETAILS
|
|
|
|
=head2 Available back-ends
|
|
|
|
When a dispatcher is created (via L<new()|Log::Report::Dispatcher/"Constructors"> or L<Log::Report::dispatcher()|Log::Report/"Report Production and Configuration">),
|
|
you must specify the TYPE of the dispatcher. This can either be a class
|
|
name, which extends a L<Log::Report::Dispatcher|Log::Report::Dispatcher>, or a pre-defined
|
|
abbreviation of a class name. Implemented are:
|
|
|
|
=over 4
|
|
|
|
=item L<Log::Report::Dispatcher::Perl|Log::Report::Dispatcher::Perl> (abbreviation 'PERL')
|
|
|
|
Use Perl's own C<print()>, C<warn()> and C<die()> to ventilate
|
|
reports. This is the default dispatcher.
|
|
|
|
=item L<Log::Report::Dispatcher::File|Log::Report::Dispatcher::File> (abbreviation 'FILE')
|
|
|
|
Logs the message into a file, which can either be opened by the
|
|
class or be opened before the dispatcher is created.
|
|
|
|
=item L<Log::Report::Dispatcher::Syslog|Log::Report::Dispatcher::Syslog> (abbreviation 'SYSLOG')
|
|
|
|
Send messages into the system's syslog infrastructure, using
|
|
Sys::Syslog.
|
|
|
|
=item L<Log::Report::Dispatcher::Callback|Log::Report::Dispatcher::Callback> (abbreviation 'CALLBACK')
|
|
|
|
Calls any CODE reference on receipt of each selected message, for
|
|
instance to send important message as email or SMS.
|
|
|
|
=item C<Log::Dispatch::*>
|
|
|
|
All of the Log::Dispatch::Output extensions can be used directly.
|
|
The L<Log::Report::Dispatcher::LogDispatch|Log::Report::Dispatcher::LogDispatch> will wrap around that
|
|
back-end.
|
|
|
|
=item C<Log::Log4perl>
|
|
|
|
Use the Log::Log4perl main object to write to dispatchers. This
|
|
infrastructure uses a configuration file.
|
|
|
|
=item L<Log::Report::Dispatcher::Try|Log::Report::Dispatcher::Try> (abbreviation 'TRY')
|
|
|
|
Used by function L<Log::Report::try()|Log::Report/"Report Production and Configuration">. It collects the exceptions
|
|
and can produce them on request.
|
|
|
|
=back
|
|
|
|
=head2 Processing the message
|
|
|
|
=head3 Addition information
|
|
|
|
The modules which use C<Log::Report> will only specify the base of
|
|
the message string. The base dispatcher and the back-ends will extend
|
|
this message with additional information:
|
|
|
|
=over 4
|
|
|
|
=item . the reason
|
|
|
|
=item . the filename/line-number where the problem appeared
|
|
|
|
=item . the filename/line-number where it problem was reported
|
|
|
|
=item . the error text in C<$!>
|
|
|
|
=item . a stack-trace
|
|
|
|
=item . a trailing new-line
|
|
|
|
=back
|
|
|
|
When the message is a translatable object (L<Log::Report::Message|Log::Report::Message>, for
|
|
instance created with L<Log::Report::__()|Log::Report/"Messages (optionally translatable)">), then the added components
|
|
will get translated as well. Otherwise, all will be in English.
|
|
|
|
Exactly what will be added depends on the actual mode of the dispatcher
|
|
(change it with L<mode()|Log::Report::Dispatcher/"Accessors">, initiate it with L<new(mode)|Log::Report::Dispatcher/"Constructors">).
|
|
|
|
mode mode mode mode
|
|
REASON SOURCE TE! NORM VERB ASSE DEBUG
|
|
trace program ... S
|
|
assert program ... SL SL
|
|
info program T.. S S S
|
|
notice program T.. S S S S
|
|
mistake user T.. S S S SL
|
|
warning program T.. S S SL SL
|
|
error user TE. S S SL SC
|
|
fault system TE! S S SL SC
|
|
alert system T.! SL SL SC SC
|
|
failure system TE! SL SL SC SC
|
|
panic program .E. SC SC SC SC
|
|
|
|
T - usually translated
|
|
E - exception (execution interrupted)
|
|
! - will include $! text at display
|
|
L - include filename and linenumber
|
|
S - show/print when accepted
|
|
C - stack trace (like Carp::confess())
|
|
|
|
=head3 Filters
|
|
|
|
With a filter, you can block or modify specific messages before
|
|
translation. There may be a wish to change the REASON of a report
|
|
or its content. It is not possible to avoid the exit which is
|
|
related to the original message, because a module's flow depends
|
|
on it to happen.
|
|
|
|
When there are filters defined, they will be called in order of
|
|
definition. For each of the dispatchers which are called for a
|
|
certain REASON (which C<accept> that REASON), it is checked whether
|
|
its name is listed for the filter (when no names where specified,
|
|
then the filter is applied to all dispatchers).
|
|
|
|
When selected, the filter's CODE reference is called with four arguments:
|
|
the dispatcher object (a L<Log::Report::Dispatcher|Log::Report::Dispatcher>), the HASH-of-OPTIONS
|
|
passed as optional first argument to L<Log::Report::report()|Log::Report/"Report Production and Configuration">, the
|
|
REASON, and the MESSAGE. Returned is the new REASON and MESSAGE.
|
|
When the returned REASON is C<undef>, then the message will be ignored
|
|
for that dispatcher.
|
|
|
|
Be warned about processing the MESSAGE: it is a L<Log::Report::Message|Log::Report::Message>
|
|
object which may have a C<prepend> string and C<append> string or
|
|
object. When the call to L<Log::Report::report()|Log::Report/"Report Production and Configuration"> contained multiple
|
|
comma-separated components, these will already have been joined together
|
|
using concatenation (see L<Log::Report::Message::concat()|Log::Report::Message/"Processing">.
|
|
|
|
B<. Example: a filter on syslog>
|
|
|
|
dispatcher filter => \&myfilter, 'syslog';
|
|
|
|
# ignore all translatable and non-translatable messages containing
|
|
# the word "skip"
|
|
sub myfilter($$$$)
|
|
{ my ($disp, $opts, $reason, $message) = @_;
|
|
return () if $message->untranslated =~ m/\bskip\b/;
|
|
($reason, $message);
|
|
}
|
|
|
|
B<. Example: take all mistakes and warnings serious>
|
|
|
|
dispatch filter => \&take_warns_seriously;
|
|
sub take_warns_seriously($$$$)
|
|
{ my ($disp, $opts, $reason, $message) = @_;
|
|
$reason eq 'MISTAKE' ? (ERROR => $message)
|
|
: $reason eq 'WARNING' ? (FAULT => $message)
|
|
: ($reason => $message);
|
|
}
|
|
|
|
=head1 SEE ALSO
|
|
|
|
This module is part of Log-Report distribution version 1.31,
|
|
built on January 15, 2021. Website: F<http://perl.overmeer.net/CPAN/>
|
|
|
|
=head1 LICENSE
|
|
|
|
Copyrights 2007-2021 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
|
|
|
|
This program is free software; you can redistribute it and/or modify it
|
|
under the same terms as Perl itself.
|
|
See F<http://dev.perl.org/licenses/>
|
|
|