Provided by: liblog-report-perl_1.34-1_all bug

NAME

       Log::Report::Dispatcher::Log4perl - send messages to Log::Log4perl back-end

INHERITANCE

        Log::Report::Dispatcher::Log4perl
          is a Log::Report::Dispatcher

SYNOPSIS

        # start using log4perl via a config file
        # The name of the dispatcher is the name of the default category.
        dispatcher LOG4PERL => 'logger'
          , accept => 'NOTICE-'
          , config => "$ENV{HOME}/.log.conf";

        # disable default dispatcher
        dispatcher close => 'logger';

        # configuration inline, not in file: adapted from the Log4perl manpage
        my $name    = 'logger';
        my $outfile = '/tmp/a.log';
        my $config  = <<__CONFIG;
        log4perl.category.$name            = INFO, Logfile
        log4perl.logger.Logfile          = Log::Log4perl::Appender::File
        log4perl.logger.Logfile.filename = $outfn
        log4perl.logger.Logfile.layout   = Log::Log4perl::Layout::PatternLayout
        log4perl.logger.Logfile.layout.ConversionPattern = %d %F{1} %L> %m
        __CONFIG

        dispatcher LOG4PERL => $name, config => \$config;

DESCRIPTION

       This dispatchers produces output tot syslog, based on the "Sys::Log4perl" module (which
       will not be automatically installed for you).

       Extends "DESCRIPTION" in Log::Report::Dispatcher.

   Reasons <--> Levels
       The REASONs for a message in Log::Report are names quite similar to the log levels used by
       Log::Log4perl.  The default mapping is list below.  You can change the mapping using
       new(to_level).

         TRACE   => $DEBUG    ERROR   => $ERROR
         ASSERT  => $DEBUG    FAULT   => $ERROR
         INFO    => $INFO     ALERT   => $FATAL
         NOTICE  => $INFO     FAILURE => $FATAL
         WARNING => $WARN     PANIC   => $FATAL
         MISTAKE => $WARN

   Categories
       "Log::Report" uses text-domains for translation tables.  These are also used as categories
       for the Log4perl infrastructure.  So, typically every module start with:

          use Log::Report 'my-text-domain', %more_options;

       Now, if there is a logger inside the log4perl configuration which is named
       'my-text-domain', that will be used.  Otherwise, the name of the dispatcher is used to
       select the logger.

       Limitiations

       The global $caller_depth concept of Log::Log4perl is broken.  That variable is used to
       find the filename and line number of the logged messages.  But these messages may have
       been caught, rerouted, eval'ed, and otherwise followed a unpredictable multi-leveled path
       before it reached the Log::Log4perl dispatcher.  This means that layout patterns %F and %L
       are not useful in the generic case, maybe in your specific case.

METHODS

       Extends "METHODS" in Log::Report::Dispatcher.

   Constructors
       Extends "Constructors" in Log::Report::Dispatcher.

       $obj->close()
           Inherited, see "Constructors" in Log::Report::Dispatcher

       Log::Report::Dispatcher::Log4perl->new($type, $name, %options)
           The Log::Log4perl infrastructure has all settings in a configuration file.  In that
           file, you should find a category with the $name.

            -Option       --Defined in             --Default
             accept         Log::Report::Dispatcher  'ALL'
             charset        Log::Report::Dispatcher  <undef>
             config                                  <undef>
             format_reason  Log::Report::Dispatcher  'LOWERCASE'
             locale         Log::Report::Dispatcher  <system locale>
             mode           Log::Report::Dispatcher  'NORMAL'
             to_level                                []

           accept => REASONS
           charset => CHARSET
           config => FILENAME|SCALAR
             When a SCALAR reference is passed in, that must refer to a string which contains the
             configuration text.  Otherwise, specify an existing FILENAME.

             By default, it is expected that Log::Log4perl has been initialized externally.  That
             module uses global variables to communicate, which should be present before any
             logging is attempted.

           format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
           locale => LOCALE
           mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
           to_level => ARRAY-of-PAIRS
             See reasonToLevel().

   Accessors
       Extends "Accessors" in Log::Report::Dispatcher.

       $obj->isDisabled()
           Inherited, see "Accessors" in Log::Report::Dispatcher

       $obj->logger( [$domain] )
           Returns the Log::Log4perl::Logger object which is used for logging.  When there is no
           specific logger for this $domain (logger with the exact name of the $domain) the
           default logger is being used, with the name of this dispatcher.

       $obj->mode()
           Inherited, see "Accessors" in Log::Report::Dispatcher

       $obj->name()
           Inherited, see "Accessors" in Log::Report::Dispatcher

       $obj->needs( [$reason] )
           Inherited, see "Accessors" in Log::Report::Dispatcher

       $obj->type()
           Inherited, see "Accessors" in Log::Report::Dispatcher

   Logging
       Extends "Logging" in Log::Report::Dispatcher.

       $obj->addSkipStack(@CODE)
       Log::Report::Dispatcher::Log4perl->addSkipStack(@CODE)
           Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->collectLocation()
       Log::Report::Dispatcher::Log4perl->collectLocation()
           Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->collectStack( [$maxdepth] )
       Log::Report::Dispatcher::Log4perl->collectStack( [$maxdepth] )
           Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->log(HASH-$of-%options, $reason, $message, $domain)
           Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->reasonToLevel($reason)
           Returns a level which is understood by Log::Dispatch, based on a translation table.
           This can be changed with new(to_level).

           example:

            use Log::Log4perl     qw/:levels/;

            # by default, ALERTs are output as $FATAL
            dispatcher Log::Log4perl => 'logger'
              , to_level => [ ALERT => $ERROR, ]
              , ...;

       $obj->skipStack()
           Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->stackTraceLine(%options)
       Log::Report::Dispatcher::Log4perl->stackTraceLine(%options)
           Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->translate(HASH-$of-%options, $reason, $message)
           Inherited, see "Logging" in Log::Report::Dispatcher

DETAILS

       Extends "DETAILS" in Log::Report::Dispatcher.

SEE ALSO

       This module is part of Log-Report distribution version 1.34, built on September 15, 2022.
       Website: http://perl.overmeer.net/CPAN/

LICENSE

       Copyrights 2007-2022 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 http://dev.perl.org/licenses/