--- name: "Log::Report::Dispatcher::Log4perl" section: "3pm" platform: "linux" package: "perl-log-report" version: "1.46-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Log::Report::Dispatcher::Log4perl" --- # Log::Report::Dispatcher::Log4perl(3pm) send messages to Log::Log4perl back-end ## 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. - $class-\>**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`. Improves base, see "Constructors" in Log::Report::Dispatcher ``` -Option --Defined in --Default accept Log::Report::Dispatcher 'ALL' charset Log::Report::Dispatcher undef config > format_reason Log::Report::Dispatcher 'LOWERCASE' locale Log::Report::Dispatcher mode Log::Report::Dispatcher 'NORMAL' to_level [] ``` - accept =\> $reasons\|\\@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()**. ### Attributes Extends "Attributes" in Log::Report::Dispatcher. - $obj-\>**isDisabled**() Inherited, see "Attributes" 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 "Attributes" in Log::Report::Dispatcher - $obj-\>**name**() Inherited, see "Attributes" in Log::Report::Dispatcher - $obj-\>**needs**( \[$reason\] ) Inherited, see "Attributes" in Log::Report::Dispatcher - $obj-\>**type**() Inherited, see "Attributes" in Log::Report::Dispatcher ### Logging Extends "Logging" in Log::Report::Dispatcher. - $any-\>**addSkipStack**(@CODE) Inherited, see "Logging" in Log::Report::Dispatcher - $obj-\>**close**() Inherited, see "Logging" in Log::Report::Dispatcher - $any-\>**collectLocation**() Inherited, see "Logging" in Log::Report::Dispatcher - $any-\>**collectStack**( \[$maxdepth\] ) Inherited, see "Logging" in Log::Report::Dispatcher - $obj-\>**log**(\\%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 - $any-\>**stackTraceLine**(%options) Inherited, see "Logging" in Log::Report::Dispatcher - $obj-\>**translate**(\\%options, $reason, $message) Inherited, see "Logging" in Log::Report::Dispatcher ## DETAILS Extends "DETAILS" in Log::Report::Dispatcher. ## DIAGNOSTICS - Error: Log4perl level '$level' must be in 0-5 Cast by `new()` ## SEE ALSO This module is part of Log-Report version 1.46, built on June 16, 2026. Website: *http://perl.overmeer.net/CPAN/* ## LICENSE For contributors see file ChangeLog. This software is copyright (c) 2007-2026 by Mark Overmeer. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.