Using the Windows event log

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 Windows 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:

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

B. Document History

This document is copyright © 2001 Perforce Software, Inc. All rights reserved.

Redistribution and use of this document in any form, with or without modification, is permitted provided that redistributions of this document retain the above copyright notice, this condition and the following disclaimer.

This document is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright holders and contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this document, even if advised of the possibility of such damage.