Module etw 

Real-time ETW event monitoring.

This module lets you observe system-wide activity as it happens — process creation, registry changes, network connections, file operations, and more — with low overhead and structured event access.

Internally this uses ETW (Event Tracing for Windows), the same infrastructure that powers Windows Performance Recorder, Process Monitor, and Microsoft Defender. The API hides the ETW complexity behind familiar builder and iterator patterns.

Privileges: Kernel tracing requires Administrator access. User-mode providers may run without elevation depending on provider ACLs. Kernel (SystemProvider) and user-mode GUID providers cannot be mixed in one session.

Quick Start

Monitor process creation and termination:

use windows_erg::etw::{EventTrace, SystemProvider};

let mut trace = EventTrace::builder("ProcessMonitor")
    .system_provider(SystemProvider::Process)
    .start()?;

let mut events = Vec::with_capacity(64);
loop {
    trace.next_batch(&mut events)?;
    for event in &events {
        println!("Event ID {}: PID={}", event.id, event.process_id);
    }
}

System Providers

SystemProvider values represent kernel-level event sources. Each covers a different area of system activity. Because they run inside the kernel they see events from all processes — no instrumentation required.

Provider	What it captures	Typical use case
Process	Process/thread start and stop	Process monitoring, EDR
Registry	Key/value read, write, delete	Auditing, config tracking
Network	TCP/UDP connections	Network monitoring, firewall
FileIo	File create, read, write, delete	File system auditing
ImageLoad	DLL/EXE load and unload	Code injection detection

Multiple Providers

Chain system_provider calls to monitor several sources in a single session:

let mut trace = EventTrace::builder("SecurityMonitor")
    .system_provider(SystemProvider::Process)
    .system_provider(SystemProvider::Registry)
    .system_provider(SystemProvider::Network)
    .start()?;

User-Mode Providers

You can subscribe to user-mode ETW providers directly by GUID:

let provider = GUID::from_u128(0x3d6fa8d1_fe05_11d0_9dda_00c04fd7ba7c);
let mut trace = EventTrace::builder("UserModeSession")
    .user_provider(provider)
    .start()?;

Buffer Tuning

High-volume providers (especially FileIo) benefit from larger buffers:

let trace = EventTrace::builder("FileMonitor")
    .system_provider(SystemProvider::FileIo)
    .buffer_size(256)       // 256 KB per buffer  (default: 64 KB)
    .min_buffers(10)        // pre-allocate 10    (default: 2)
    .max_buffers(50)        // cap at 50          (default: 20)
    .channel_capacity(50_000)
    .start()?;

Enrichment Features

The following enrichment options are available on EventTraceBuilder:

Method	Effect
with_stack_traces()	Capture call stacks per event
with_thread_context()	Include thread metadata in raw events
with_detailed_events()	Schema-based field parsing of raw payloads
with_cpu_samples()	Correlate CPU usage samples with the event stream

Already active:

• with_process_filter(pids) filters events by PID in the callback path before they are pushed to output channels.
• with_thread_context() attaches ThreadContext to raw TraceEvent values.
• with_stack_traces() parses ETW extended stack data into StackTrace.
• with_cpu_samples() attaches processor-number metadata as CpuSample.

Structs

CpuSample

Optional per-event CPU sampling enrichment.

EventField

A named field decoded from ETW payload data.

EventTrace

A running ETW trace session.

EventTraceBuilder

Builder for configuring an ETW trace session.

FileIoEvent

Typed representation of a decoded File I/O event.

ImageLoadEvent

Typed representation of a decoded image load event.

ImageUnloadEvent

Typed representation of a decoded image unload event.

ProcessEndEvent

Typed representation of a decoded process end event.

ProcessStartEvent

Typed representation of a decoded process start event.

RegistryEvent

Typed representation of a decoded Registry event.

StackTrace

Optional per-event stack trace enrichment.

TcpEvent

Typed representation of a decoded TCP event.

ThreadContext

Optional per-event thread metadata enrichment.

TraceEvent

A single event captured from a kernel trace session.

Enums

DecodedEvent

A decoded ETW event with typed fields.

EventFieldValue

Typed value for a schema-decoded ETW field.

EventStreamMode

Output stream strategy for ETW events.

FileIoOperation

Decoded operation kind for File I/O kernel provider events.

RegistryOperation

Decoded operation kind for Registry kernel provider events.

SystemProvider

System-level event sources for kernel tracing.

TcpOperation

Decoded operation kind for TCP kernel provider events.

TraceLevel

Verbosity level for a trace session.