mstools/info/evguidep.txt - view

File: [WindowsNT SDKs] / mstools / info / evguidep.txt
Revision 1.1.1.1 (vendor branch): download - view: text, annotated - select for diffs
Thu Aug 9 18:21:00 2018 UTC (7 years, 9 months ago) by root
Branches: msft, MAIN
CVS tags: ntsdk-jun-1992, HEAD

Microsoft Windows NT Build 297 06-28-1992

Windows NT Event Reporting Guidelines Windows NT Event Reporting Guidelines Windows NT Event Reporting Guidelines Revision Revision Revision 0.2P, 27-Jun-92 This document is expressly for external use Microsoft Corporation Company Confidential Windows NT Event Reporting Guidelines - i Introduction............................................2 Popups and Logs.........................................2 Event Logging...........................................3 Source................................................4 Event ID..............................................4 Event Type............................................4 Category..............................................5 Strings...............................................5 Description...........................................6 Data..................................................6 Microsoft Corporation Company Confidential Windows NT Event Reporting Guidelines 2 Introduction Introduction Introduction Many applications (particularly services), and Windows itself, have the need to record important events which occur while they are running. Events may be anything from asserting the fact that SQL Server has started, to asserting that it has crashed. After crashes or other errors, users, administrators, and support personnel have the task of trying to piece together what caused the problem so that they may prevent it from recurring and so they may have a better chance to recover damaged or lost data. Today, LAN Manager and other service applications like SQL Server and Lotus Notes record errors and events in various proprietary Error logs. These proprietary Error logs have different formats, use different user interfaces for their display, and cannot be merged to provide a complete picture. Yet, all of these logs are storing similar information, similarly controlling the logging of information, and presenting the logged data in similar ways. The goal of Windows Event logging is to provide a standard centralized way for applications and the system to record important software and hardware events, to supply a standard user interface for viewing the logs, a standard programmatic interface for examining the logs, and to provide a means to merge events from various sources into a single informative "story" of what happened. Therefore, Windows NT provides an Event Log service which may be called using Win32 API by any application to log important events. Windows NT also includes an administrative tool called the Event Viewer which allows one to view events in the event logs as well as manage the growth of these logs. Events are defined as any significant occurrence in system or application software which requires notification of one or more users. When an event occurs, there are two options for notifying the user: 1) interactive popup message and 2) logging to a log file. Either of these options may apply for a given event, depending upon its nature. The purpose of this document is to specify a set of guidelines for event handling for Windows NT applications. The goal is to provide critical information to the user while not unnecessarily disturbing their work flow and to do so in a consistent way across the system, and applications. Popups and Logs Popups and Logs Popups and Logs Whether to popup a local message, or log an event or some combination thereof must be determined on a case by case basis. The purpose of this section is to provide some guidelines to make the decision process more straightforward. Generally, more things are logged than require a popup. Thus, whenever a popup is appropriate, it is almost always appropriate to log an event to the event log as well. Microsoft Corporation Company Confidential Windows NT Event Reporting Guidelines 3 Popup Examples No diskette in drive, bad media, unformatted disk, etc. Disk hot fix error Messages delivered from Administrator (e.g. "I am going to shutdown the server \\KRUSTY") The last example shows that popups are not exclusively signs of dire emergency, but may be anything that the user will greatly benefit from being interrupted. To popup messages use the usual Win32 MessageBox API. Events should be logged whenever a something significant occurs such as an error or a change of security policy. All events that are logged should be done so in a way that is aimed at solving the user's problem. The purpose of logging errors is to inform the user that their system is having problems, and to guide them in how to rectify these problems. Security events are logged to help an administrator track changes to the security system and to identify possible security breaches. It is also appropriate to selectively log informational events, such as SQL Server started successfully. Remember, only messages which are of definite value to the end-user or technician should be logged -- ask yourself how the events you are planning to log will benefit someone in tracking down a problem. Event Logging Event Logging Event Logging Windows NT includes an event logging service which is always running. The event service exposes API for use by system software (subsystems, system security, device drivers, built-in services, etc.) and application software (e.g. third party services such as SQL Server, Comm Server, etc.). When an event occurs which needs to be logged, the system or application software calls the event service API. See the Win32 API specification for information about using the Event Log API. There are three different built-in event logs: System, Security, and Application. Only the Windows NT security system can log events to the Security log. Only the Windows NT system and built-in or third- party device drivers should log to the System event log. Services and other applications should log events to the Application log. Among the parameters that are supplied for logged events are: Source Source Source Name of software which logs the event (this may be called "Module" or "ModuleName" in some of the older documentation). Microsoft Corporation Company Confidential Windows NT Event Reporting Guidelines 4 Event ID Event ID Event ID Unique ID (per Source message file) which identifies the event for lookup of description. Event Event Event This is used for categorization of events (Viewer allows Type Type Type filtering by Type): Error, Warning, Information, Success Audit, Failure Audit Category Category Category This is used for categorization of events. Each Source may define their own categories. The Event Viewer UI will allow filtering by Category within Source. Strings Strings Strings insertion strings The that are used to substitute occurrence-specific values into fields within an event description. Example: Str1$ = "C:\foo", Description = "Could not open %1". Str1$ is substituted for %1, to create: "Could not open C:\foo" as the displayed information in the Event Viewer. Localized text description including place holders for Descri Descri Descri insertion strings (Text) for display in the Event Viewer. ption ption ption Descriptions are contained within message files which are per-source and looked up by Event Viewer at display time. Data Data Data This is event-specific data which will be displayed as a Hex/Text dump in the Event Viewer. Source Source Source Source is the name of the software which logs the event. For many applications, Source may be simply the application name (e.g. Microsoft Excel 4.0) or may reflect a sub-component of a large application service such as SQL Server (e.g. SQL Kernel). System software should reflect the subsystem component logging the event, such as "Windows NTFS", or the device driver name such as "3Com Elink II Driver", etc. Events logged by Windows User, GDI, or Base should all simply be logged as "Windows". Event ID Event ID Event ID Event IDs are looked up within a message file to locate a description string for presentation to the end user. In addition, they are useful for product support, as the user need only identify the Source and the Event ID for product support to know exactly which event has occurred. Event IDs are therefore unique to a particular message file. Event Type Event Type Event Type There are five defined types for Events. The representation of Type is as a bitmask for efficiency in filtering events in the Event Viewer. Each event, however, should only have one type-bit set -- Microsoft Corporation Company Confidential Windows NT Event Reporting Guidelines 5 that is, by convention, all events are of one type. The five types are as follows: informational events are used to note infrequent Informat Informat Informat significant events for successful operations. For ional ional ional example, when SQL Server successfully loads, it may be appropriate to log a "SQL Server has started" informational event. Note that while this is appropriate for major server services, it is generally inappropriate for desktop applications (e.g. Excel) to log an event each time it is started. Informational events should generally be used as a trace not facility. Warning Warning Warning warning events are used to indicate problems that are not significant, but which may foretell of future errors or other problems. Resource consumption warnings are a good candidate event class for warnings. For example, a warning could be logged if low on disk space. "Errors" which are recovered without loss of function or data can be classified as Warnings. Error Error Error error events are used to indicate significant problems that have occurred and that the user should know about. Errors usually indicate a loss of function or data. For example, if a service cannot be loaded during the boot process, an error event may be logged. Success Success Success these are security events when an audited access was Audit Audit Audit successful. For example, a successful logon attempt is a candidate for Success Audit events. Failure Failure Failure these are security events when an audited access Audit Audit Audit failed. For example, a failed attempt to open a file is a candidate for Failure Audit events. Category Category Category Categories are used to help organize the events for filtering in the Event Viewer. Each Source may define its own numbered Categories and the text strings to which they are mapped. In the Event Viewer, it is possible to filter based upon Source and within that, Category. By convention, when a Source does not define an event category for a given event, the Category field should be set to zero (0). Each Source must specify a category message file to be used to retrieve and display the Category names, based upon the Category value for a given event. The category message file may be the same file as the event description message file. Microsoft Corporation Company Confidential Windows NT Event Reporting Guidelines 6 Strings Strings Strings Strings are optional language independent (i.e. non-localized) strings which are used to fill in values for place holders in description strings. Since the Strings are not localized, it is critical that this field only be used to store language independent strings such as numeric values or string tokens (file names, usernames, etc.). It is not acceptable to use several Strings to "paste" together a larger description or to use non-token strings. Think of the insertion string as being data, not text, and you should be fine. For example, one should not not not do the following: Str1$ = successfully, Description = "User was %1 added to database." to form "User was successfully added to database" (the alternative being Str1$ = "not"). This is not acceptable for three reasons: 1) the strings "successfully" and "not" should be localized and 2) even if the insertion strings are obtained from language dependent message files, it would be done so at the time when the event is logged not viewed which may be the wrong language for the person using the Event Viewer, and 3) such substitutions of adverbs and adjectives will not work in many other languages. The above example should use two separate events. An example of an appropriate use of an insertion string is: Description = "Access denied. Attempted to open the file %1", Str1$ = "c:\foobar.c". Description Description Description Each event has associated with it a description which is located in a message file registered by the Source. The descriptions should be worded in a way that is meaningful to a user for them to understand what is wrong, and what actions to take. The description should be geared toward a user solving their own problem and should not be written for a support person or a programmer. The description strings are indexed by Event ID, enabling the Event Viewer to display event-specific text for any event based upon the Event ID. All descriptions should be localized and are language dependent. Description strings may optionally contain place holders for insertion strings. Each place holder is represented by a percent sign and an index number of the string to substitute. For example, %1 specifies to replace the %1 with the first insertion string, whereas %5 substitutes the fifth insertion string, etc. Descriptions should be understandable by the end user, and should be short and to the point, using very clear language and should avoid use of culture- specific phrases. If your event includes private data in the Data field, the end of the description should include some explanation as to what the Data field contains. For example, the network software often notes: "(The SMB Microsoft Corporation Company Confidential Windows NT Event Reporting Guidelines 7 is the event data)." As a convention, use parenthesis around these remarks as indicated in this example. Data Data Data Each event may have event-specific data associated with it. The Event Viewer has no knowledge of any of the events, and will only display this extra data in a Hex/Text dump format. Use event specific data sparingly, only include it if it is really useful to a support technician or a programmer. Example uses of event-specific data is found in many network events where SMBs and NCBs are included as event-specific data. In all cases, the last part of the description string should include a note about what information is available as event-specific data. See example in the Description section (above). Third party applications may use the Data field to store information which the application may wish to process independently of the Event Viewer. For example, a third party may write their own viewer specific to their events, or may write a program which scans the log files and makes reports including information from their event- specific data. Microsoft Corporation Company Confidential

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.