Log::R...og4perl(3pm)

💖 Log::Report::Dispatcher::Log4perl 💖

hiii bestie, welcome to the Log::Report::Dispatcher::Log4perl(3pm) page, straight outta the User Contributed Perl Documentation 📚✨ this is literally the plug that ships your Log::Report messages over to a Log::Log4perl back-end. no cap. let's get into it 🫶

---

🌸 NAME 🌸

Log::Report::Dispatcher::Log4perl — send messages to Log::Log4perl back-end. that's the whole job description, iconic behavior 👑

---

🧬 INHERITANCE 🧬

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

so it's a Log::Report::Dispatcher, it just showed up with an extra accessory ✨

---

🎀 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 📖

okay so real talk: this dispatcher produces output tot syslog, based on the Sys::Log4perl module 💀 and heads up bestie — that module will not be automatically installed for you. you gotta go get it yourself. girl math can't save you here.

it extends DESCRIPTION in Log::Report::Dispatcher, so that's your required reading 🫶

🔥 Reasons <--> Levels 🔥

the REASONs for a message in Log::Report are names quite similar to the log levels used by Log::Log4perl, so they lowkey vibe together. the default mapping is listed below 👇 and yes you can 100% 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, and plot twist — those same text-domains get used as categories for the Log4perl infrastructure. the way that works is, typically every module starts with:

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

so now, if there's a logger inside the log4perl configuration named 'my-text-domain', that one gets chosen 🎯 otherwise? the name of the dispatcher is used to select the logger. either way you're getting a logger bestie.

⚠️ Limitiations ⚠️

bestie this is the messy part. 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 those messages may have been caught, rerouted, eval'ed, and otherwise followed a unpredictable multi-leveled path before it reached the Log::Log4perl dispatcher. which means layout patterns %F and %L are not useful in the generic case — maybe in your specific case, but don't count on it 🙈

---

🛠️ METHODS 🛠️

extends METHODS in Log::Report::Dispatcher 🫶

🧸 Constructors 🧸

extends Constructors in Log::Report::Dispatcher.

$class->new($type, $name, %options)

the Log::Log4perl infrastructure keeps all its settings in a configuration file, so in that file you should find a category with the $name 👑 improves base, see Constructors in Log::Report::Dispatcher.

the option table has these columns — -Option, --Defined in, --Default — and here's every single row, no skips, periodt:

• accept — defined in Log::Report::Dispatcher, default 'ALL'
• charset — defined in Log::Report::Dispatcher, default undef
• config — default <C<undef>>
• format_reason — defined in Log::Report::Dispatcher, default 'LOWERCASE'
• locale — defined in Log::Report::Dispatcher, default <system locale>
• mode — defined in Log::Report::Dispatcher, default 'NORMAL'
• to_level — default []

and now the full tea on each one 🍵

• 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. and by default? it's expected that Log::Log4perl has been initialized externally, because that module uses global variables to communicate, and those 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 (like, a logger with the exact name of the $domain), the default logger gets 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 📊 and you can change it 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 🌈

---

and that's the whole page bestie, you ate that 💅✨ this was perl v5.40.1, dated 2026-07-05, and the page was literally Log::R...og4perl(3pm) — go forth and dispatch your logs, main character 👑🦋