Collecting and Reading WSL Diagnostic Logs with ETW and WPA

“WSL is broken” can refer to a Linux program, the distribution’s own startup configuration, the WSL service, the utility VM, Windows networking, or a host driver. These layers produce different evidence. A Linux journalctl excerpt cannot explain a Windows service failure that occurs before the guest starts, and a Windows ETW trace does not replace a Linux application’s own logs. Collect the smallest trace that captures a repeatable failure, record the versions and timeline, and preserve the original artifacts before trying disruptive repairs.

This guide is an evidence-collection workflow, not a fix for every startup problem. For an ordinary distro boot failure, first use the focused recovery procedure for safe mode/debug shell; for detailed WSL platform problems, Microsoft maintains a diagnostic collector in the WSL repository. Avoid unregistering a distribution or rebuilding its virtual disk as a “diagnostic step”: those actions can destroy or alter the state you need to understand.

Separate the evidence by layer

Begin by writing down the operation that failed, the exact local time and time zone, the expected result, the observed result, and whether the issue affects one distro or all of them. Note whether it happens after a cold Windows start, after sleep, only on a VPN, or only after a specific package/service starts. These distinctions help correlate guest-side logs with host-side events.

From PowerShell, record WSL’s reported component versions and registered distros:

wsl.exe --version
wsl.exe --status
wsl.exe --list --verbose
Get-CimInstance Win32_OperatingSystem |
  Select-Object Caption, Version, BuildNumber

If WSL never starts, do not claim that a Linux log is missing because the guest is healthy or unhealthy; the distro might not have booted far enough to generate one. Record the exact wsl.exe command and full error text instead. If a different distro works, note that comparison, but treat it as useful narrowing evidence, not proof that every shared WSL component is fault-free.

Inside a distro that does start, capture its identity and guest logs separately:

uname -a
cat /etc/os-release
date --iso-8601=seconds

On a systemd-enabled distro, add:

systemctl --failed --no-pager
journalctl -b -p warning --no-pager

For a kernel, filesystem, or device symptom, include a bounded dmesg excerpt relevant to the reproduction rather than an unfiltered dump. For an individual Linux process failure, capture its program version, command line with sensitive arguments removed, exit status, and application-specific logs; Microsoft recommends reproducing Linux userspace issues on Linux and using tools such as strace when the failing binary or system call is the likely layer.

Use the maintained WSL collector for platform traces

The recommended WSL platform collection script is maintained in Microsoft’s microsoft/WSL repository. It uses Windows Performance Recorder (WPR) and gathers multiple host and WSL artifacts. Run it only when an issue is reproducible enough to capture, and use an administrative PowerShell prompt as directed by the upstream WSL contributor guide. The simplest invocation is:

$work = Join-Path $env:TEMP 'WslDiagnostics'
New-Item -ItemType Directory -Path $work -Force | Out-Null
Set-Location $work
Invoke-WebRequest `
  -Uri 'https://raw.githubusercontent.com/microsoft/WSL/master/diagnostics/collect-wsl-logs.ps1' `
  -UseBasicParsing `
  -ErrorAction Stop `
  -OutFile '.\collect-wsl-logs.ps1'
Get-FileHash -LiteralPath '.\collect-wsl-logs.ps1' -Algorithm SHA256

The WSL contributor guide uses -UseBasicParsing for this download and directs collection from an administrative PowerShell prompt. Because this URL follows the repository’s moving master branch, inspect the downloaded script and follow your organization’s software execution policy before running it. The SHA-256 output records which bytes were reviewed; it is not an independent authenticity check. Only after reviewing and approving the script, use the required elevated prompt and apply a process-scoped execution policy if permitted:

Set-ExecutionPolicy -Scope Process Bypass -Force
.\collect-wsl-logs.ps1

That temporary policy change applies only to the PowerShell process; it is not a substitute for approval on a managed machine. The official collector may require Windows Performance Recorder tooling and elevation. Follow its current prompts, reproduce the issue only after collection is active, then stop the trace as requested and note the output archive path.

For a networking-only reproduction, use the collector’s networking profile rather than enabling every trace by default:

.\collect-wsl-logs.ps1 -LogProfile networking

