Logging Guidelines

Event logs store records of significant events on behalf of Windows NT/Windows 2000 and applications running on Windows NT/Windows 2000. Because the logging functions are general purpose, you must decide what information is appropriate to log. Generally, you should log only information that could be useful in diagnosing a hardware or software problem. Event logging is not intended to be used as a tracing tool.

Choosing Events to Log

The following are examples of cases in which event logging can be helpful:

• Resource problems. If an application gets into a low-memory situation (caused by a code bug or inadequate memory) that degrades performance, logging a warning event when memory allocation fails might provide a clue about what went wrong.
• Hardware problems. If a device driver encounters a disk controller time-out, a power failure in a parallel port, or a data error from a network or serial card, logging information about these events can help the system administrator diagnose hardware problems. The device driver logs the error.
• Bad sectors. If a disk driver encounters a bad sector, it may be able to read from or write to the sector after retrying the operation, but the sector will go bad eventually. Therefore, if the disk driver can proceed, it should log a warning; otherwise, it should log an error event. If a file system driver finds a large number of bad sectors, fixes them, and logs warning events, logging information of this type might indicate that the disk is about to fail.
• Information events. A server application (such as a database server) records a user logging on, opening a database, or starting a file transfer. The server can also log error events it encounters (cannot access file, host process disconnected, and so on), a corruption in the database, or whether a file transfer was successful.

Writing Messages

Remember that your audience is administrators and users who are trying to troubleshoot the problem. A message should contain all information needed to interpret what caused the problem and what to do to correct the problem. Avoid writing a cryptic message like the following:

A driver packet received from the I/O subsystem was invalid. 
The data is the packet. 

A better message would indicate that the driver in question is functioning properly, but is logging incorrectly formatted packets. It would go on to say that a Unicode version of the driver is needed to correct the problem. For more information, see Error Message Guidelines.

Do not use tabs or commas in the message text. Event logfiles can be saved as comma or tab separated text files. Many organizations import these files into databases and the extra formatting characters require manual manipulation.

When using UNC names, or other links which contain spaces, enclose the name in angle brackets. For example, <\\sharename\servername>.

Windows 2000: Starting with Windows 2000, you can write a URL to the end of the message that points the user to related help material. The URL must be a full-qualified DNS host name. For example, you could append the following text to your messages:

For additional information on this message, please visit our support site at http://www.microsoft.com/Support/ProdRedirect/ContentSearch.asp.

The page should be an ASP page that redirects the user to the exact content that relates to the messages. It must parse additional parameters that are passed when the URL is clicked to determine where to redirect the user.

From the arguments passed to the ReportEvent function:

• Event source
• Event ID
• Event category

From the message DLL header for the event source:

• Company name
• Product name
• Product version
• File version

Reducing Overhead

Event logging consumes resources such as disk space and processor time. The amount of disk space that an event log requires and the overhead for an application that logs events depend on how much information you choose to log. This is why it is important to log only essential information. It is also good to place event logging calls in an error path in the code rather than in the main code path, which would reduce performance.

The amount of disk space required per event log record includes the members of the EVENTLOGRECORD structure. This is a variable length structure; strings and binary data are stored following the structure.