26.6 Querying the Event Logs

The Event Logs are typically a system administrator's first line of inquiry when trying to troubleshoot problems. Since they are so important, it is also important to see how we can make use of them with WMI. The two major components that we need to be concerned with are the Event Logs themselves and the events contained within each Event Log. We will first focus on properties of Event Logs.

The Win32_NTEventLogFile class represents an Event Log. Table 26-4 contains several Win32_NTEventLogFile properties that can be used to query or modify properties of a Event Log.

Table 26-4. Useful Win32_NTEventLogFile properties

Property	Description
FileSize	Size of the Event Log file in bytes.
LogFileName	Standard name used for describing the Event Log (e.g., Application).
MaxFileSize	Max size in bytes that the Event Log file can reach. This is a writeable property.
Name	Fully qualified path to the Event Log file.
NumberOfRecords	Total number of records in the Event Log.
OverwriteOutDated	Number of days after which events can be overwritten. This is a writeable property with 0 indicating to overwrite events as needed, 1-365 being the number of days to wait before overwriting, and 4294967295 indicating that events should never be overwritten.
OverwritePolicy	Text description of the overwrite policy (as specified by the OverwriteOutDated property). Can be one of WhenNeeded, OutDated, or Never.
Sources	Array of registered sources that may write entries to the Event Log.

Let's look at an example that displays all of the properties listed in Table 26-4 for each Event Log and sets the MaxFileSize and OverwriteOutDated properties if they have not already been set to the correct values. Since we want to iterate over all Event Logs, we will pass Win32_NTEventLogFile to the InstancesOf method. Example 26-2 shows how to accomplish this.

Example 26-2. Displaying properties of the Event Log using Win32_NTEventLogFile

strComputer = "."
intMaxFileSize = 10 * 1024 * 1024   ' << 10MB
intOverwriteOutDated = 180          ' << 6 months
   
Set objWMI = GetObject("winmgmts:\\" & strComputer & "\root\cimv2")
Set objELF = objWMI.InstancesOf("Win32_NTEventLogFile")
' Iterate over each Event Log
for each objEL in objELF
   WScript.Echo objEL.LogFileName & " Log:"
   WScript.Echo " FileSize: " & objEL.FileSize
   
   ' If the size has not been set yet, set it
   if objEL.MaxFileSize <> intMaxFileSize then
      WScript.Echo " ** Setting MaxFileSize: " & intMaxFileSize & " (new) " & _
                   objEL.MaxFileSize & " (current)"
      objEL.MaxFileSize = intMaxFileSize
      objEL.Put_
   else 
      WScript.Echo " MaxFileSize: " & objEL.MaxFileSize
   end if
   
   WScript.Echo " Name: " & objEL.Name
   WScript.Echo " NumberOfRecords: " & objEL.NumberOfRecords
   
   ' If the overwrite date has not been set, set it
   WScript.Echo " OverwritePolicy: " & objEL.OverwritePolicy
   if objEL.OverwriteOutDated <> intOverwriteOutDated then
      WScript.Echo " ** Setting OverwriteOutDated: " & _
                   intOverwriteOutDated & " (new) " & _ 
                   objEL.OverwriteOutDated & " (current)"
      objEL.OverwriteOutDated = intOverwriteOutdated
      objEL.Put_
   else 
      WScript.Echo " OverwriteOutDated: " & objEL.OverwriteOutDated
   end if
   
   WScript.Echo ""
next

Note that for the MaxFileSize and OverwriteOutDated properties, we set them only if they haven't been set already. To set properties, simply set the property method equal to the new value. To commit the change, you must use the Put_ method. Using Put_ is very similar to SetInfo in ADSI. WMI implements a caching mechanism very similar to the Property Cache described in Chapter 19. If we did not call Put_, the new values would never have been written back to the system.

The Event Logs contain a wealth of information about the health and status of the system and hosted applications. With WMI, system administrators can write simple to complex queries to find specific events in any of the Event Logs. The Win32_NTLogEvent class represents individual event entries in an Event Log. Table 26-5 contains several useful properties that are available for Win32_NTLogEvent objects.

Table 26-5. Useful Win32_NTLogEvent properties

Property	Description
CategoryString	Category name if present.
EventCode	The event number (or id) for the event.
EventType	Numeric value representing severity of the event. See Type for the string version.
LogFile	Event Log name the event is contained in. LogFile and RecordNumber are used as keys to uniquely identify an event.
Message	Event message text.
RecordNumber	The number associated with the event. RecordNumber is unique within an Event Log.
SourceName	Name of source that generated the error.
Type	String representing the severity of the event. Will be one of Error, Warning, Informational, Security audit success, or Security audit failure.
User	User that was logged on when event was generated.

In the next example, we will retrieve all events that match certain criteria. Let's say that we want to find all Information events in the System Event Log that have an event code of 5778 and were generated after November 1, 2002. The WQL for this query works out to be:

   Select * from Win32_NTLogEvent 
    Where Type = 'Information'
    And Logfile = 'System' 
    and EventCode = 5778
    and TimeGenerated > '2002/11/01'

Once we have the WQL query, the rest of the code is very similar to many of the previous examples.

strComputer = "."
   
Set objWMI = GetObject("winmgmts:\\" & strComputer & "\root\cimv2")
Set objEvents = objWMI.ExecQuery _
        ("Select * from Win32_NTLogEvent Where Logfile = 'System' " & _
         "and EventCode = 5778 and Type = 'Information' " & _
         "and TimeGenerated > '2002/11/01' ")
   
WScript.Echo "Total events that match criteria: " & objEvents.Count
for each objEvent in objEvents
   WScript.Echo " CategoryString: " & objEvent.CategoryString
   WScript.Echo " EventType: " & objEvent.EventType
   WScript.Echo " LogFile: " & objEvent.LogFile
   WScript.Echo " Message: " & objEvent.Message
   WScript.Echo " RecordNumber: " & objEvent.RecordNumber
   WScript.Echo " SourceName: " & objEvent.SourceName
   WScript.Echo " TimeGenerated: " & objEvent.TimeGenerated
   WScript.Echo " Type: " & objEvent.Type
   WScript.Echo " User: " & objEvent.User
   WScript.Echo ""
next