Struct EventTraceBuilder 

pub struct EventTraceBuilder { /* private fields */ }

Builder for configuring an ETW trace session.

Obtained from EventTrace::builder. Chain configuration methods, then call start to begin tracing and receive an EventTrace handle.

Implementations

impl EventTraceBuilder

pub fn system_provider(self, provider: SystemProvider) -> Self

Add a kernel event source to this trace session.

Can be called multiple times to monitor several sources at once. At least one provider must be added before calling start.

Example

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

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

pub fn user_provider(self, provider_guid: GUID) -> Self

Add a user-mode ETW provider by GUID.

This enables events from providers registered with EventRegister (for example application or service providers).

User-mode providers cannot be mixed with kernel SystemProviders in a single session.

pub fn buffer_size(self, size_kb: u32) -> Self

Set buffer size in kilobytes (default: 64 KB).

Larger buffers reduce the chance of losing events at the cost of memory.

pub fn min_buffers(self, count: u32) -> Self

Set the minimum number of event buffers pre-allocated by the OS (default: 2).

pub fn max_buffers(self, count: u32) -> Self

Set the maximum number of event buffers the OS may allocate (default: 20).

pub fn flush_interval(self, seconds: u32) -> Self

Set how often the OS flushes filled buffers, in seconds (default: 1).

pub fn channel_capacity(self, capacity: usize) -> Self

Set the internal event channel capacity (default: 10 000).

Bounds memory usage during high-volume tracing. Events beyond this limit are dropped when the consumer falls behind.

pub fn with_decoded_stream(self) -> Self

Emit only decoded events to avoid raw event allocation overhead.

pub fn with_both_streams(self) -> Self

Emit both raw and decoded events.

pub fn with_stack_traces(self) -> Self

Capture stack trace metadata for events when ETW provides it.

When enabled, raw TraceEvent values may include stack_trace parsed from event extended data items.

pub fn with_thread_context(self) -> Self

Include thread context metadata in each event.

When enabled, raw TraceEvent values include thread_context metadata populated from the ETW event header (ProcessId and ThreadId).

pub fn with_detailed_events(self) -> Self

Parse event payloads into named fields using the provider schema (planned feature).

When implemented, the raw data bytes in each TraceEvent will be pre-decoded into structured fields based on the provider’s event schema.

pub fn with_cpu_samples(self) -> Self

Attach basic CPU sampling metadata to each raw event.

When enabled, raw TraceEvent values include cpu_sample with the logical processor number from ETW buffer context.

pub fn with_process_filter<I, P>(self, pids: I) -> Self

where I: IntoIterator<Item = P>, P: Into<ProcessId>,

Restrict event collection to specific process IDs.

When non-empty, only events whose ProcessId matches one of pids are forwarded from the ETW callback to the output channels.

Example

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

let trace = EventTrace::builder("TargetedMonitor")
    .system_provider(SystemProvider::FileIo)
    .with_process_filter(vec![1234, 5678])
    .start()?;

pub fn start(self) -> Result<EventTrace>

Start the trace session and return an EventTrace handle.

Errors

Condition	Error
Empty session name	EtwError::SessionStartFailed
Name longer than 1024 chars	EtwError::SessionStartFailed
No providers specified	EtwError::SessionStartFailed
Mixed kernel + user providers	EtwError::SessionStartFailed
min_buffers > max_buffers	EtwError::SessionStartFailed
NT Kernel Logger already running	SessionStartFailed with ERROR_ALREADY_EXISTS
Windows API failure	EtwError::SessionStartFailed with OS error code