NAME¶
Log::Report::Dispatcher - manage dispatching
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
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-';
# Within a "try" block, there is only one dispatcher
dispatcher TRY => 'try';
DESCRIPTION¶
This base-class handles the creation of dispatchers, plus the common filtering
rules.
See the "DETAILS" section, below.
METHODS¶
Constructors¶
- $obj->close
- Terminate the dispatcher activities. The dispatcher gets
disabled, to avoid the case that it is accidentally used. Returns
"undef" (false) if the dispatcher was already closed.
- Log::Report::Dispatcher->new(TYPE, NAME,
OPTIONS)
- Create a dispatcher. The TYPE of back-end to start is
required, and listed in the "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 Log::Report::dispatcher()) 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'
- accept => REASONS
- See Log::Report::Util::expand_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
"accept"'s default is "NOTICE-". In case of
"VERBOSE" it will be "INFO-", "ASSERT"
results in "ASSERT-", and "DEBUG" in
"ALL".
- 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.
- 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.
- locale => LOCALE
- Overrules the global setting. Can be overruled by
Log::Report::report(locale).
- mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
- Possible values are "NORMAL" (or 0 or
"undef"), which will not show "INFO" or debug
messages, "VERBOSE" (1; shows "INFO" not debug),
"ASSERT" (2; only ignores "TRACE" messages), or
"DEBUG" (3) which shows everything. See section "Run
modes" in Log::Report.
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.
Accessors¶
- $obj->isDisabled
- $obj->mode
- Returns the mode in use for the dispatcher as number. See
new(mode) and "Run modes" in Log::Report.
- $obj->name
- Returns the unique name of this dispatcher.
- $obj->needs
- Returns the list with all REASONS which are needed to
fulfill this dispatcher's needs. When disabled, the list is empty, but not
forgotten.
- $obj->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.
Logging¶
- $obj->collectLocation
- Log::Report::Dispatcher->collectLocation
- Collect the information to be displayed as line where the
error occurred. Probably, this needs improvement, where carp and die show
different lines.
- $obj->collectStack([MAXDEPTH])
- Log::Report::Dispatcher->collectStack([MAXDEPTH])
- Returns an ARRAY of ARRAYs with text, filename,
line-number.
- $obj->log(HASH-of-OPTIONS, REASON, MESSAGE)
- This method is called by Log::Report::report() and
should not be called directly. Internally, it will call
translate(), which does most of the work.
- $obj->stackTraceLine(OPTIONS)
- Log::Report::Dispatcher->stackTraceLine(OPTIONS)
-
-Option --Default
abstract 1
call <required>
filename <required>
linenr <required>
max_line undef
max_params 8
package <required>
params <required>
- 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 "max_line"
margin.
- call => STRING
- filename => STRING
- linenr => INTEGER
- max_line => INTEGER
- max_params => INTEGER
- package => CLASS
- params => ARRAY
- $obj->translate(HASH-of-OPTIONS, REASON,
MESSAGE)
- See "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).
DETAILS¶
Available back-ends¶
When a dispatcher is created (via
new() or
Log::Report::dispatcher()), you must specify the TYPE of the
dispatcher. This can either be a class name, which extends a
Log::Report::Dispatcher, or a pre-defined abbreviation of a class name.
Implemented are:
- Log::Report::Dispatcher::Perl (abbreviation 'PERL')
- Use Perl's own "print()", "warn()" and
"die()" to ventilate reports. This is the default
dispatcher.
- 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.
- Log::Report::Dispatcher::Syslog (abbreviation
'SYSLOG')
- Send messages into the system's syslog infrastructure,
using Sys::Syslog.
- "Log::Dispatch::*"
- All of the Log::Dispatch::Output extensions can be used
directly. The Log::Report::Dispatcher::LogDispatch will wrap around that
back-end.
- "Log::Log4perl"
- Use the Log::Log4perl main object to write to dispatchers.
This infrastructure uses a configuration file.
- Log::Report::Dispatcher::Try (abbreviation 'TRY')
- Used by Log::Report::try(), it will translate
reports into exceptions.
Processing the message¶
Addition information
The modules which use "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:
- . the reason
- . the filename/line-number where the problem appeared
- . the filename/line-number where it problem was
reported
- . the error text in $!
- . a stack-trace
- . a trailing new-line
When the message is a translatable object (Log::Report::Message, for instance
created with Log::Report::__()), 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
mode(), initiate it with new(mode)).
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.! S S SC SC
failure system TE! S S SC SC
panic program .E. SC SC SC SC
T - usually translated
E - exception (execution interrupted)
! - will include $! text
L - include filename and linenumber
S - show/print when accepted
C - stack trace (like Carp::confess())
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
"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 Log::Report::Dispatcher), the HASH-of-OPTIONS passed as
optional first argument to
Log::Report::report(), the REASON, and the
MESSAGE. Returned is the new REASON and MESSAGE. When the returned REASON is
"undef", then the message will be ignored for that dispatcher.
Be warned about processing the MESSAGE: it is a Log::Report::Message object
which may have a "prepend" string and "append" string or
object. When the call to
Log::Report::report() contained multiple
comma-separated components, these will already have been joined together using
concatenation (see
Log::Report::Message::concat().
SEE ALSO¶
This module is part of Log-Report distribution version 0.94, built on August 23,
2011. Website:
http://perl.overmeer.net/log-report/
LICENSE¶
Copyrights 2007-2011 by Mark Overmeer. 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
http://www.perl.com/perl/misc/Artistic.html