/ 
Log-Report-0.01
River stage two • 36 direct dependents • 86 total dependents
/ Log::Report::Dispatcher

NAME

Log::Report::Dispatcher - manage dispatching

SYNOPSIS

use Log::Report;
dispatcher 'FILE', 'log'
  , mode => 'DEBUG', to => '/var/log/mydir/myfile';

# The follow will be created for you always (when STDERR leads
# to a terminal)
dispatcher Log::Report::Dispatch::File => 'stderr'
   , to => \*STDERR, accept => 'NOTICE-';

DESCRIPTION

This base-class handles the creation of dispatchers, plus the common filtering rules.

When the program sees a terminal on STDERR (the usual case for any non-daemon), it will create a dispatcher for you to show all messages with minimal level NOTICE to it. That dispatcher is named 'stderr', and when you create one with the same name yourself, it will replace the default one.

See the "DETAILS" section, below.

METHODS

Constructors

$obj->close

    Terminate the dispatcher's 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
filter  undef
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.

    . filter => FILTER|ARRAY-of-FILTERs

    . locale => 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 adviced 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->addFilter(CODE|LIST-of-CODE|ARRAY-of-CODE)

    Add new filters to the dispatcher. Filters limit the amount of messages which are passed-through to the back-end logger. New filters are added to the end of the existing list.

    A LIST of defined filters (CODE references) is returned.

$obj->isDisabled

$obj->mode

$obj->name

    Returns the unique name of this dispatcher.

$obj->needs

    Returns the list with all REASONS which are needed to fulfil 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->collectStack(NESTING, [MAXDEPTH])

    Returns an ARRAY of ARRAYs with text, filename, line-number.

$obj->log(HASH-of-OPTIONS, REASON, MESSAGE)

$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 abbrevation of a class name. Implemented are:

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.

Processing the message

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 block
REASON   SOURCE   TE!  NORM -v   -vv  -vvv TRY
trace    program  ...                 S      
assert   program  ...            SL   SL     
info     program  T..       S    S    S 
notice   program  T..  S    S    S    S    D
mistake  user     T..  S    S    S    SL   D
warning  program  T.!  SL   SL   SL   SL   DL
error    user     TE.  S    S    SL   SC   B
fault    system   TE!  S    S    SL   SC   B
alert    system   T.!  S    S    SC   SC   S
failure  system   TE!  S    S    SC   SC   S
panic    program  .E.  SC   SC   SC   SC   SC

-v = verbose, -vv = debug, -vvv = trace
T - usually translated
E - exit
! - will include $! text
B - leave block with exception
D - delayed; only shown when block completes without error
L - include filename and linenumber
S - show/print when accepted
C - stack trace (like Carp::confess())

SEE ALSO

This module is part of Log-Report distribution version 0.01, built on May 25, 2007. Website: http://perl.overmeer.net/logreport/

LICENSE

Copyrights 2007 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