| 1 | # Debugging WSL |
| 2 | |
| 3 | ## Logging |
| 4 | |
| 5 | There are multiple sources of logging in WSL. The main one is the ETL trace that is emitted from Windows processes. |
| 6 | |
| 7 | To collect an ETL trace, run ([link to wsl.wprp](https://github.com/microsoft/WSL/blob/master/diagnostics/wsl.wprp)): |
| 8 | |
| 9 | ``` |
| 10 | wpr -start wsl.wprp -filemode |
| 11 | |
| 12 | [reproduce the issue] |
| 13 | |
| 14 | wpr -stop logs.ETL |
| 15 | ``` |
| 16 | |
| 17 | The consolidated `wsl.wprp` file includes multiple profiles for different scenarios: |
| 18 | |
| 19 | - `WSL` - General WSL tracing (default) |
| 20 | - `WSL-Storage` - Enhanced storage tracing |
| 21 | - `WSL-Networking` - Comprehensive networking tracing |
| 22 | - `WSL-HvSocket` - HvSocket-specific tracing |
| 23 | |
| 24 | To use a specific profile, append `!ProfileName` to the wprp file, e.g., `wpr -start wsl.wprp!WSL-Networking -filemode` |
| 25 | |
| 26 | 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. |
| 27 | |
| 28 | Notable ETL providers: |
| 29 | |
| 30 | - `Microsoft.Windows.Lxss.Manager`: Logs emitted from wslservice.exe |
| 31 | Important events: |
| 32 | - `GuestLog`: Logs from the vm's dmesg |
| 33 | - `Error`: Unexpected errors |
| 34 | - `CreateVmBegin`, `CreateVmEnd`: Virtual machine lifetime |
| 35 | - `CreateNetworkBegin`, `CreateNetworkEnd`: Networking configuration |
| 36 | - `SentMessage`, `ReceivedMessage`: Communication on the hvsocket channels with Linux. |
| 37 | |
| 38 | - `Microsoft.Windows.Subsystem.Lxss`: Other WSL executables (wsl.exe, wslg.exe, wslconfig.exe, wslrelay.exe, ...) |
| 39 | Important events: |
| 40 | - `UserVisibleError`: An error was displayed to the user |
| 41 | |
| 42 | - `Microsoft.Windows.Plan9.Server`: Logs from the Windows plan9 server (used when accessing /mnt/ shares and running Windows) |
| 43 | |
| 44 | |
| 45 | 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: |
| 46 | |
| 47 | ``` |
| 48 | [wsl2] |
| 49 | debugConsole=true |
| 50 | ``` |
| 51 | |
| 52 | to `%USERPROFILE%/.wslconfig` and restarting WSL |
| 53 | |
| 54 | |
| 55 | ## WSLg (graphical and audio applications) logs |
| 56 | |
| 57 | [WSLg](https://github.com/microsoft/wslg) runs graphical and audio Linux applications. It runs a |
| 58 | system distro that hosts the `weston` Wayland compositor (with an RDP backend), `Xwayland`, |
| 59 | `pulseaudio`, and `FreeRDP`. WSLg's source lives in a separate repository: |
| 60 | [microsoft/wslg](https://github.com/microsoft/wslg). |
| 61 | |
| 62 | WSLg writes its logs to `/mnt/wslg` (accessible from Windows via `\\wsl$\<Distro>\mnt\wslg`): |
| 63 | |
| 64 | - `weston.log` - Weston compositor and RDP backend log |
| 65 | - `wlog.log` - FreeRDP log |
| 66 | - `pulseaudio.log` - PulseAudio log |
| 67 | - `stderr.log` - `WSLGd` and child-process stderr |
| 68 | - `versions.txt` - WSLg version and component git hashes |
| 69 | |
| 70 | Crash dumps (e.g. `core.weston`) are written to `%TEMP%\wsl-crashes` on newer builds, or |
| 71 | `/mnt/wslg/dumps` on older ones. |
| 72 | |
| 73 | The [collect-wsl-logs.ps1](https://github.com/microsoft/WSL/blob/master/diagnostics/collect-wsl-logs.ps1) |
| 74 | script gathers the logs above automatically into a `wslg/` folder (crash dumps are included when run |
| 75 | with `-Dump`). Note that `weston.log` is truncated on every system-distro boot, so it only contains |
| 76 | the most recent boot. |
| 77 | |
| 78 | |
| 79 | ## Attaching debuggers |
| 80 | |
| 81 | Usermode can be attached to WSL Windows processes (wsl.exe, wslservice.exe, wslrelay.exe, ...). The symbols are available under the `bin/<platform>/<target>` folder. |
| 82 | 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. |
| 83 | |
| 84 | ## Linux debugging |
| 85 | |
| 86 | `gdb` can be attached to Linux processes (see [man gdb](https://man7.org/linux/man-pages/man1/gdb.1.html)). |
| 87 | |
| 88 | The simplest way to debug a WSL process with gdb is to use the `/mnt` mountpoints to access the code from gdb. |
| 89 | Once started, just use `dir /path/to/wsl/source` in gdb to connect the source files. |
| 90 | |
| 91 | ## Root namespace debugging |
| 92 | |
| 93 | 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: |
| 94 | |
| 95 | ``` |
| 96 | wsl --debug-shell |
| 97 | ``` |
| 98 | |
| 99 | You can then install `gdb` by running `tdnf install gdb` and start debugging processes. |