mirror of
https://github.com/microsoft/WSL.git
synced 2026-04-11 10:52:42 -05:00
8c220dc083
* 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>
74 lines
2.8 KiB
Markdown
74 lines
2.8 KiB
Markdown
# 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](https://github.com/microsoft/WSL/blob/master/diagnostics/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](https://apps.microsoft.com/detail/9n58qrw40dfw?hl=en-US&gl=US) 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](https://github.com/microsoft/WSL/blob/master/CONTRIBUTING.md#11-reporting-a-wsl-process-crash) to automatically collect crash dumps when processes crash.
|
|
|
|
## Linux debugging
|
|
|
|
`gdb` can be attached to Linux processes (see [man gdb](https://man7.org/linux/man-pages/man1/gdb.1.html)).
|
|
|
|
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. |