Log::Dispatch::Win32EventLog - Class for logging to the Windows NT Event Log


This document describes version 0.14 of Log::Dispatch::Win32EventLog, released 2006-10-21.


  use Log::Dispatch::Win32EventLog;

  my $log = Log::Dispatch::Win32EventLog->new(
      name       => 'myname'
      min_level  => 'info',
      source     => 'My App'

  $log->log(level => 'emergency', messsage => 'something BAD happened');


Log::Dispatch::Win32EventLog is a subclass of Log::Dispatch::Output, which inserts logging output into the windows event registry.


  $log = Log::Dispatch::Win32EventLog->new(%params);

This method takes a hash of parameters. The following options are valid:


Same as various Log::Dispatch::* classes.


This will be the source that the event is recorded from. Usually this is the name of your application.

The source name should not contain any backslash characters. If it does, they will be changed to underscores and a warning will be issued. This is due to a restriction of the NT Event Log.


Registration of an event source removes the warning about the event being from an unknown source. It also allows you to post to a log other than the Application log.

When you register a source to particular log, all future events will be posted to that log, even if you unregister the source and attempt to register it to a different log. If you want to change the log, you will have to change the source name.

If you register a source to the Security log, informational events will be tagged as "Audit Success" and higher levels will be tagged as "Audit Failure".

In order to use this feature, you must have Win32::EventLog::Message installed.

The process that registers the event sources may need permission to register the event. In some cases you may first need to run a simple script which registers the source name while logged in as an administrator:

  use Log::Dispatch;
  use Log::Dispatch::Win32EventLog 0.10;

  my $dispatch = Log::Dispatch->new;
  $dispatch->add( Log::Dispatch::Win32EventLog->new(
    source   => 'MySourceName',
    register => 'System',

afterwards the source name should be properly registered, and any script with rights to post to the event logs should be able to post.

This is an experimental feature. See the "KNOWN ISSUES" section for more information.


inherited from Log::Dispatch::Output.

Using with Log4perl

This module can be used as a Log::Log4perl appender. The configuration file should have the following:

  log4perl.appender.EventLog         = Log::Dispatch::Win32EventLog
  log4perl.appender.EventLog.layout  = Log::Log4perl::Layout::SimpleLayout
  log4perl.appender.EventLog.source  = MySourceName
  log4perl.appender.EventLog.Threshold = INFO

Replace MySourceName with the source name of your application.

You can also use the log4j wrapper instead:

  log4j.category.cat1                = INFO, myAppender

  log4j.appender.myAppender          = org.apache.log4j.NTEventLogAppender
  log4j.appender.myAppender.source   = MySourceName
  log4j.appender.myAppender.layout   = org.apache.log4j.SimpleLayout

See Log::Log4perl::JavaMap::NTEventLogAppender for more information.


See for an up-to-date list of known issues and bugs.

Full Event Logs

Depending on event log settings, if they are at their maximum size and the automatic purging of older events is disabled, then some of the tests may fail. Clear the event logs and re-test the module.

Source Registration

Event source registration may fail sporadically. It may not work when a source is registered for the first time, or when the event log has been newly cleared.

IIS and Windows Server 2003

In some server configurations using IIS (Windows Server 2003), you may need to set security policy to grant permissions to write to the event log(s).

See Microsoft KnowledgeBase Article 323076 at;en-us;323076.

Older versions of

Earlier versions of Win32 do not have a function called IsAdminUser. Tests which require the user to be an administrator will be skipped, with a message saying that the "User is not an administrator" (even when the user is an administrator).


Log::Dispatch, Win32::EventLog, Log::Log4perl

Win32::EventLog::Carp traps warn and die signals and sends them to the NT event log.


David Landgren (current maintainer) <dland at>

Robert Rothenberg <rrwo at>

Artur Bergman <abergman at>

Gunnar Hansson <gunnar at>


Much thanks to Frank Chan <fpchan at> for testing several developer releases of this module.


This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.