Return to evguidep.txt CVS log

Up to [WindowsNT SDKs] / mstools / info

Annotation of mstools/info/evguidep.txt, revision 1.1

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.