2.17. ETW – Event Tracing for Windows

The EtwManager instance is accessible via windows.system.etw

Note

This code is the result of my research on ETW that lead to this presentation ETW for the lazy reverser (FR)

Note

See sample ETW (Event Tracing for Windows)

2.17.1. EtwManager

class windows.winobject.event_trace.EtwManager

An object to query ETW session/providers and open new trace

open_trace(name=None, logfile=None, guid=None)

Open a new ETW Trace

Returns:

EtwTrace

property providers

The list of currently existing ETW providers.

Type:

[TraceProvider] – A list of ETW providers

property sessions

The list of currently active ETW session.

Type:

[EventTraceProperties] – A list of EventTraceProperties

2.17.2. Tracing Events

2.17.2.1. EtwTrace

class windows.winobject.event_trace.EtwTrace(name, logfile=None, guid=None)

Represent an ETW Trace for tracing/processing events

enable(guid, flags=255, level=255)

Enable the specified event trace provider.

enable_ex(guid, flags=255, level=255, any_keyword=4294967295, all_keyword=0)

Enable the specified event trace provider.

exists()

Return True if the trace already exist (based on its name)

flush()

Flush the trace

guid

The guid of the trace

logfile

The logging file of the trace (None means real time trace)

name

The name of the trace

process(callback, begin=None, end=None, context=None)

Process the event retrieved by the trace. This function will call callback with any EventRecord in the trace. begin/end allow to filter and only process events in a given timeframe.

Warning

If the trace if REALTIME (no logfile) this function will hang/process new event until the trace is stopped.

Using logman -ets stop TRACE_NAME for exemple.

start(flags=0, mode=0)

Start the tracing

stop(soft=False)

stop the tracing.

soft will allow to stop a non-existing trace that do not exists/run. This allow for simpler script that stop/start some EtwTrace.

2.17.2.2. EventTraceProperties

class windows.winobject.event_trace.EventTraceProperties

Represent an Event Trace session that may exist or now. (https://docs.microsoft.com/en-us/windows/win32/api/evntrace/ns-evntrace-event_trace_properties)

This class is widly used by EtwTrace

classmethod create()

Initialize a new EventTraceProperties

property guid

The GUID of the Event Trace session (see Wnode.Guid)

property id

The LoggerId if the session (see Wnode.HistoricalContext)

property logfile

The logfile associated with the session

property name

The name of the session

2.17.2.3. EventRecord

class windows.winobject.event_trace.EventRecord

property guid

Guid of the Event

property id

ID of the Event

property pid

Process ID that provided the event

property tid

Thread ID that provided the event

property user_data

Event specific data

Type:

str