mirror of
https://github.com/aphrody-labs/WSL.git
synced 2026-10-14 21:59:15 +00:00
95cdd1cf31
* Collect WSLg logs in collect-wsl-logs.ps1 Gather WSLg graphical/audio logs into a wslg/ folder of the log archive: weston.log, pulseaudio.log, wlog.log, stderr.log and versions.txt from /mnt/wslg, plus crash dumps from %TEMP%\wsl-crashes (and legacy /mnt/wslg/dumps). Logs are copied inside WSL as the uid=0 user so binary dumps are preserved and root-only logs like pulseaudio.log are readable. Document WSLg log collection and analysis in CONTRIBUTING.md, doc/docs/debugging.md, and a new .github/copilot/wslg-logs.md guide, including references to the microsoft/wslg repository. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Pass WSLg dest path as sh argument to handle quotes safely Addresses PR review: a destination path containing a single quote (e.g. C:\Users\O'Connor\...) would break the single-quoted sh -c string. Pass the path as $1 and reference it via "$1" inside the script instead. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address review: timeout, --system, and gate WSLg dumps behind -Dump - Collect WSLg logs inside a background job with a 60s timeout so a wedged WSL service cannot hang log collection. - Use wsl.exe --system to reach /mnt/wslg, which works even when the default distro is WSL1 or is not running, and runs as the wslg user that owns the logs (removes the id -nu 0 super-user detection). - Only collect WSLg crash dumps (/mnt/wslg/dumps and %TEMP%\wsl-crashes) when -Dump is passed, since users may not expect dumps by default. Docs updated accordingly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Use --system --user root for WSLg log collection Run the WSLg collection as root in the system distro so root-owned logs are guaranteed readable, removing ambiguity about required privileges. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * collect-wsl-logs: address WSLg review feedback - Trim wslpath output before the null/whitespace check - Explain the sh -c arg0/\ idiom used to pass the destination safely - Lower the WSLg collection timeout from 60s to 20s Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * collect-wsl-logs: use New-Item -Force for the wslg folder instead of mkdir -p Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Ben Hillis <benhill@ntdev.microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
99 lines
3.9 KiB
Markdown
99 lines
3.9 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
|
|
|
|
|
|
## WSLg (graphical and audio applications) logs
|
|
|
|
[WSLg](https://github.com/microsoft/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](https://github.com/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](https://github.com/microsoft/WSL/blob/master/diagnostics/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](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. |