<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Using the Windows event log</title>
</head>
<body bgcolor="#FFFFFF" text="#000000" link="#000099" vlink="#660066" alink="#FF0000">
<div align="center">
<p>
<a href="http://www.ravenbrook.com/">Ravenbrook</a> /
<a href="http://www.ravenbrook.com/project/">Projects</a> /
<a href="http://www.ravenbrook.com/project/p4dti/">Perforce Defect Tracking Integration</a> /
<a href="../../index.html">Version 2.0 Product Sources</a> /
<a href="../index.html">Design</a>
</p>
<p><i><a href="http://www.ravenbrook.com/project/p4dti/">Perforce Defect Tracking Integration Project</a></i></p>
<hr />
<h1>Using the Windows event log</h1>
<address>
<a href="mailto:gdr@ravenbrook.com">Gareth Rees</a>,
<a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>,
2001-09-12
</address>
</div>
<h2><a id="section-1" name="section-1">1. Introduction</a></h2>
<p> 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 <a href="http://www.ravenbrook.com/project/p4dti/issue/job000134/">job000134</a>
and <a href="http://www.ravenbrook.com/project/p4dti/issue/job000149/">job000149</a>. </p>
<p> The intended readership is project developers. </p>
<p> This document is not confidential. </p>
<h2><a id="section-2" name="section-2">2. Windows event log basics</a></h2>
<h3><a id="section-2.1" name="section-2.1">2.1. Reporting an event</a></h3>
<p> The Windows event log can be written from Python using the Python
Windows extensions [<a title="Python Programming on Win32"
href="#ref-Hammond-2000-01">Hammond 2000-01, page 359</a>]. Writing an
entry to the event log looks like this: </p>
<blockquote><pre class="source">
import win32evtlogutil
win32evtlogutil.ReportEvent(ApplicationName, EventID, EventCategory,
EventType, Inserts, Data, SID)
</pre></blockquote>
<p> See [<a title="Python Programming on Win32"
href="#ref-Hammond-2000-01">Hammond 2000-01, page 359</a>] for
descriptions of the arguments. </p>
<p> In the P4DTI, we use the following arguments: </p>
<p> <code>ApplicationName</code> is "P4DTI-" plus the replicator
identifier. </p>
<p> <code>EventCategory</code> is always 0 (we don't use message
categories). </p>
<p> <code>EventType</code> corresponds to the P4DTI message priority as
follows: </p>
<table border="1" cellspacing="0" cellpadding="5">
<tr valign="top">
<th>P4DTI priority</th>
<th>Windows event type</th>
</tr>
<tr valign="top">
<td>message.EMERG</td>
<td>win32evtlog.EVENTLOG_ERROR_TYPE</td>
</tr>
<tr valign="top">
<td>message.ALERT</td>
<td>win32evtlog.EVENTLOG_ERROR_TYPE</td>
</tr>
<tr valign="top">
<td>message.CRIT</td>
<td>win32evtlog.EVENTLOG_ERROR_TYPE</td>
</tr>
<tr valign="top">
<td>message.ERR</td>
<td>win32evtlog.EVENTLOG_ERROR_TYPE</td>
</tr>
<tr valign="top">
<td>message.WARNING</td>
<td>win32evtlog.EVENTLOG_WARNING_TYPE</td>
</tr>
<tr valign="top">
<td>message.NOTICE</td>
<td>win32evtlog.EVENTLOG_WARNING_TYPE</td>
</tr>
<tr valign="top">
<td>message.INFO</td>
<td>win32evtlog.EVENTLOG_INFORMATION_TYPE</td>
</tr>
<tr valign="top">
<td>message.DEBUG</td>
<td>win32evtlog.EVENTLOG_INFORMATION_TYPE</td>
</tr>
</table>
<h3><a id="section-2.2" name="section-2.2">2.2. Registering the event message file</a></h3>
<p> 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 </p>
<blockquote><code>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\FOO\EventMessageFile</code></blockquote>
<p> This names a Windows executable or DLL containing a message string
table resource. </p>
<p> The simplest way to create this registry key is to call the
<code>AddSourceToRegistry</code>. </p>
<blockquote><pre class="source">
import win32evtlogutil
win32evtlogutil.AddSourceToRegistry(ApplicationName, MessageDLL,
EventLogType)
</pre></blockquote>
<p> See [<a title="Python Programming on Win32"
href="#ref-Hammond-2000-01">Hammond 2000-01, page 359</a>] for
descriptions of the arguments. </p>
<h3><a id="section-2.3" name="section-2.3">2.3. Building the event message file</a></h3>
<p> We start out with the message file, <code>eventlog.mc</code>. This
is processed by the message compiler that comes with Microsoft Visual
Studio: </p>
<blockquote><samp>
"C:/Program Files/Microsoft Visual Studio/VC98/BIN/MC.exe" eventlog.mc
</samp></blockquote>
<p> This generates two files, <code>eventlog.rc</code> and
<code>MSG00001.bin</code>. 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 <code>eventlog.cpp</code> and <code>eventlog.rc</code> to the
project. When Visual Studio builds this project it produces the event
message file, <code>eventlog.dll</code>. </p>
<h2><a id="section-3" name="section-3">3. User interface</a></h2>
<p> 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 <code>log_level</code> configuration parameter. </p>
<p> To avoid (possibly unpleasant) surprises when upgrading from an old
release of the P4DTI, the event log is turned off by default. </p>
<p> 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. </p>
<h2><a id="section-A" name="section-A">A. References</a></h2>
<table>
<tr valign="top">
<td>[<a id="ref-Hammond-2000-01" name="ref-Hammond-2000-01">Hammond 2000-01</a>]</td>
<td>
"Python Programming on Win32";
Mark Hammond and Andy Robinson;
OReilly;
2000-01;
ISBN 1-56592-621-8.
</td>
</tr>
</table>
<h2><a id="section-B" name="section-B">B. Document History</a></h2>
<table>
<tr valign="top">
<td>2001-09-12</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Created.</td>
</tr>
</table>
<hr />
<p> <small>This document is copyright © 2001 Perforce Software, Inc. All rights reserved.</small> </p>
<p> <small>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.</small> </p>
<p> <small> <strong> 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. </strong> </small> </p>
<div align="center">
<p><code>$Id: //info.ravenbrook.com/project/p4dti/version/2.0/design/win32-eventlog/index.html#2 $</code></p>
<p>
<a href="http://www.ravenbrook.com/">Ravenbrook</a> /
<a href="http://www.ravenbrook.com/project/">Projects</a> /
<a href="http://www.ravenbrook.com/project/p4dti/">Perforce Defect Tracking Integration</a> /
<a href="../../index.html">Version 2.0 Product Sources</a> /
<a href="../index.html">Design</a>
</p>
</div>
</body>
</html>