mirror of https://github.com/microsoft/WSL.git synced 2026-04-10 07:50:53 -05:00

Files

Ben Hillis 8c220dc083 Fix grammar, typos, and formatting in docs and source (#14286 )

* Fix localization text, Intune capitalization, ADMX indentation, unused import

- distributions/validate.py: Remove unused 'import base64'
- en-US/en-GB Resources.resw: Fix word order 'the list distribution' -> 'the distribution list' in MessageCouldFetchDistributionList
- en-US/en-GB Resources.resw: Remove trailing space from MessageCorruptedDistroRegistration value
- intune/en-US/WSL.adml: Fix 'For Linux' -> 'for Linux' capitalization (5 occurrences) to match official product name
- intune/WSL.admx: Fix inconsistent 3-space indent to 4-space on AllowWSL1 and CustomKernelUserSettingConfigurable policies

* Fix grammar, typos, and formatting in docs and source code

- WmiService.h: Fix duplicated word 'of of' -> 'is of' in WQL comment
- drvfs.md: Fix 'which tell' -> 'which tells' (subject-verb agreement), double space, second 'tell' -> 'tells'
- systemd.md: Fix 'tries synchronizes' -> 'tries to synchronize'
- wslhost.exe.md: Fix 'processes terminates' -> 'process terminates'
- boot-process.md: Add missing 'in' preposition, fix C:/ -> C:\, fix lowercase 'linux' to 'Linux' (4 occurrences), fix misplaced parenthesis
- init.md: Fix double space before hvsocket backtick
- session-leader.md: Fix heading level ## -> ### to match sibling section
- CONTRIBUTING.md: Fix double period after bold security notice
- debugging.md: Fix missing word 'be' in 'can enabled', fix 'process' -> 'processes'
- index.md: Add missing period at end of sentence
- technical-documentation/index.md: Fix 'API's' -> 'APIs' (remove incorrect apostrophe)
- relay.md: Fix lowercase 'linux' to 'Linux' (3 occurrences)
- localhost.md: Fix lowercase 'linux' to 'Linux'
- plan9.md: Fix lowercase 'linux' to 'Linux'

* update errormessages testcase

---------

Co-authored-by: Ben Hillis <benhill@ntdev.microsoft.com>

2026-03-03 18:13:59 -08:00

2.8 KiB

Raw Blame History

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

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.

2.8 KiB Raw Blame History