windows_erg/etw/
mod.rs

1//! Real-time ETW event monitoring.
2//!
3//! This module lets you observe system-wide activity as it happens — process
4//! creation, registry changes, network connections, file operations, and more
5//! — with low overhead and structured event access.
6//!
7//! Internally this uses **ETW (Event Tracing for Windows)**, the same
8//! infrastructure that powers Windows Performance Recorder, Process Monitor,
9//! and Microsoft Defender. The API hides the ETW complexity behind familiar
10//! builder and iterator patterns.
11//!
12//! > **Privileges**: Kernel tracing requires **Administrator** access.
13//! > User-mode providers may run without elevation depending on provider ACLs.
14//! > Kernel (`SystemProvider`) and user-mode GUID providers cannot be mixed in one session.
15//!
16//! # Quick Start
17//!
18//! Monitor process creation and termination:
19//!
20//! ```no_run
21//! use windows_erg::etw::{EventTrace, SystemProvider};
22//!
23//! # fn main() -> windows_erg::Result<()> {
24//! let mut trace = EventTrace::builder("ProcessMonitor")
25//!     .system_provider(SystemProvider::Process)
26//!     .start()?;
27//!
28//! let mut events = Vec::with_capacity(64);
29//! loop {
30//!     trace.next_batch(&mut events)?;
31//!     for event in &events {
32//!         println!("Event ID {}: PID={}", event.id, event.process_id);
33//!     }
34//! }
35//! # Ok(())
36//! # }
37//! ```
38//!
39//! # System Providers
40//!
41//! [`SystemProvider`] values represent kernel-level event sources. Each covers
42//! a different area of system activity. Because they run inside the kernel they
43//! see events from **all processes** — no instrumentation required.
44//!
45//! | Provider | What it captures | Typical use case |
46//! |----------|-----------------|------------------|
47//! | `Process` | Process/thread start and stop | Process monitoring, EDR |
48//! | `Registry` | Key/value read, write, delete | Auditing, config tracking |
49//! | `Network` | TCP/UDP connections | Network monitoring, firewall |
50//! | `FileIo` | File create, read, write, delete | File system auditing |
51//! | `ImageLoad` | DLL/EXE load and unload | Code injection detection |
52//!
53//! # Multiple Providers
54//!
55//! Chain [`system_provider`][EventTraceBuilder::system_provider] calls to
56//! monitor several sources in a single session:
57//!
58//! ```no_run
59//! # use windows_erg::etw::{EventTrace, SystemProvider};
60//! # fn example() -> windows_erg::Result<()> {
61//! let mut trace = EventTrace::builder("SecurityMonitor")
62//!     .system_provider(SystemProvider::Process)
63//!     .system_provider(SystemProvider::Registry)
64//!     .system_provider(SystemProvider::Network)
65//!     .start()?;
66//! # Ok(())
67//! # }
68//! ```
69//!
70//! # User-Mode Providers
71//!
72//! You can subscribe to user-mode ETW providers directly by GUID:
73//!
74//! ```no_run
75//! # use windows::core::GUID;
76//! # use windows_erg::etw::EventTrace;
77//! # fn example() -> windows_erg::Result<()> {
78//! let provider = GUID::from_u128(0x3d6fa8d1_fe05_11d0_9dda_00c04fd7ba7c);
79//! let mut trace = EventTrace::builder("UserModeSession")
80//!     .user_provider(provider)
81//!     .start()?;
82//! # let _ = &mut trace;
83//! # Ok(())
84//! # }
85//! ```
86//!
87//! # Buffer Tuning
88//!
89//! High-volume providers (especially `FileIo`) benefit from larger buffers:
90//!
91//! ```no_run
92//! # use windows_erg::etw::{EventTrace, SystemProvider};
93//! # fn example() -> windows_erg::Result<()> {
94//! let trace = EventTrace::builder("FileMonitor")
95//!     .system_provider(SystemProvider::FileIo)
96//!     .buffer_size(256)       // 256 KB per buffer  (default: 64 KB)
97//!     .min_buffers(10)        // pre-allocate 10    (default: 2)
98//!     .max_buffers(50)        // cap at 50          (default: 20)
99//!     .channel_capacity(50_000)
100//!     .start()?;
101//! # Ok(())
102//! # }
103//! ```
104//!
105//! # Enrichment Features
106//!
107//! The following enrichment options are available on [`EventTraceBuilder`]:
108//!
109//! | Method | Effect |
110//! |--------|--------|
111//! | `with_stack_traces()` | Capture call stacks per event |
112//! | `with_thread_context()` | Include thread metadata in raw events |
113//! | `with_detailed_events()` | Schema-based field parsing of raw payloads |
114//! | `with_cpu_samples()` | Correlate CPU usage samples with the event stream |
115//!
116//! Already active:
117//! - `with_process_filter(pids)` filters events by PID in the callback path
118//!   before they are pushed to output channels.
119//! - `with_thread_context()` attaches `ThreadContext` to raw `TraceEvent` values.
120//! - `with_stack_traces()` parses ETW extended stack data into `StackTrace`.
121//! - `with_cpu_samples()` attaches processor-number metadata as `CpuSample`.
122
123mod decode;
124mod schema;
125mod session;
126mod types;
127
128pub use decode::{
129    DecodedEvent, EventField, EventFieldValue, FileIoEvent, FileIoOperation, ImageLoadEvent,
130    ImageUnloadEvent, ProcessEndEvent, ProcessStartEvent, RegistryEvent, RegistryOperation,
131    TcpEvent, TcpOperation,
132};
133pub use session::{EventStreamMode, EventTrace, EventTraceBuilder};
134pub use types::{CpuSample, StackTrace, SystemProvider, ThreadContext, TraceEvent, TraceLevel};
windows_erg/etw/mod.rs

windows_erg/etw/
mod.rs
