1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
=encoding utf8
=head1 NAME
Log::Report::Dispatcher::Log4perl - send messages to Log::Log4perl back-end
=head1 INHERITANCE
Log::Report::Dispatcher::Log4perl
is a Log::Report::Dispatcher
=head1 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;
=head1 DESCRIPTION
This dispatchers produces output tot syslog, based on the C<Sys::Log4perl>
module (which will not be automatically installed for you).
Extends L<"DESCRIPTION" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DESCRIPTION">.
=head2 Reasons <--> Levels
The REASONs for a message in L<Log::Report|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 L<new(to_level)|Log::Report::Dispatcher::Log4perl/"Constructors">.
TRACE => $DEBUG ERROR => $ERROR
ASSERT => $DEBUG FAULT => $ERROR
INFO => $INFO ALERT => $FATAL
NOTICE => $INFO FAILURE => $FATAL
WARNING => $WARN PANIC => $FATAL
MISTAKE => $WARN
=head2 Categories
C<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.
=head3 Limitiations
The global C<$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 C<%F>
and C<%L> are not useful in the generic case, maybe in your specific case.
=head1 METHODS
Extends L<"METHODS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"METHODS">.
=head2 Constructors
Extends L<"Constructors" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Constructors">.
=over 4
=item $obj-E<gt>B<close>()
Inherited, see L<Log::Report::Dispatcher/"Constructors">
=item Log::Report::Dispatcher::Log4perl-E<gt>B<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 []
=over 2
=item accept => REASONS
=item charset => CHARSET
=item 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.
=item format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
=item locale => LOCALE
=item mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
=item to_level => ARRAY-of-PAIRS
See L<reasonToLevel()|Log::Report::Dispatcher::Log4perl/"Logging">.
=back
=back
=head2 Accessors
Extends L<"Accessors" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Accessors">.
=over 4
=item $obj-E<gt>B<isDisabled>()
Inherited, see L<Log::Report::Dispatcher/"Accessors">
=item $obj-E<gt>B<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.
=item $obj-E<gt>B<mode>()
Inherited, see L<Log::Report::Dispatcher/"Accessors">
=item $obj-E<gt>B<name>()
Inherited, see L<Log::Report::Dispatcher/"Accessors">
=item $obj-E<gt>B<needs>( [$reason] )
Inherited, see L<Log::Report::Dispatcher/"Accessors">
=item $obj-E<gt>B<type>()
Inherited, see L<Log::Report::Dispatcher/"Accessors">
=back
=head2 Logging
Extends L<"Logging" in Log::Report::Dispatcher|Log::Report::Dispatcher/"Logging">.
=over 4
=item $obj-E<gt>B<addSkipStack>(@CODE)
=item Log::Report::Dispatcher::Log4perl-E<gt>B<addSkipStack>(@CODE)
Inherited, see L<Log::Report::Dispatcher/"Logging">
=item $obj-E<gt>B<collectLocation>()
=item Log::Report::Dispatcher::Log4perl-E<gt>B<collectLocation>()
Inherited, see L<Log::Report::Dispatcher/"Logging">
=item $obj-E<gt>B<collectStack>( [$maxdepth] )
=item Log::Report::Dispatcher::Log4perl-E<gt>B<collectStack>( [$maxdepth] )
Inherited, see L<Log::Report::Dispatcher/"Logging">
=item $obj-E<gt>B<log>(HASH-$of-%options, $reason, $message, $domain)
Inherited, see L<Log::Report::Dispatcher/"Logging">
=item $obj-E<gt>B<reasonToLevel>($reason)
Returns a level which is understood by Log::Dispatch, based on
a translation table. This can be changed with L<new(to_level)|Log::Report::Dispatcher::Log4perl/"Constructors">.
example:
use Log::Log4perl qw/:levels/;
# by default, ALERTs are output as $FATAL
dispatcher Log::Log4perl => 'logger'
, to_level => [ ALERT => $ERROR, ]
, ...;
=item $obj-E<gt>B<skipStack>()
Inherited, see L<Log::Report::Dispatcher/"Logging">
=item $obj-E<gt>B<stackTraceLine>(%options)
=item Log::Report::Dispatcher::Log4perl-E<gt>B<stackTraceLine>(%options)
Inherited, see L<Log::Report::Dispatcher/"Logging">
=item $obj-E<gt>B<translate>(HASH-$of-%options, $reason, $message)
Inherited, see L<Log::Report::Dispatcher/"Logging">
=back
=head1 DETAILS
Extends L<"DETAILS" in Log::Report::Dispatcher|Log::Report::Dispatcher/"DETAILS">.
=head1 SEE ALSO
This module is part of Log-Report distribution version 1.40,
built on April 18, 2025. Website: F<http://perl.overmeer.net/CPAN/>
=head1 LICENSE
Copyrights 2007-2025 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/>
|
