Collect WSLg logs in collect-wsl-logs.ps1#40913
Open
benhillis wants to merge 4 commits into
Open
Conversation
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>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR extends WSL’s standard diagnostics collection to include WSLg (GUI/audio) logs and crash dumps, and adds documentation to help contributors interpret those logs and understand when issues should be routed to the separate microsoft/wslg repository.
Changes:
- Collect
/mnt/wslglogs into awslg/subfolder incollect-wsl-logs.ps1, plus host-side WSLg crash dumps from%TEMP%\wsl-crashes. - Add a WSLg log analysis guide under
.github/copilot/and link it from Copilot instructions. - Update contributor and debugging docs to describe WSLg log locations and the new collection behavior.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
diagnostics/collect-wsl-logs.ps1 |
Adds best-effort WSLg log + crash dump collection into the archive. |
doc/docs/debugging.md |
Documents WSLg log locations and notes they’re auto-collected by the script. |
CONTRIBUTING.md |
Notes that standard log collection includes WSLg logs/dumps for GUI/audio issues. |
.github/copilot/wslg-logs.md |
New guide describing WSLg architecture, log files, and common signatures. |
.github/copilot-instructions.md |
Links to the WSLg guide and summarizes what the collection script gathers. |
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>
benhillis
commented
Jun 25, 2026
OneBlue
reviewed
Jun 25, 2026
- 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>
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>
OneBlue
reviewed
Jun 26, 2026
| param($DestFull, $CollectDumps) | ||
|
|
||
| $destWsl = & wsl.exe --system --user root -e wslpath -u "$DestFull" 2>$null | ||
| if ([string]::IsNullOrWhiteSpace($destWsl)) { return } |
Collaborator
There was a problem hiding this comment.
nit: We should probably swap and do the Trim() before the null check
| $destWsl = $destWsl.Trim() | ||
|
|
||
| # Destination is passed as $1 so paths containing a single quote are handled safely. | ||
| & wsl.exe --system --user root -e sh -c 'cp /mnt/wslg/pulseaudio.log /mnt/wslg/weston.log /mnt/wslg/wlog.log /mnt/wslg/stderr.log /mnt/wslg/versions.txt "$1/" 2>/dev/null; exit 0' sh "$destWsl" |
Collaborator
There was a problem hiding this comment.
I'm a bit confused by this, what does the sh "$destWsl" do at the end ?
Collaborator
There was a problem hiding this comment.
Is this an edit error maybe ?
| } | ||
| } -ArgumentList (Resolve-Path $wslgFolder).Path, ([bool]$Dump) | ||
|
|
||
| if (Wait-Job $wslgJob -Timeout 60) |
Collaborator
There was a problem hiding this comment.
60 seconds feels like a lot for this, I'd recommend something like maybe 20 seconds
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds WSLg (graphical and audio application) log collection to
collect-wsl-logs.ps1, so a standard WSL log collection also captures what's needed to diagnose WSLg issues, and documents how to read those logs.Changes
diagnostics/collect-wsl-logs.ps1: collect WSLg logs into awslg/folder of the archive:weston.log,pulseaudio.log,wlog.log,stderr.log,versions.txtfrom/mnt/wslg.wsl.exe --system --user root, which reaches/mnt/wslgeven when the default distro is WSL1 or isn't running, and can read root-only logs likepulseaudio.log. The destination is passed toshas$1, so paths containing a single quote are handled safely./mnt/wslg/dumpsand host%TEMP%\wsl-crashes, e.g.core.weston) are collected only when-Dumpis passed, since users may not expect dumps to be published by default..github/copilot/wslg-logs.md(new): a log-analysis guide covering the WSLg architecture, the file layout, and common log signatures (system-distro cycling,glamorto software-rendering fallback, RDP audio sink, FontMonitor), with references to the microsoft/wslg repo..github/copilot-instructions.md: Log Analysis Tools now points to the WSLg guide and notes WSLg code lives in microsoft/wslg.CONTRIBUTING.md: note that the same script covers graphical-app (WSLg) issues.doc/docs/debugging.md: new "WSLg logs" section with the file list, dump locations, and microsoft/wslg references.Testing
collect-wsl-logs.ps1end to end and confirmed thewslg/folder is present and populated in the resulting archive.--system --user rootreads the root-owned0600pulseaudio.logand copies all logs to the host folder.-Dumpgates crash-dump collection.collect-wsl-logs.ps1parses;mkdocs buildsucceeds.