USING THE WINDOWS EVENT LOG

              Gareth Rees, Ravenbrook Limited, 2001-09-12


1. INTRODUCTION

This document describes how the P4DTI uses the Windows Event Log service
to log its activity.  The implementation of this design is intended to
fix job000134 and job000149.

The intended readership is project developers.

This document is not confidential.


2. WINDOWS EVENT LOG BASICS


2.1. Reporting an event

The Windows event log can be written from Python using the Python win32
extensions [Hammond 2000-01, page 359].  Writing an entry to the event
log looks like this:

    import win32evtlogutil
    win32evtlogutil.ReportEvent(ApplicationName, EventID, EventCategory,
                                EventType, Inserts, Data, SID)

See [Hammond 2000-01, page 359] for descriptions of the arguments.

In the P4DTI, we use the following arguments:

ApplicationName is "P4DTI-" plus the replicator identifier.

EventCategory is always 0 (we don't use message categories).

EventType corresponds to the P4DTI message priority as follows:

    P4DTI priority      Windows event type
    ---------------------------------------------------------
    message.EMERG       win32evtlog.EVENTLOG_ERROR_TYPE
    message.ALERT       win32evtlog.EVENTLOG_ERROR_TYPE
    message.CRIT        win32evtlog.EVENTLOG_ERROR_TYPE
    message.ERR         win32evtlog.EVENTLOG_ERROR_TYPE
    message.WARNING     win32evtlog.EVENTLOG_WARNING_TYPE
    message.NOTICE      win32evtlog.EVENTLOG_WARNING_TYPE
    message.INFO        win32evtlog.EVENTLOG_INFORMATION_TYPE
    message.DEBUG       win32evtlog.EVENTLOG_INFORMATION_TYPE


2.2. Registering the event message file

The Windows Event Viewer find the format strings for an event in the
application log for the application FOO by looking for a Windows
Registry key named

    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\FOO\EventMessageFile

This names a Windows executable or DLL containing a message string table
resource.

The simplest way to create this registry key is to call the
AddSourceToRegistry.

    import win32evtlogutil
    win32evtlogutil.AddSourceToRegistry(ApplicationName, MessageDLL,
                                        EventLogType)

See [Hammond 2000-01, page 359] for descriptions of the arguments.


2.3. Building the event message file

We start out with the message file, eventlog.mc.  This is processed by
the message compiler that comes with Microsoft Visual Studio:

    "C:/Program Files/Microsoft Visual Studio/VC98/BIN/MC.exe" eventlog.mc

This generates two files, eventlog.rc and MSG00001.bin.  We use these
files to build a DLL containing (1) a stub entry point so that it
qualifies as a DLL; and (2) the messages.  We do this by creating a DLL
project in Visual Studio and adding eventlog.cpp and eventlog.rc to the
project.  When Visual Studio builds this project it produces the event
message file, eventlog.dll.


3. USER INTERFACE

As far as I can tell, there's no way of filtering the messages that end
up in the log on the basis of their type.  This is different from the
situation with syslog, where the syslog configuration can be set to
filter messages by priority.  So instead we filter them in the logger
class based on the log_level configuration parameter.

To avoid (possibly unpleasant) surprises when upgrading from an old
release of the P4DTI, the event log is turned off by default.

If you turn it on, you need to (1) install the Python interface to
Windows and (2) specify the "Overwrite events as needed" setting in the
Windows event viewer so that you are not overwhelmed with complaints
from the event log.  The AG notes both of these points.


A. REFERENCES

[Hammond 2000-01] "Python Programming on Win32"; Mark Hammond and Andy
Robinson; O'Reilly; 2000-01.


B. DOCUMENT HISTORY

2001-09-12 GDR Created.


C. COPYRIGHT AND LICENCE

Copyright 2001 Ravenbrook Limited.  This document is provided "as is",
without any express or implied warranty.  In no event will the authors
be held liable for any damages arising from the use of this document.
You may make and distribute verbatim copies of this document provided
that you do not charge a fee for this document or for its distribution.