Debugging WSL

Logging

There are multiple sources of logging in WSL. The main one is the ETL trace that is emitted from Windows processes.

To collect an ETL trace, run (link to wsl.wprp):

wpr -start wsl.wprp -filemode

[reproduce the issue]

wpr -stop logs.ETL

The consolidated wsl.wprp file includes multiple profiles for different scenarios:

• WSL - General WSL tracing (default)
• WSL-Storage - Enhanced storage tracing
• WSL-Networking - Comprehensive networking tracing
• WSL-HvSocket - HvSocket-specific tracing

To use a specific profile, append !ProfileName to the wprp file, e.g., wpr -start wsl.wprp!WSL-Networking -filemode

Once the log file is saved, you can use WPA to view the logs.

Notable ETL providers:

• Microsoft.Windows.Lxss.Manager: Logs emitted from wslservice.exe Important events:

  • GuestLog: Logs from the vm's dmesg
  • Error: Unexpected errors
  • CreateVmBegin, CreateVmEnd: Virtual machine lifetime
  • CreateNetworkBegin, CreateNetworkEnd: Networking configuration
  • SentMessage, ReceivedMessage: Communication on the hvsocket channels with Linux.

• Microsoft.Windows.Subsystem.Lxss: Other WSL executables (wsl.exe, wslg.exe, wslconfig.exe, wslrelay.exe, ...) Important events:

  • UserVisibleError: An error was displayed to the user

• Microsoft.Windows.Plan9.Server: Logs from the Windows plan9 server (used when accessing /mnt/ shares and running Windows)

On the Linux side, the easiest way to access logs is to look at dmesg or use the debug console, which can be enabled by writing:

[wsl2]
debugConsole=true

to %USERPROFILE%/.wslconfig and restarting WSL

WSLg (graphical and audio applications) logs

WSLg runs graphical and audio Linux applications. It runs a system distro that hosts the weston Wayland compositor (with an RDP backend), Xwayland, pulseaudio, and FreeRDP. WSLg's source lives in a separate repository: microsoft/wslg.

WSLg writes its logs to /mnt/wslg (accessible from Windows via \\wsl$\<Distro>\mnt\wslg):

• weston.log - Weston compositor and RDP backend log
• wlog.log - FreeRDP log
• pulseaudio.log - PulseAudio log
• stderr.log - WSLGd and child-process stderr
• versions.txt - WSLg version and component git hashes

Crash dumps (e.g. core.weston) are written to %TEMP%\wsl-crashes on newer builds, or /mnt/wslg/dumps on older ones.

The collect-wsl-logs.ps1 script gathers the logs above automatically into a wslg/ folder (crash dumps are included when run with -Dump). Note that weston.log is truncated on every system-distro boot, so it only contains the most recent boot.

Attaching debuggers

Usermode can be attached to WSL Windows processes (wsl.exe, wslservice.exe, wslrelay.exe, ...). The symbols are available under the bin/<platform>/<target> folder. You can also use this trick to automatically collect crash dumps when processes crash.

Linux debugging

gdb can be attached to Linux processes (see man gdb).

The simplest way to debug a WSL process with gdb is to use the /mnt mountpoints to access the code from gdb. Once started, just use dir /path/to/wsl/source in gdb to connect the source files.

Root namespace debugging

Some WSL processes such as gns or mini_init aren't accessible from within WSL distributions. To attach a debugger to those, use the debug shell via:

wsl --debug-shell

You can then install gdb by running tdnf install gdb and start debugging processes.