| 1 | # Analyzing WSLg logs |
| 2 | |
| 3 | WSLg is the component that runs graphical (GUI) and audio Linux applications on WSL. Its |
| 4 | source lives in a separate repository: https://github.com/microsoft/wslg. The canonical list |
| 5 | of diagnostics to request for a WSLg bug is the WSLg repo bug report template |
| 6 | (`.github/ISSUE_TEMPLATE/bug_report.yml` in microsoft/wslg). |
| 7 | |
| 8 | `diagnostics/collect-wsl-logs.ps1` collects the logs into a `wslg/` subfolder of the log archive |
| 9 | (via `wsl.exe --system --user root`, with a timeout so a wedged service can't hang collection), so a |
| 10 | standard WSL log collection already contains the log files below. Crash dumps (`dumps/`, |
| 11 | `wsl-crashes/`) are only collected when the script is run with `-Dump`. |
| 12 | |
| 13 | ## Architecture (just enough to read the logs) |
| 14 | |
| 15 | WSLg runs a **system distro** (a small Azure Linux VM, separate from the user distro) that hosts: |
| 16 | - **weston** (Wayland compositor) with the `rdp-backend.so` / `rdprail-shell.so` modules |
| 17 | - **Xwayland** for X11 apps |
| 18 | - **pulseaudio** with an RDP sink/source for audio |
| 19 | - **FreeRDP** to stream the surfaces over an hvsocket to the Windows RDP client (`msrdc.exe`) |
| 20 | |
| 21 | `weston.log` and `wlog.log` are written by weston/FreeRDP, `pulseaudio.log` by pulseaudio, and |
| 22 | `stderr.log` is the combined stderr of `WSLGd` and the processes it launches. |
| 23 | |
| 24 | ## Files (in the `wslg/` folder, sourced from `/mnt/wslg`) |
| 25 | |
| 26 | | File | Contents | |
| 27 | |---|---| |
| 28 | | `versions.txt` | WSLg version, architecture, build date, component git hashes (weston, FreeRDP, mesa, pulseaudio) | |
| 29 | | `weston.log` | Weston compositor + RDP backend log | |
| 30 | | `wlog.log` | FreeRDP (WLog) log | |
| 31 | | `pulseaudio.log` | PulseAudio log | |
| 32 | | `stderr.log` | `WSLGd` and child-process stderr | |
| 33 | | `dumps/` | Legacy WSLg crash dumps (older builds only; collected with `-Dump`) | |
| 34 | | `wsl-crashes/` | Host-side WSLg crash dumps copied from `%TEMP%\wsl-crashes` (newer builds, e.g. `core.weston`; collected with `-Dump`) | |
| 35 | |
| 36 | ## Reading tips and common signatures |
| 37 | |
| 38 | - **`weston.log` is truncated on every boot.** Weston is started with `--log=/mnt/wslg/weston.log` |
| 39 | and opens it truncating, so the file only ever contains the **latest** system-distro boot. To |
| 40 | tell whether weston restarted, compare the boot timestamp on the first line (`weston 9.0.0 ...`) |
| 41 | across snapshots, or correlate with `dmesg`. |
| 42 | |
| 43 | - **System distro cycling / teardown.** In `dmesg` (collected via the ETL `GuestLog` events or |
| 44 | the debug console), this pair means the WSLg system distro's `init` exited and the distro was |
| 45 | torn down (idle timeout or shutdown), which also restarts weston: |
| 46 | ``` |
| 47 | Exception: Operation canceled @p9io.cpp:258 (AcceptAsync) |
| 48 | WSL (1 - init()) ERROR: InitEntryUtilityVm:2551: Init has exited. Terminating distribution |
| 49 | ``` |
| 50 | Repeating every ~25-60s with no GUI client attached is usually normal idle teardown, not a crash. |
| 51 | A genuine weston crash instead leaves a core dump in `wsl-crashes/` (or `dumps/`). |
| 52 | |
| 53 | - **No GPU acceleration (software rendering).** This means the virtual GPU (`/dev/dxg`, d3d12 mesa) |
| 54 | is not usable, so rendering falls back to CPU: |
| 55 | ``` |
| 56 | Xwayland glamor: GBM Wayland interfaces not available |
| 57 | Failed to initialize glamor, falling back to sw |
| 58 | ``` |
| 59 | Investigate GPU driver presence, `/dev/dxg`, and the `mesa`/`d3d12` stack if the user reports |
| 60 | black windows, slow rendering, or missing 3D. |
| 61 | |
| 62 | - **Audio sink not connected (usually benign at boot).** Expected until an RDP/audio client attaches: |
| 63 | ``` |
| 64 | [rdp-sink] RDP Sink - Trying to connect to /mnt/wslg/PulseAudioRDPSink |
| 65 | [rdp-sink] Connected failed |
| 66 | ``` |
| 67 | If it persists while audio is actively broken, look at the RDP client (`msrdc`) audio channel. |
| 68 | |
| 69 | - **Mostly-benign startup noise** (not a root cause on its own): |
| 70 | - `WSLGd: Exception: No such file or directory @FontMonitor.cpp:280` - font share not mounted. |
| 71 | - `XDG_RUNTIME_DIR "/mnt/wslg/runtime-dir" ... mode 040777` (should be 0700) - common warning. |
| 72 | - `dbus: Unknown username "pulse"` / `Option "-listen" is deprecated` - harmless. |
| 73 | |
| 74 | ## When to escalate to the WSLg repo |
| 75 | |
| 76 | WSLg code is not in this repository. Fixes to weston, FreeRDP, pulseaudio, or the RDP backend |
| 77 | belong in https://github.com/microsoft/wslg. Use a commit-pinned permalink when referencing files |
| 78 | there so the link does not drift, e.g. |
| 79 | `https://github.com/microsoft/wslg/blob/<commit-sha>/<path>`. |