warning This is an experimental version of LogDispatchContrib.

support To configure your Foswiki to install from this repository, modify the {ExtensionsRepositories} setting in your lib/LocalSite.cfg like this:
$Foswiki::cfg{ExtensionsRepositories} = 'Foswiki.org=(http://foswiki.org/Extensions/,http://foswiki.org/pub/Extensions/);Local=(http://foswiki.org/Extensions/Testing/,http://foswiki.org/pub/Extensions/Testing/)';

Read more about configuring Extension repositories


Advanced logging using Log::Dispatch


LogDispatchContrib is a pluggable logger implementation that can replace the default loggers shipped with Foswiki. It provides logging methods similar to the Compatibility logger shipped with Foswiki, and adds several alternative methods to support alternate destinations.

The following log methods are shipped by default:

$ LogDispatch::File: A simple file based logger. It does not do any file rotation or date stamping of the files. $ LogDispatch::FileRolling: A file based logger similar to the "Compatibility" logger used by default on Foswiki 1.0. It logs to files named with a date stamp, for example events-2012-09.log. The pattern for the file name is configurable. This logger supports several advanced features:
    • Files are "thread safe": locked so that multiple process can safely log to a common file
    • Files are "fork safe": The file is closed and reopened if a fork is detected $ LogDispatch::Screen: Logs to STDERR, which is typically written to the Apache (Web Server) error log.. $ LogDispatch::Syslog: Logs to the local Syslog daemon. By default logs to the user facility.

The architecure of LogDispatch is pluggable. It is expected that additional loggers will be added, such as Log::Dispatch::DBI, Log::Dispatch::Jabber, etc.

Note that all loggers can be enabled to log all levels to all methods. When a log message is requested by a Foswiki function, Log::Dispatch examines the log level of the request, and passes the message to each enabled logger in sequence that has requested that log level.

Foswiki Logging

Log::Dispatch supports the 8 logging levels typical in most logging systems. debug-0 info-1, notice-2, warning-3, error-4, critical-5, alert-6 and emergency-7, however Foswiki uses only a subset of these levels:
  • debug level 0 is used for some error reporting, and when debugging is enabled in the core and for some extensions.
  • info level 1 is used for transation logging. The following fields are written by default:
Timestamp* and *log level User ID Action Web.Topic Agent String IP Address
2012-09-23T03:15:54Z info guest view LogDispatchContrib Firefox
  • warning Errors and other failures are written to the warning log level

Logger features and configuration

Common configuration for all loggers

The followng common features apply to all Loggers:

$ $Foswiki::cfg{Log}{LogDispatch}{MaskIP}: Hide IP Addresses logged in the event log. Default; IP addresses are logged. Two possible options can be configured; x.x.x.x will cause the remoteAddr field to be replaced with x.x.x.x. hash will cause the IP address to be scrambled, so that the original address is not easily identifiable, but multiple transactions from the same IP address will be logged using the same address. Note; the hash method does not work for IPv6 addresses. $ $Foswiki::cfg{Log}{LogDispatch}{EventIterator}: Specified which logger should be used to retrieve messages when the eachEventSince function is used. This is an expert level setting. See the help in bin/configure for more information. $ $Foswiki::cfg{Log}{LogDispatch}{FlatLayout}: Defines the record layout used to write the log to a flat file. This is an expert level setting. See the help in bin/configure for more information. Currently a common format can be set the four supported loggers.

LogDispatch::File simple file logging

When enabled, the default configuration:
  • debug messages (Level 0) are writen to debug.log
  • info messages (Level 1) are written to events.log
  • notice-emergency (Levels 2-7) are written to error.log

This can be overridden with an "Expert" level configuration variable, which assigns a range of log levels to a filename prefix. The left side of the => is the filename prefix, and the right side is the lower:higher log level to be written to that file.

There is an extra filter option that can be used to direct a subset of log messages to a file. The log request is assembled into the complete message, and then the optional 3rd parameter is applied as a regular expression against that message. If the regex matches, the record will be logged.

This example implements the default log levels as shown above, and then applies two filtered loggers:
  • Authentication messages (matching string AUTHENTICATION) are sent to auth.log
  • registration start, requests and rejections are logged to reg.log