The WSL project documents other profiles, including storage and Hyper-V socket tracing, and a restart/reproduction mode for certain network-creation failures. Select a profile based on the observed layer and consult the current upstream instructions: trace names and script options may evolve. Do not assume that an arbitrary profile name copied from an old blog post still exists in the installed script.

Read WSL ETW events with Windows Performance Analyzer

The collector produces an archive containing logs.etl among its artifacts. Microsoft’s troubleshooting guide describes opening that ETL in Windows Performance Analyzer (WPA), expanding System Activity, adding Generic Events, and selecting the Microsoft.Windows.Lxss.Manager event series. The VerboseLog events can reveal WSL-side detail around a failure that is not visible in the distro’s own journal.

Treat the ETL as a timeline, not a text log. Filter around the reproduction timestamp, compare the event sequence before and after the failure, and correlate it with the exact PowerShell command and guest timestamps. If you see no relevant provider or event, confirm the collector actually started and that the issue occurred while the trace was active; an empty view does not prove that WSL emitted no diagnostic events. Windows Performance Analyzer is part of the Windows Performance Toolkit; install it from Microsoft’s supported Windows ADK distribution when it is not already available.

For a stuck WSL VM or process crash, Microsoft’s guide also documents creating a memory dump for VmmemWSL through Task Manager. A dump is much larger and more sensitive than a text log, and is not the first choice for a merely slow command. Capture one only when the failure warrants it and use the support channel’s approved handling process.

Make a reproduction useful to another engineer

The log bundle is only as useful as the conditions attached to it. Include a short report alongside your own issue with:

Windows edition/build, WSL component version, kernel version, distro name/version, and whether it is WSL 1 or WSL 2.
The single shortest command sequence that reproduces the issue, including expected and actual results.
Approximate local timestamp and time zone for each attempt, plus whether WSL was cold, recently shut down, resumed from sleep, or connected to VPN.
Whether it affects one distro, a second distro, Windows-native applications, or a comparable virtual machine.
The diagnostic profile used, when collection started/stopped, collector output path, and whether any trace command failed.
Relevant distro logs and application versions, clearly labeled as guest evidence rather than host evidence.

Prefer one controlled reproduction over repeated changes between runs. If the symptom requires a particular networking mode, fstab entry, or systemd service, save the exact configuration with secrets removed. After a change, record it as a new test rather than combining before-and-after behavior in one unlabeled trace.

Protect and preserve the evidence

Diagnostic bundles and memory dumps can contain usernames, filesystem paths, network endpoints, process details, and other machine-specific information. Treat them as support artifacts, store them in an approved location, and inspect/redact material before posting publicly. Do not edit the original archive; create a separate redacted copy if the support channel permits it. Keep hashes or a read-only copy if evidence integrity matters to your workflow.

Avoid attaching a full networking trace to a general question when a short getent, route, or service log already isolates the cause. The WSL networking profile may include packet-level and Windows Filtering Platform diagnostics, so use it only for an issue that needs that visibility. Conversely, do not expect a short distro journalctl excerpt to capture a host-side routing, VM creation, or WSL service failure. Match the cost and scope of collection to the failure layer.

Close the loop without destroying state

Before testing a repair, preserve the initial error, version inventory, relevant config, and original log archive. Then make one narrow change, reproduce the same command under comparable conditions, and collect a second trace only if it adds evidence. A valid fix should change the expected symptom without introducing a new failure in unrelated distros or host networking.

For an actionable upstream report, search the WSL repository for the same error and Windows/WSL version, follow its current issue template, provide concise reproduction steps, and attach logs through the official channel. Never upload another person’s logs or a corporate network trace without authorization. If evidence points to a Linux distribution package or userspace binary rather than WSL itself, direct the report to that distro or application’s maintainers instead of treating every Linux error as a WSL platform defect.

Completion checklist

A diagnostic capture is complete when the failure can be tied to a precise layer and timestamp; the Windows and guest version inventory is recorded; the selected trace profile covers the reproduction; the ETL/archive opens or its collection failure is documented; sensitive data is handled appropriately; and the next action is based on evidence rather than an irreversible reset. Keep the initial and post-fix results distinguishable so a later reviewer can verify what changed.

Related:

Sources: