Log::Report::Dispatcher::Log4perl(3pm)

1Log::Report::DispatcherU:s:eLrogC4opnetrrli(b3u)ted PerlLoDgo:c:uRmeepnotratt:i:oDnispatcher::Log4perl(3)
2
3
4

NAME

6       Log::Report::Dispatcher::Log4perl - send messages to Log::Log4perl
7       back-end
8

INHERITANCE

10        Log::Report::Dispatcher::Log4perl
11          is a Log::Report::Dispatcher
12

SYNOPSIS

14        # start using log4perl via a config file
15        # The name of the dispatcher is the name of the default category.
16        dispatcher LOG4PERL => 'logger'
17          , accept => 'NOTICE-'
18          , config => "$ENV{HOME}/.log.conf";
19
20        # disable default dispatcher
21        dispatcher close => 'logger';
22
23        # configuration inline, not in file: adapted from the Log4perl manpage
24        my $name    = 'logger';
25        my $outfile = '/tmp/a.log';
26        my $config  = <<__CONFIG;
27        log4perl.category.$name            = INFO, Logfile
28        log4perl.logger.Logfile          = Log::Log4perl::Appender::File
29        log4perl.logger.Logfile.filename = $outfn
30        log4perl.logger.Logfile.layout   = Log::Log4perl::Layout::PatternLayout
31        log4perl.logger.Logfile.layout.ConversionPattern = %d %F{1} %L> %m
32        __CONFIG
33
34        dispatcher LOG4PERL => $name, config => \$config;
35

DESCRIPTION

37       This dispatchers produces output tot syslog, based on the
38       "Sys::Log4perl" module (which will not be automatically installed for
39       you).
40
41       Extends "DESCRIPTION" in Log::Report::Dispatcher.
42
43   Reasons <--> Levels
44       The REASONs for a message in Log::Report are names quite similar to the
45       log levels used by Log::Log4perl.  The default mapping is list below.
46       You can change the mapping using new(to_level).
47
48         TRACE   => $DEBUG    ERROR   => $ERROR
49         ASSERT  => $DEBUG    FAULT   => $ERROR
50         INFO    => $INFO     ALERT   => $FATAL
51         NOTICE  => $INFO     FAILURE => $FATAL
52         WARNING => $WARN     PANIC   => $FATAL
53         MISTAKE => $WARN
54
55   Categories
56       "Log::Report" uses text-domains for translation tables.  These are also
57       used as categories for the Log4perl infrastructure.  So, typically
58       every module start with:
59
60          use Log::Report 'my-text-domain', %more_options;
61
62       Now, if there is a logger inside the log4perl configuration which is
63       named 'my-text-domain', that will be used.  Otherwise, the name of the
64       dispatcher is used to select the logger.
65
66       Limitiations
67
68       The global $caller_depth concept of Log::Log4perl is broken.  That
69       variable is used to find the filename and line number of the logged
70       messages.  But these messages may have been caught, rerouted, eval'ed,
71       and otherwise followed a unpredictable multi-leveled path before it
72       reached the Log::Log4perl dispatcher.  This means that layout patterns
73       %F and %L are not useful in the generic case, maybe in your specific
74       case.
75

METHODS

77       Extends "METHODS" in Log::Report::Dispatcher.
78
79   Constructors
80       Extends "Constructors" in Log::Report::Dispatcher.
81
82       $obj->close()
83           Inherited, see "Constructors" in Log::Report::Dispatcher
84
85       Log::Report::Dispatcher::Log4perl->new($type, $name, %options)
86           The Log::Log4perl infrastructure has all settings in a
87           configuration file.  In that file, you should find a category with
88           the $name.
89
90            -Option       --Defined in             --Default
91             accept         Log::Report::Dispatcher  'ALL'
92             charset        Log::Report::Dispatcher  <undef>
93             config                                  <undef>
94             format_reason  Log::Report::Dispatcher  'LOWERCASE'
95             locale         Log::Report::Dispatcher  <system locale>
96             mode           Log::Report::Dispatcher  'NORMAL'
97             to_level                                []
98
99           accept => REASONS
100           charset => CHARSET
101           config => FILENAME|SCALAR
102             When a SCALAR reference is passed in, that must refer to a string
103             which contains the configuration text.  Otherwise, specify an
104             existing FILENAME.
105
106             By default, it is expected that Log::Log4perl has been
107             initialized externally.  That module uses global variables to
108             communicate, which should be present before any logging is
109             attempted.
110
111           format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
112           locale => LOCALE
113           mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
114           to_level => ARRAY-of-PAIRS
115             See reasonToLevel().
116
117   Accessors
118       Extends "Accessors" in Log::Report::Dispatcher.
119
120       $obj->isDisabled()
121           Inherited, see "Accessors" in Log::Report::Dispatcher
122
123       $obj->logger( [$domain] )
124           Returns the Log::Log4perl::Logger object which is used for logging.
125           When there is no specific logger for this $domain (logger with the
126           exact name of the $domain) the default logger is being used, with
127           the name of this dispatcher.
128
129       $obj->mode()
130           Inherited, see "Accessors" in Log::Report::Dispatcher
131
132       $obj->name()
133           Inherited, see "Accessors" in Log::Report::Dispatcher
134
135       $obj->needs( [$reason] )
136           Inherited, see "Accessors" in Log::Report::Dispatcher
137
138       $obj->type()
139           Inherited, see "Accessors" in Log::Report::Dispatcher
140
141   Logging
142       Extends "Logging" in Log::Report::Dispatcher.
143
144       $obj->addSkipStack(@CODE)
145       Log::Report::Dispatcher::Log4perl->addSkipStack(@CODE)
146           Inherited, see "Logging" in Log::Report::Dispatcher
147
148       $obj->collectLocation()
149       Log::Report::Dispatcher::Log4perl->collectLocation()
150           Inherited, see "Logging" in Log::Report::Dispatcher
151
152       $obj->collectStack( [$maxdepth] )
153       Log::Report::Dispatcher::Log4perl->collectStack( [$maxdepth] )
154           Inherited, see "Logging" in Log::Report::Dispatcher
155
156       $obj->log(HASH-$of-%options, $reason, $message, $domain)
157           Inherited, see "Logging" in Log::Report::Dispatcher
158
159       $obj->reasonToLevel($reason)
160           Returns a level which is understood by Log::Dispatch, based on a
161           translation table.  This can be changed with new(to_level).
162
163           example:
164
165            use Log::Log4perl     qw/:levels/;
166
167            # by default, ALERTs are output as $FATAL
168            dispatcher Log::Log4perl => 'logger'
169              , to_level => [ ALERT => $ERROR, ]
170              , ...;
171
172       $obj->skipStack()
173           Inherited, see "Logging" in Log::Report::Dispatcher
174
175       $obj->stackTraceLine(%options)
176       Log::Report::Dispatcher::Log4perl->stackTraceLine(%options)
177           Inherited, see "Logging" in Log::Report::Dispatcher
178
179       $obj->translate(HASH-$of-%options, $reason, $message)
180           Inherited, see "Logging" in Log::Report::Dispatcher
181

DETAILS

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

LICENSE

190       Copyrights 2007-2022 by [Mark Overmeer <markov@cpan.org>]. For other
191       contributors see ChangeLog.
192
193       This program is free software; you can redistribute it and/or modify it
194       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
195
196
197
198perl v5.36.0                      2022-09-1L5og::Report::Dispatcher::Log4perl(3)