0 Fork 0

mirror of https://github.com/aphrody-labs/WSL.git synced 2026-10-14 13:49:03 +00:00

Files

T

95cdd1cf31 Collect WSLg logs and crash dumps in collect-wsl-logs.ps1 (#40913 )

* 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>

2026-07-09 09:34:00 -07:00

3.9 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

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.

3.9 KiB Raw Blame History