$Foswiki::cfg{Log}{LogDispatch}{File}{FileLevels} = {
    debug  => 'debug:debug',
    events => 'info:info',
    error  => 'notice:emergency',
    auth   => 'info:info:AUTHENTICATION',
    reg    => 'info:warning:\\| [Rr]eg(start|ister|istration)',

LogDispatch::FileRolling "Stamped" file logger

ALERT! This logger has additional dependencies:
  • Log::Dispatch::File::Rolling must be installed using CPAN
  • Log::Log4perl::DateFormat required for the filename patern parsing

This is the recommended logger for file logging, especially on busy systems

When enabled, the default configuration:
  • debug messages (Level 0) are writen to debug-yyyy-mm.log
  • info messages (Level 1) are written to events-yyyy-mm.log
  • notice-emergency (Levels 2-7) are written to error-yyyy-mm.log

The FileRolling logger is very similar to the simple File logger, however it generates filenames using a pattern substitution for Year, Month, and a subset of other options supported by Log4Perl. The pattern substitution is applied only to the characters inside the %d{...} block. The default pattern:

$Foswiki::cfg{Log}{LogDispatch}{FileRolling}{Pattern} = '-%d{yyyy-MM}.log';
is appended to the filename prefix, and the substitution is applied. For example: error-2012-09.log or events-2012-12.log

TIP In order to "continue" an existing PlainFile log using LogDispatchContrib:
  • Quiesce your Foswiki system to avoid writing new log messages
  • Move the old log files to the name that LogDispatch will use:
    • events.log to events.yyyymm
    • debug.log to debug.yyyymm
    • error.log to error.yyyymm
  • Using bin/configure, change the Pattern to %d{yyyyMM} and verify that FileRolling is enabled.
  • Restart / re-enable your server

The following character patterns are supported, however many will not make sense as part of a filename.

Character Definition Type eachEvent Example
G era designator (Text)   AD
e epoch seconds (Number) ALERT! 1315011604
y year (Number)   1996
M month in year (Number)   07
M month in year (Text) ALERT! July (Text if pattern longer than 2 characters)
d day in month (Number)   10
h hour in am/pm (1~12) (Number) ALERT! 12
H hour in day (0~23) (Number) ALERT! 0
m minute in hour (Number) ALERT! 30
s second in minute (Number) ALERT! 55
S millisecond (Number) ALERT! 978
E day in week (Text) ALERT! Tuesday
D day in year (Number)   189
a am/pm marker (Text) ALERT! PM
Z RFC 822 time zone (Text) ALERT! -0800
$ process id (Number) ALERT! 8232

  • ALERT! - not supported for eachEventSince log processing.
  • $ Process ID can be used to isolate logs per process to avoid any contention on extremely busy system, or when the system cannot support file locking.

As with the File logger, the log levels 0-7 are mapped to file name prefixes using an expert level parameter. However unlike the File logger, log filtering is not supported

$Foswiki::cfg{Log}{LogDispatch}{FileRolling}{FileLevels} = {
    debug  => 'debug:debug',
    events => 'info:info',
    error  => 'notice:emergency',

Screen (STDERR) logger

This method directs messages to the STDERR output. STDERR is normally recorded in the Apache error log. When enabled, the default configuration sends error, critical, emergency and alert messages to STDERR. There are two configuration options, specifying the lowest and highest log level to be sent to STDERR.

Syslog logger

ALERT! This logger has additional dependencies:
  • Sys::Syslog is required for Syslog logging

The Syslog logger uses the system Syslog facility to send messages to the system log. It is disabled by default. It has 5 configuration options:
  • Facility - specifies the Syslog Facility set in the log message. Default is user.
  • Identifier - specifies a string that is prepended to each log message. Default is Foswiki.
  • MinLevel and
  • MaxLevel specifies the range of log levels sent to the Syslog logger.
  • Logopt Logger options understood by Syslog. This is an expert level configuration. See http://perldoc.perl.org/Sys/Syslog.html and bin/configure help for details.


You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Possible future enhancements

  • Ensure consistent format for all logs - include the User, Web.Topic and IP address
  • Add DBI logger
  • IPv6 support
  • Add Jabber, DBI, Windows even type loggers
  • Add filtering support for the FileRolling logger similar to the File * logger.


Author: George Clark
Copyright ©: 2012, Foswiki:Main.GeorgeClark
License: GPL (GNU General Public License 3)
Log::Dispatch>=0May be required for lib/Foswiki/Logger/LogDispatch.pm
Log::Dispatch::File::Rolling>=0May be required for lib/Foswiki/Logger/LogDispatch.pm
Log::Dispatch::Screen>=0May be required for lib/Foswiki/Logger/LogDispatch.pm
Sys::Syslog>=0.16Optional May be required for Syslog logging
Log::Log4perl::DateFormat>=0Optional May be required for lib/Foswiki/Logger/LogDispatch.pm
Version: 15575 (2012-10-12)
Release: 1.0.1
Change History:  
1.0.1 (15 Oct 2012): Continued devlopment
1.0.0 (XX Mmm 20XX): Initial version
Home: http://foswiki.org/Extensions/LogDispatchContrib
Support: http://foswiki.org/Support/LogDispatchContrib

PackageForm edit

ExtensionClassification Admin, Data and Files
ExtensionType ContribPackage
Compatibility Foswiki 1.1 and beyond.
DemoUrl http://
SupportUrl LogDispatchContrib
ModificationPolicy PleaseFeelFreeToModify
Topic attachments
I Attachment Action Size Date Who Comment
LogDispatchContrib.md5md5 LogDispatchContrib.md5 manage 177 bytes 15 Oct 2012 - 18:51 GeorgeClark  
LogDispatchContrib.sha1sha1 LogDispatchContrib.sha1 manage 201 bytes 15 Oct 2012 - 18:51 GeorgeClark  
LogDispatchContrib.tgztgz LogDispatchContrib.tgz manage 18 K 15 Oct 2012 - 18:51 GeorgeClark  
LogDispatchContrib.zipzip LogDispatchContrib.zip manage 42 K 15 Oct 2012 - 18:51 GeorgeClark  
LogDispatchContrib_installerEXT LogDispatchContrib_installer manage 6 K 15 Oct 2012 - 18:51 GeorgeClark  
Topic revision: r4 - 11 Jan 2016, GeorgeClark - This page was cached on 14 Jan 2018 - 19:11.

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License