The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.


Win32::EventLog::Carp - for carping in the Windows NT Event Log


This document describes version 1.41 of Win32::EventLog::Carp, released 2007-05-19.



These should be standard modules on Win32 systems.

The module will use Win32::EventLog::Message to register itself as a source, if that module is installed.


  use Win32::EventLog::Carp;
  croak "We're outta here!";

  use Win32::EventLog::Carp qw(cluck);
  cluck "This is how we got here!";


Win32::EventLog::Carp traps warnings and fatal errors in Perl and reports these errors in the Windows NT Event Log. This is useful for scripts which run as services or through the scheduler, and for CGI/ISAPI scripts.

The interface is similar to Carp: the carp, croak and confess functions are exported (with cluck being optional). You need only change references of "Carp" to "Win32::EventLog::Carp" to begin using this module.

One notable exception is the addition of the click function:

  Win32::EventLog::Carp::click "Hello!\n";

This outouts a message to STDERR with a short stack trace and allows scripts to post a simple "I have started" or "I am doing XYZ now" message to the log. To avoid the stack trace, end the message with a newline (which is what happens with the Carp module).



See the documentation to the Carp module for an explanation of these routines. The only difference is that instead of sending their output to STDERR, the message is also logged in the Application Log.


Similar to cluck, except that it prints to STDERR directly, rather than going through Carp.


If the Win32::EventLog::Message module is available, register the source with the Windows NT event log (this only works if the user has the proper permissions). This removes the 'description not found' warning in when looking at the event in the event log viewer.

Using Win32::EventLog::Carp with CGI::Carp

Some modules which trap the __WARN__ and __DIE__ signals are not very friendly, and will cancel out existing traps. The solution is to use this module after using other modules:

  use CGI::Carp;
  use Win32::EventLog::Carp


      $SIG{__WARN__} = \&my_handler;

  use Win32::EventLog::Carp

It is assumed that the previous handler will properly warn or die as appropriate. This module will instead report these events to the NT event log.

Logging failed evals

By default, this module will no longer log errors in the event log when something dies in an eval. If you would like to enable this, specify the LogEvals option:

  use Win32::EventLog::Carp
          LogEvals => 1

You can also change the value from within your program:

  $Win32::EventLog::Carp::LogEvals = 1;

Event Source Registration

If the Win32::EventLog::Message module is installed on the system, and if the script is run with the appropriate (Administrator) permissions, then Perl program will attempt register itself as an event source. Which means that

  carp "Hello";

will produce something like

  Hello at line 10

rather than

  The description for Event ID ( 0 ) in Source ( ) could
  not be found. It contains the following insertion string(s): Hello
  at line 10.

Redefining Event Sources

You can specify a different event source. The following

  use Win32::EventLog::Carp qw(cluck carp croak click confess),
          Source => 'MyProject'

will list the source as "MyProject" rather than the filename.

Logging to Security or System Logs

You can specify a log other than the Application Log to report events to:

  use Win32::EventLog::Carp 1.40
          Register => 'System'

Events can only be posted to one log. (For example, you cannot have some events go to the Application Log while others go to the Security Log.)

Once you have registered a source to an event log, it may not be possible to register it to a different log.

This feature should still be considered experimental.

Forcing a Stack Trace

As with Carp, you can force a stack trace by specifying the verbose option:

  perl -MCarp=verbose

Windows 95/98/ME

Windows 95/98/ME do not support the event log, so this module will not work on those operating systems. If you are writing scripts which will be used on both NT-based and non-NT-based operating systems, use the following workaround:

  require Win32;

  if (Win32::IsWinNT) {
    require Win32::EventLog::Carp;
    import Win32::EventLog::Carp 1.31;
  else {
    require Carp;
    import Carp;

This will import the standard Carp namespace for both types of machines, although the click function will not be available to Windows 95/98/ME scripts.


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

Basename of Event Source

We use the basename of the script as the event source, rather than the full pathname. This allows us to register the source name (since we cannot have slashes in registered event log source names).

The downside is that we have to view the event text to see which script it is (for common script names in a web site, for instance). In such cases, define a custom source name related to the application.

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.

Test::Exception and Test::Warn

When using Test::Exception functions such as dies_ok, the source will be listed as the "Test::Exception" module rather than the script that is running the tests.

Test::Warn functions will block warnings from being posted to the event log altogether.



Win32::EventLog::Message can be found at

A PowerPoint presentation about this module can be found at



David Landgren <dland at> (current maintainer)

Robert Rothenberg <rrwo at>

Suggestions and Bug Reporting

Feedback is always welcome. Please use the CPAN Request Tracker at to submit bug reports.


Copyright (c) 2000-2004, Robert Rothenberg. Copyright (c) 2006, David Landgren. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.