NXLog User Guide

109.9. Event Tracing for Windows (im_etw)

This module can be used to collect events through Event Tracing for Windows (ETW).

ETW is a mechanism in Windows designed for efficient logging of both kernel and user-mode applications. Debug and Analytical channels are based on ETW and cannot be collected as regular Windows Eventlog channels via the im_msvistalog module. Various Windows services such as the Windows Firewall and DNS Server can be configured to log events through Windows Event Tracing.

The im_etw module reads event tracing data directly for maximum efficiency. Unlike other solutions, im_etw does not save ETW data into intermediary trace files that need to be parsed again.

Note	The im_etw module is only available on the Windows platform.

109.9.1. Configuration

The im_etw module accepts the following directives in addition to the common module directives. One of KernelFlags and Provider must be specified.

KernelFlags: This directive specifies that kernel trace logs should be collected, and accepts a comma-separated list of flags to use for filtering the logs. The Provider and KernelFlags directives are mutually exclusive (but one must be specified). The following values are allowed: ALPC, CSWITCH, DBGPRINT, DISK_FILE_IO, DISK_IO, DISK_IO_INIT, DISPATCHER, DPC, DRIVER, FILE_IO, FILE_IO_INIT, IMAGE_LOAD, INTERRUPT, MEMORY_HARD_FAULTS, MEMORY_PAGE_FAULTS, NETWORK_TCPIP, NO_SYSCONFIG, PROCESS, PROCESS_COUNTERS, PROFILE, REGISTRY, SPLIT_IO, SYSTEMCALL, THREAD, VAMAP, and VIRTUAL_ALLOC.

Provider: This directive specifies the name (not GUID) of the ETW provider from which to collect trace logs. Providers available for tracing can be listed with logman query providers. The Provider and KernelFlags directives are mutually exclusive (but one must be specified). The Windows Kernel Trace provider is not supported; instead, the KernelFlags directive should be used to open a kernel logger session.

Level: This optional directive specifies the log level for collecting trace events. Because kernel log sessions do not provide log levels, this directive is only available in combination with the Provider directive. Valid values include Critical, Error, Warning, Information, and Verbose. If this directive is not specified, the verbose log level is used.

109.9.2. Fields

The following fields are used by im_etw.

Depending on the ETW provider from which NXLog collects trace logs, the set of fields generated by the im_etw module may slightly vary. In addition to the fields listed below, the module can generate special provider-specific fields. If the module is configured to collect trace logs from a custom provider (for example, from a custom user-mode application), the module will also generate fields derived from the custom provider trace logs.

$raw_event (type: string): A string containing a field=value pair for each field in the event.

$AccountName (type: string): The username associated with the event.

$AccountType (type: string): The type of the account. Possible values are: User, Group, Domain, Alias, Well Known Group, Deleted Account, Invalid, Unknown, and Computer.

$ActivityID (type: string): The ID of the activity corresponding to the event.

$ChannelID (type: integer): The channel to which the event log should be directed.

$Domain (type: string): The domain name of the user.

$EventId (type: integer): The Event ID, corresponding to the provider, that indicates the type of event.

$EventTime (type: datetime): The time when the event was generated.

$EventType (type: string): One of CRITICAL, ERROR, WARNING, DEBUG, AUDIT_FAILURE, AUDIT_SUCCESS, or INFO.

$ExecutionProcessID (type: integer): The ID of the process that generated the event.

$ExecutionThreadID (type: integer): The ID of the thread that generated the event.

$Keywords (type: string): A keyword bit mask corresponding to the current event.

$OpcodeValue (type: integer): An integer indicating the operation corresponding to the event.

$ProviderGuid (type: string): The GUID of the trace provider, corresponding to the $SourceName.

$Severity (type: string): The normalized severity name of the event. See $SeverityValue.

$SeverityValue (type: integer)

The normalized severity number of the event, mapped as follows.

Event Log Severity	Normalized Severity
0/Audit Success	2/INFO
0/Audit Failure	4/ERROR
1/Critical	5/CRITICAL
2/Error	4/ERROR
3/Warning	3/WARNING
4/Information	2/INFO
5/Verbose	1/DEBUG

Event Log Severity

Normalized Severity

0/Audit Success

2/INFO

0/Audit Failure

4/ERROR

1/Critical

5/CRITICAL

2/Error

4/ERROR

3/Warning

3/WARNING

4/Information

2/INFO

5/Verbose

1/DEBUG

$SourceName (type: string): The name of the trace provider.

$TaskValue (type: integer): An integer indicating a particular component of the provider.

$Version (type: integer): The version of the event type.

109.9.3. Examples

Example 545. Collecting Events From the Windows Kernel Trace

With this configuration, NXLog will collect trace events from the Windows kernel. Only events matching the PROCESS and THREAD flags will be collected.

nxlog.conf


  1
2
3
4

  <Input etw>
    Module      im_etw
    KernelFlags PROCESS, THREAD
</Input>

Example 546. Collecting Events From an ETW Provider

With this configuration, NXLog will collect events from the Microsoft-Windows-DNSServer trace provider.

nxlog.conf


  1
2
3
4

  <Input etw>
    Module      im_etw
    Provider    Microsoft-Windows-DNSServer
</Input>