![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to evguidep.txt CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [WindowsNT SDKs] / mstools / info|
Return to evguidep.txt CVS log | Up to [WindowsNT SDKs] / mstools / info |
1.1 root 1:
2:
3:
4:
5:
6:
7:
8:
9:
10:
11:
12:
13:
14:
15:
16:
17:
18:
19:
20:
21:
22:
23:
24:
25:
26:
27:
28:
29:
30:
31:
32: Windows NT Event Reporting Guidelines
33: Windows NT Event Reporting Guidelines
34: Windows NT Event Reporting Guidelines
35:
36: Revision
37: Revision
38: Revision 0.2P, 27-Jun-92
39:
40: This document is expressly for external use
41:
42:
43:
44:
45:
46:
47:
48:
49:
50:
51:
52:
53:
54:
55:
56:
57:
58:
59:
60:
61:
62:
63:
64:
65:
66: Microsoft Corporation Company Confidential
67:
68:
69:
70: Windows NT Event Reporting Guidelines - i
71:
72:
73:
74:
75: Introduction............................................2
76:
77:
78: Popups and Logs.........................................2
79:
80:
81: Event Logging...........................................3
82:
83:
84: Source................................................4
85:
86:
87: Event ID..............................................4
88:
89:
90: Event Type............................................4
91:
92:
93: Category..............................................5
94:
95:
96: Strings...............................................5
97:
98:
99: Description...........................................6
100:
101:
102: Data..................................................6
103:
104:
105:
106:
107:
108:
109:
110:
111:
112:
113:
114:
115:
116:
117:
118:
119:
120:
121:
122:
123:
124:
125:
126:
127:
128: Microsoft Corporation Company Confidential
129:
130:
131:
132: Windows NT Event Reporting Guidelines 2
133:
134:
135:
136: Introduction
137: Introduction
138: Introduction
139:
140: Many applications (particularly services), and Windows itself, have
141: the need to record important events which occur while they are
142: running. Events may be anything from asserting the fact that SQL
143: Server has started, to asserting that it has crashed. After crashes
144: or other errors, users, administrators, and support personnel have
145: the task of trying to piece together what caused the problem so that
146: they may prevent it from recurring and so they may have a better
147: chance to recover damaged or lost data.
148:
149: Today, LAN Manager and other service applications like SQL Server and
150: Lotus Notes record errors and events in various proprietary Error
151: logs. These proprietary Error logs have different formats, use
152: different user interfaces for their display, and cannot be merged to
153: provide a complete picture. Yet, all of these logs are storing
154: similar information, similarly controlling the logging of
155: information, and presenting the logged data in similar ways.
156:
157: The goal of Windows Event logging is to provide a standard
158: centralized way for applications and the system to record important
159: software and hardware events, to supply a standard user interface for
160: viewing the logs, a standard programmatic interface for examining the
161: logs, and to provide a means to merge events from various sources
162: into a single informative "story" of what happened. Therefore,
163: Windows NT provides an Event Log service which may be called using
164: Win32 API by any application to log important events. Windows NT
165: also includes an administrative tool called the Event Viewer which
166: allows one to view events in the event logs as well as manage the
167: growth of these logs.
168:
169: Events are defined as any significant occurrence in system or
170: application software which requires notification of one or more
171: users. When an event occurs, there are two options for notifying the
172: user: 1) interactive popup message and 2) logging to a log file.
173: Either of these options may apply for a given event, depending upon
174: its nature. The purpose of this document is to specify a set of
175: guidelines for event handling for Windows NT applications. The goal
176: is to provide critical information to the user while not
177: unnecessarily disturbing their work flow and to do so in a consistent
178: way across the system, and applications.
179:
180: Popups and Logs
181: Popups and Logs
182: Popups and Logs
183:
184: Whether to popup a local message, or log an event or some combination
185: thereof must be determined on a case by case basis. The purpose of
186: this section is to provide some guidelines to make the decision
187: process more straightforward.
188:
189: Generally, more things are logged than require a popup. Thus,
190: whenever a popup is appropriate, it is almost always appropriate to
191: log an event to the event log as well.
192:
193:
194: Microsoft Corporation Company Confidential
195:
196:
197:
198: Windows NT Event Reporting Guidelines 3
199:
200:
201:
202: Popup Examples
203:
204: No diskette in drive, bad media, unformatted disk, etc.
205:
206: Disk hot fix error
207:
208: Messages delivered from Administrator (e.g. "I am going to
209: shutdown the server \\KRUSTY")
210:
211: The last example shows that popups are not exclusively signs of dire
212: emergency, but may be anything that the user will greatly benefit
213: from being interrupted. To popup messages use the usual Win32
214: MessageBox API.
215:
216: Events should be logged whenever a something significant occurs such
217: as an error or a change of security policy. All events that are
218: logged should be done so in a way that is aimed at solving the user's
219: problem. The purpose of logging errors is to inform the user that
220: their system is having problems, and to guide them in how to rectify
221: these problems. Security events are logged to help an administrator
222: track changes to the security system and to identify possible
223: security breaches. It is also appropriate to selectively log
224: informational events, such as SQL Server started successfully.
225:
226: Remember, only messages which are of definite value to the end-user
227: or technician should be logged -- ask yourself how the events you are
228: planning to log will benefit someone in tracking down a problem.
229:
230: Event Logging
231: Event Logging
232: Event Logging
233:
234: Windows NT includes an event logging service which is always running.
235: The event service exposes API for use by system software (subsystems,
236: system security, device drivers, built-in services, etc.) and
237: application software (e.g. third party services such as SQL Server,
238: Comm Server, etc.). When an event occurs which needs to be logged,
239: the system or application software calls the event service API.
240:
241: See the Win32 API specification for information about using
242: the Event Log API.
243:
244: There are three different built-in event logs: System, Security, and
245: Application. Only the Windows NT security system can log events to
246: the Security log. Only the Windows NT system and built-in or third-
247: party device drivers should log to the System event log. Services
248: and other applications should log events to the Application log.
249:
250: Among the parameters that are supplied for logged events are:
251:
252: Source
253: Source
254: Source Name of software which logs the event (this may be called
255: "Module" or "ModuleName" in some of the older
256: documentation).
257:
258:
259:
260: Microsoft Corporation Company Confidential
261:
262:
263:
264: Windows NT Event Reporting Guidelines 4
265:
266:
267:
268: Event ID
269: Event ID
270: Event ID Unique ID (per Source message file) which identifies the
271: event for lookup of description.
272:
273: Event
274: Event
275: Event This is used for categorization of events (Viewer allows
276: Type
277: Type
278: Type filtering by Type):
279:
280: Error, Warning, Information, Success Audit, Failure Audit
281:
282: Category
283: Category
284: Category This is used for categorization of events. Each Source
285: may define their own categories. The Event Viewer UI
286: will allow filtering by Category within Source.
287:
288: Strings
289: Strings
290: Strings insertion strings
291: The that are used to substitute
292: occurrence-specific values into fields within an event
293: description. Example: Str1$ = "C:\foo", Description =
294: "Could not open %1". Str1$ is substituted for %1, to
295: create: "Could not open C:\foo" as the displayed
296: information in the Event Viewer.
297:
298: Localized text description including place holders for
299: Descri
300: Descri
301: Descri insertion strings (Text) for display in the Event Viewer.
302: ption
303: ption
304: ption Descriptions are contained within message files which are
305: per-source and looked up by Event Viewer at display time.
306:
307: Data
308: Data
309: Data This is event-specific data which will be displayed as a
310: Hex/Text dump in the Event Viewer.
311:
312: Source
313: Source
314: Source
315:
316: Source is the name of the software which logs the event. For many
317: applications, Source may be simply the application name (e.g.
318: Microsoft Excel 4.0) or may reflect a sub-component of a large
319: application service such as SQL Server (e.g. SQL Kernel). System
320: software should reflect the subsystem component logging the event,
321: such as "Windows NTFS", or the device driver name such as "3Com Elink
322: II Driver", etc. Events logged by Windows User, GDI, or Base should
323: all simply be logged as "Windows".
324:
325: Event ID
326: Event ID
327: Event ID
328:
329: Event IDs are looked up within a message file to locate a description
330: string for presentation to the end user. In addition, they are
331: useful for product support, as the user need only identify the Source
332: and the Event ID for product support to know exactly which event has
333: occurred. Event IDs are therefore unique to a particular message
334: file.
335:
336: Event Type
337: Event Type
338: Event Type
339:
340: There are five defined types for Events. The representation of Type
341: is as a bitmask for efficiency in filtering events in the Event
342: Viewer. Each event, however, should only have one type-bit set --
343:
344:
345: Microsoft Corporation Company Confidential
346:
347:
348:
349: Windows NT Event Reporting Guidelines 5
350:
351:
352:
353: that is, by convention, all events are of one type. The five types
354: are as follows:
355:
356: informational events are used to note infrequent
357: Informat
358: Informat
359: Informat significant events for successful operations. For
360: ional
361: ional
362: ional example, when SQL Server successfully loads, it may be
363: appropriate to log a "SQL Server has started"
364: informational event. Note that while this is
365: appropriate for major server services, it is generally
366: inappropriate for desktop applications (e.g. Excel) to
367: log an event each time it is started. Informational
368: events should generally be used as a trace
369: not
370: facility.
371:
372: Warning
373: Warning
374: Warning warning events are used to indicate problems that are
375: not significant, but which may foretell of future
376: errors or other problems. Resource consumption
377: warnings are a good candidate event class for
378: warnings. For example, a warning could be logged if
379: low on disk space. "Errors" which are recovered
380: without loss of function or data can be classified as
381: Warnings.
382:
383: Error
384: Error
385: Error error events are used to indicate significant problems
386: that have occurred and that the user should know
387: about. Errors usually indicate a loss of function or
388: data. For example, if a service cannot be loaded
389: during the boot process, an error event may be logged.
390:
391: Success
392: Success
393: Success these are security events when an audited access was
394: Audit
395: Audit
396: Audit successful. For example, a successful logon attempt
397: is a candidate for Success Audit events.
398:
399: Failure
400: Failure
401: Failure these are security events when an audited access
402: Audit
403: Audit
404: Audit failed. For example, a failed attempt to open a file
405: is a candidate for Failure Audit events.
406:
407:
408:
409: Category
410: Category
411: Category
412:
413: Categories are used to help organize the events for filtering in the
414: Event Viewer. Each Source may define its own numbered Categories and
415: the text strings to which they are mapped. In the Event Viewer, it
416: is possible to filter based upon Source and within that, Category.
417: By convention, when a Source does not define an event category for a
418: given event, the Category field should be set to zero (0).
419:
420: Each Source must specify a category message file to be used to
421: retrieve and display the Category names, based upon the Category
422: value for a given event. The category message file may be the same
423: file as the event description message file.
424:
425:
426: Microsoft Corporation Company Confidential
427:
428:
429:
430: Windows NT Event Reporting Guidelines 6
431:
432:
433:
434: Strings
435: Strings
436: Strings
437:
438: Strings are optional language independent (i.e. non-localized)
439: strings which are used to fill in values for place holders in
440: description strings. Since the Strings are not localized, it is
441: critical that this field only be used to store language independent
442: strings such as numeric values or string tokens (file names,
443: usernames, etc.). It is not acceptable to use several Strings to
444: "paste" together a larger description or to use non-token strings.
445: Think of the insertion string as being data, not text, and you should
446: be fine.
447:
448: For example, one should not
449: not
450: not do the following: Str1$ = successfully,
451: Description = "User was %1 added to database." to form "User was
452: successfully added to database" (the alternative being Str1$ =
453: "not"). This is not acceptable for three reasons: 1) the strings
454: "successfully" and "not" should be localized and 2) even if the
455: insertion strings are obtained from language dependent message files,
456: it would be done so at the time when the event is logged not viewed
457: which may be the wrong language for the person using the Event
458: Viewer, and 3) such substitutions of adverbs and adjectives will not
459: work in many other languages. The above example should use two
460: separate events.
461:
462: An example of an appropriate use of an insertion string is:
463: Description = "Access denied. Attempted to open the file %1", Str1$
464: = "c:\foobar.c".
465:
466: Description
467: Description
468: Description
469:
470: Each event has associated with it a description which is located in a
471: message file registered by the Source. The descriptions should be
472: worded in a way that is meaningful to a user for them to understand
473: what is wrong, and what actions to take. The description should be
474: geared toward a user solving their own problem and should not be
475: written for a support person or a programmer.
476:
477: The description strings are indexed by Event ID, enabling the Event
478: Viewer to display event-specific text for any event based upon the
479: Event ID. All descriptions should be localized and are language
480: dependent. Description strings may optionally contain place holders
481: for insertion strings. Each place holder is represented by a percent
482: sign and an index number of the string to substitute. For example,
483: %1 specifies to replace the %1 with the first insertion string,
484: whereas %5 substitutes the fifth insertion string, etc. Descriptions
485: should be understandable by the end user, and should be short and to
486: the point, using very clear language and should avoid use of culture-
487: specific phrases.
488:
489: If your event includes private data in the Data field, the end of the
490: description should include some explanation as to what the Data field
491: contains. For example, the network software often notes: "(The SMB
492:
493:
494: Microsoft Corporation Company Confidential
495:
496:
497:
498: Windows NT Event Reporting Guidelines 7
499:
500:
501:
502: is the event data)." As a convention, use parenthesis around these
503: remarks as indicated in this example.
504:
505: Data
506: Data
507: Data
508:
509: Each event may have event-specific data associated with it. The
510: Event Viewer has no knowledge of any of the events, and will only
511: display this extra data in a Hex/Text dump format. Use event
512: specific data sparingly, only include it if it is really useful to a
513: support technician or a programmer. Example uses of event-specific
514: data is found in many network events where SMBs and NCBs are included
515: as event-specific data. In all cases, the last part of the
516: description string should include a note about what information is
517: available as event-specific data. See example in the Description
518: section (above).
519:
520: Third party applications may use the Data field to store information
521: which the application may wish to process independently of the Event
522: Viewer. For example, a third party may write their own viewer
523: specific to their events, or may write a program which scans the log
524: files and makes reports including information from their event-
525: specific data.
526:
527:
528:
529:
530:
531:
532:
533:
534:
535:
536:
537:
538:
539:
540:
541:
542:
543:
544:
545:
546:
547:
548:
549:
550:
551:
552:
553:
554:
555:
556:
557:
558: Microsoft Corporation Company Confidential
559:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.