Event Selection

Article
05/08/2009

Event selection refers to the process by which event consumers (subscribers and event log readers) select events from the Windows Event Log system. Event selection is the same regardless of whether the events are selected either as they arrive or from reading from an event log. Selecting events allows you to display information about the events or manage event log information.

Selecting Event Sources

A query selects events that match certain conditions. The following list describes possible sources from which an event can be selected:

An event log that is attached to a channel (referenced by the channel name) and handled as a sequence of events. A query applies only to the contents of the log. For more information, see Event Logs and Channels in Windows Event Log.
An external file that is handled as a sequence of events. The file is specified by a URL that uses "file" as its protocol. For example, file://c:/dir1/dir2/file.evtx.

The following list describes file formats supported by Windows Event Log:
- An event log archive (.evtx file).
- An .evt file (this is an event log archive from a Windows 2000, Windows XP, or Windows Server 2003 computer.
- An ETW file.

Relative paths and environment variables cannot be used when specifying a file. A Universal Naming Convention (UNC) path can be used to locate the file. Any relative path and environment variable expansion must be completed prior to making API calls.

Selecting Events

Each event source is handled as a document that contains a sequence of events. Windows Event Log uses query expressions based on a subset of XPath 1.0 for selecting events from their sources. When you specify a query, you also specify an event channel for the context of the query. You can also use XML and Boolean expressions to query for events.

When you select an event with an event query, the entire event is selected, not a portion of the event information.

For more information about how to use Windows Event Log to select events, see Querying for Events, Subscribing to Events, Maintaining Logged Events, Rendering Events.

Selection Filters

Filters can be used in XPath event queries to restrict events in the result set based on the event content. The event content is XML elements that contain values. The selection filter queries for specific values of specific XML elements in an event XML representation. For more information about how an event is represented in XML, see Event Representation for Event Consumers.

The following example shows how to use a valid XPath event query to select all the events (*) in the System channel.

Channel: System
Query: *

The following example shows how to use a query to select all the LowOnMemory events in the system channel.

Channel: System
Query: *[UserData/LowOnMemory]

The following example shows how to use a query to select all the Level 1 (Critical) severity level events in the system channel.

Channel: System
Query: *[System/Level=1]

The following example shows how to use compound expressions within the filter to form queries.

Channel: System
Query: *[UserData/*/PrinterName="MyPrinter" and System/Level=1]

When the XPath expressions are evaluated, type conversions are performed on the values specified in the expression to allow for better comparisons.

Note Be careful when comparing floating point numbers in XPath queries. Any string representation of a floating point number is approximated and the value displayed in XML might not match the number stored with the event. Floating point numbers should be compared as being less than or greater than a constant.

The string values from the specified XPath expression are converted to as many types as possible when the expression is prepared for evaluation. This assures that during the actual evaluation against an event, all required conversions of the values in the expression are available. The following list describes the order of conversion attempts for the values of specified in the XPath expression.

Both the Unicode and ANSI representations of the value are generated and stored.
A conversion to a number is attempted on the value, and either a double floating point value or 64 bit integer value representation is stored.
1. If the string contains the ".", "+", or "-" characters, then the parser attempts to convert the string into a double as if it were a floating point number.
2. If the conversion to a double value fails and the number starts with "0x" or "0X", an attempt is made to convert a hexadecimal number into an unsigned 64-bit integer.
3. If the hexadecimal conversion fails, an attempt is made to convert a decimal number into an unsigned 64-bit integer.
4. If all conversion attempts fail, no number is stored.
A Boolean conversion is performed.
1. If a numeric value is already stored, then a Boolean value is stored as well. The value is true for non-zero numbers and false for zero.
2. If there is no numeric value, then a case-sensitive comparison of the string is done to "true" and "false" strings. The appropriate Boolean value is saved if either comparison succeeds.
Each of the following conversions are attempted until either one of the conversions succeeds or all the conversions are attempted.
1. If the string value matches a GUID format, a GUID value is stored.
2. If the string value matches a SID formation, a SID value is stored.
3. If the string value is a date or time and can be represented by in a FILETIME structure, then the FILETIME structure is saved.
4. If the string value contains an even number of characters and each character is a hexadecimal digit, then the binary large object (BLOB) representation is stored.

Selection Limitations

Windows Event Log does not implement the full functionality of XPath 1.0. It only implements the features of XPath 1.0 which are useful in the eventing and logging scenarios. The primary restriction is that only XML elements that represent events can be selected by an event selector. An XPath query that does not select an event is illegal. Because all event elements are named Event, all valid selector paths start with * or Event. All location paths operate on the event nodes and are composed of a series of steps. Each step is a structure of three parts: the axis, node test, and predicate. For more information about these parts and about XPath 1.0, see XML Path Language (XPath). The Event Log XPath processor restricts event node processing in the following ways:

Axis: Only the Child (default) and Attribute (and its shorthand "@") axis are supported.
Node Tests: Only node names and NCName tests are supported. The "*" character, which selects any character, is supported.
Predicates: Any valid XPath expression is acceptable if the location paths conform to the following restrictions:
- Standard operators or, and, =, !=, <=, <, >=, >, and parentheses are supported.
- Generating a string value for a node name is not supported.
- Evaluation in reverse order is not supported.
- Node sets are not supported.
- Namespace scoping is not supported.
- Namespace, processing, and comment nodes are not supported.
- Context size is not supported.
- Variable bindings are not supported.
- The position function, and its shorthand array reference, are supported (on leaf nodes only).
- The Band function is supported. The function performs a bitwise AND for two integer number arguments. If the result of the bitwise AND is non-zero, the function evaluates to true, and otherwise, the function evaluates to false.
- The timediff function is supported. The function computes the difference between the second argument and the first argument. One of the arguments must be a literal number. An argument must have FILETIME representation. The result is the number of milliseconds between the two times and it is positive if the second argument represents a later time. It is negative otherwise. When the second argument is not provided, the current system time is used. For an example of how the timediff function is used, see the example queries in the next section.

XML Event Queries

XPath is the query language for selecting events. Additionally, XML fragments can be used to select events from an event source.

The fragment contains an element called <QueryList>. The element contains a set of <Query> elements, each specifying a set of selectors and suppressors. Selectors select events to return in the query result set, and suppressors suppress events from being returned in the result set. For more information about the XML elements that can be used in a query, see Query Schema.

The following XML example shows a set of <Query> elements that specify a set of selectors and suppressors for the query.

<QueryList>
  <Query Id="0" Path="Application">
    <Select Path="Application">
        *[System[(Level &lt;= 3) and 
        TimeCreated[timediff(@SystemTime) &lt;= 86400000]]]
    </Select>
    <Suppress Path="Application">
        *[System[(Level = 2)]]
    </Suppress>
    <Select Path="System">
        *[System[(Level=1  or Level=2 or Level=3) and 
        TimeCreated[timediff(@SystemTime) &lt;= 86400000]]]
    </Select>
  </Query>
</QueryList>

Each <Query> element is optionally identified by an identifier and can specify a path which applies to the selectors and suppressors it contains that do not specify a path of their own. The event query applies to each of the queries in sequence, returning a set of events that match any of the queries. A consumer can find the identifier of the queries that matched for each returned event.

The following list describes event query selectors and suppressors.

A selector selects events to be included in the result set of the filter that contains the selector (unless the events are rejected by a suppressor in the same query).

The following XML example shows how to use a query to select all the events from the System channel that occurred in the last 24 hours.
```
<QueryList>
  <Query Id="0" Path="System">
    <Select Path="System">*[System[(Level=2) and
        TimeCreated[timediff(@SystemTime) &lt;= 86400000]]]</Select>
  </Query>
</QueryList>
```
A suppressor has the same form as an event selector, but any events selected by it are omitted from the result set (even if the same events were selected by a selector in the query). There can be multiple suppressors within a query. The net result is that the events selected by the union of all suppressors are omitted from the result set.

The following XML example shows how to use a query to select all the events in the System channel, except those that have a Severity equal to Informational (Level equal to 4).
```
<Query id="1" path="System">
    <Select>*</Select>
    <Suppress>*[System/Level=4]</Suppress>
</Query>
```

Event Queries as Boolean Expressions

A single query with its set of selectors and suppressors can be viewed as a single Boolean expression. The Event Selector that is specified by a selector or suppressor can be viewed as a predicate that evaluates to true if the XPath expression selects an event.

For an event e, if we use Pn (e) for the nth selector predicate and use Rm (e) for the mth suppressor predicate, the Boolean expression that must evaluate to true for an event to be selected is:

(P1(e) | P2(e) | & | Pn(e)) & !(R1(e) | R2(e) | & | Rm(e))

Partager via