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.