DOCSEARCHbyAlgolia
Submit Docs

wtrace Documentation

repository·master·Indexed 20 days ago

https://github.com/lowleveldesign/wtrace

wtrace is a command-line tool for Windows 8.1+ and .NET 4.8.x that records low-level OS trace events, including File I/O, Registry operations, TCP/IP connections, and RPC calls. It allows users to trace system-wide events or target specific processes by PID or executable, featuring a flexible filtering system and configurable event handlers for deep insights into system and process behavior.

Tokens
1.2K
Snippets
6
Records
7
Agent score
22%

What's inside wtrace

  1. Trace a specific process or start a new one

    master

    wtrace can target an existing process by its PID or launch a new process and trace it.

    • By PID: If the first argument is a number, wtrace traces that PID. Use -c or --children to also trace all child processes launched by that PID.
    • By Executable: If the first argument is not a number, wtrace attempts to start that executable with the remaining arguments.

    Use -c or --children to include the process tree.

    # Trace File I/O operations of the process with id 1234 and its children
wtrace -f "name >= FileIO/" -c 1234

# Start and trace the opening of the test.txt file by notepad.exe
wtrace notepad c:\temp\test.txt

  2. Trace system-wide events

    master

    To trace all processes in the system, run wtrace with no arguments.

    Warning: System-wide tracing produces a high volume of events. To prevent event loss or high memory usage, it is highly recommended to:

    1. Use --handlers to limit the types of events collected.
    2. Use -f (filters) to narrow down the scope.
    3. Use --nosummary to disable statistics collection and minimize memory usage for long sessions.
    # show File write events from all the processes
wtrace --handlers file -f 'eventname=FileIO/Write'

# show RPC events from all the processes
wtrace --handlers rpc

# Trace system-wide with minimal memory usage
wtrace --nosummary

  3. Resolve RPC procedure names

    master

    To see human-readable RPC procedure names (e.g., [lsapolicylookup]) instead of just IDs, you must:

    1. Enable the image handler.
    2. Provide a symbol path via the --symbols parameter or set the _NT_SYMBOL_PATH environment variable.

    Example using the --symbols flag:

    wtrace.exe --symbols="SRV*C:\symbols\*https://msdl.microsoft.com/download/symbols" -v notepad.exe

  5. Troubleshoot wtrace errors

    master

    WARNING: the session did not finish in the allotted time.

    This indicates an issue with ETW session handling. The session might still be running. Stop it manually using logman:

    logman stop wtrace-rt -ets

    WARNING: … events were lost in the session.

    This means the event volume was too high for wtrace to process. To fix this:

    • Add more specific filters (-f).
    • Disable unneeded handlers (--handlers).

  6. Filter trace events with -f

    master

    Use the -f, --filter=FILTER option to display only events that satisfy a specific condition.

    Filter Syntax: keyword operator value

    Keywords:

    • pid: Process ID
    • pname: Process name
    • name: Event name
    • level: Event level (1 [critical] to 5 [debug])
    • path: Event path
    • details: Event details

    Operators:

    • =: Equals
    • <>: Does not equal
    • <=: Ends with (text) or Less than or equal (numeric)
    • >=: Starts with (text) or Greater than or equal (numeric)
    • ~: Contains (text)

    Logic:

    • Filters with the same keyword are OR-ed together.
    • Filters with different keywords are AND-ed together.
    • Text filters are case-insensitive.
    # Trace system-wide and filter events for processes named notepad OR notepad2 AND path starts with d:\temp
wtrace -f "pname = notepad" -f "pname = notepad2" -f "path >= d:\temp"

# Trace a process with id 12572 and its children and show only TCP/IP events
wtrace -f "name >= tcp" -c 12572

  7. Configure event handlers with --handlers

    master

    The --handlers=HANDLERS option specifies which event types to collect. If a handler is not specified, its events will not appear in the live output or the summary.

    Available Handlers:

    • process: Process/Thread events (always enabled by default)
    • file: File I/O events
    • registry: Registry events (voluminous, disabled by default)
    • rpc: RPC events (requires image handler for name resolution)
    • tcp: TCP/IP events
    • udp: UDP events
    • image: Module (load/unload) events

    Note: The registry handler can generate > 1000 events/s; use with caution.

    # Trace only registry and tcp events system-wide
wtrace --handlers registry,tcp