Fingerprint translation-stack crashes in game_exited

Closed
UT
13d ago
+697-1

Description

Adds a compact crash fingerprint to game_exited so the server can cluster crashes per game and component version.

Capture. In a normal launch nothing from the guest is kept: WINEDEBUG=-all, DXVK_LOG_LEVEL=none, MESA_DEBUG=silent, and the always-registered debug callback in setupXEnvironment reads guest stdout/stderr line by line but only writes them to a file on debug runs or with Wine/Box64 logging enabled. That callback now also appends each line to GuestOutputTail, an in-memory ring capped at 256 KB (lines capped at 4 KB). There is no new thread, file or log during play, just one bounded append in a callback that already runs for every line.

Fingerprint. CrashFingerprint.extract(tail, exitReason, componentVersions) is pure. It matches:

  • wine: wine: Unhandled ..., winedbg Unhandled exception: ... in NN-bit code, Exception code, the top 3 Backtrace frames as module!symbol+0xoff or module+0xoff, Call from ... to unimplemented function, err:module:import_dll / other err:module failures, and wineserver loss
  • FEX: unknown or unhandled instruction (with the bytes), unhandled syscall, signals
  • Box64: Unimplemented Opcode, Unsupported Syscall, dynarec errors
  • Mesa/Turnip: Assertion ... failed, VK_ERROR_DEVICE_LOST / GPU hang, MESA: error
  • DXVK: err: and DxvkError
  • vkd3d-proton: err:d3d12_* / err:vkd3d*

The highest-priority match wins. Instruction faults beat asserts, which beat device loss, then exceptions, unimplemented functions, load failures, syscalls and plain err: lines. A crash in a module that is not a known wine, DXVK, vkd3d, FEX or Mesa module is attributed to game.

Shape: {component, kind, code, module, frames[≤3], sample[≤5 lines ≤200 chars], hash, versions}. Hex runs of 6 or more digits become 0x…, and wine/box64 thread and pid prefixes are stripped. hash is the first 16 hex of sha256(component|kind|code|module|frames). The serialized size is capped at 2 KB. It returns null when nothing matched and the exit was not guest_terminated. A guest_terminated exit with no match gives component=none, kind=other.

Wiring. game_exited and recordRun are sent from the same place and thread as on master. In exit(), the props get crash_fingerprint (map) and crash_fingerprint_hash, extracted from the in-memory tail. Extraction runs on Dispatchers.IO and exit() waits for it for at most 200 ms; on timeout or any failure it adds nothing (catch-all, logged with Timber). For a guest_terminated exit the tail is complete by then; a user-initiated exit has nothing to find. versions carries wine, emulator, fexcore, box64, graphics driver + version, and dxwrapper + version from the container. The fingerprint is also stored in .gamenative/runs/*.json, so the next launch can read it. It is pipeline diagnostics and follows the same gating as game_exited, nothing more.

Not built locally; CI compiles and runs CrashFingerprintTest.

Recording

Not applicable (telemetry only).

Type of Change

  • Bug fix
  • Performance / stability improvement
  • Compatibility improvements
  • Other (requires prior approval)

Checklist

  • If I have access to #code-changes, I have discussed this change there and it has been green-lighted. If I do not have access, I have still provided clear context in this PR. If I skip both, I accept that this change may face delays in review, may not be reviewed at all, or may be closed.
  • This change aligns with the current project scope (core functionality, stability, or performance). If not, it has been explicitly approved beforehand.
  • I have attached a recording of the change.
  • I have read and agree to the contribution guidelines in CONTRIBUTING.md.

Summary by cubic

Adds a compact crash fingerprint to game_exited so crashes can be clustered per game and component version.

  • Keeps the last 256 KB of guest stdout/stderr in a bounded in-memory ring appended by the existing debug callback; no new thread, file, or log during play.
  • A pure matcher detects Wine, FEX, Box64, Mesa/Turnip, DXVK, and vkd3d-proton crash patterns and produces component, kind, code, module, up to 3 backtrace frames, and a 5-line sample capped at 200 chars each.
  • Thread IDs, PIDs, and long hex runs are normalized so identical crashes hash the same.
  • The fingerprint is extracted in exit() with a 200 ms timeout, sent with game_exited from the same place as before, and stored in .gamenative/runs/*.json for the next launch.
  • Normal exits yield no fingerprint; a guest_terminated exit without a match yields component=none, kind=other.

Summary by CodeRabbit

  • New Features
    • Session reports can now include a structured crash fingerprint for recognized failures, with details such as the affected component, error type, and relevant software versions.
    • Fingerprints include a concise log sample and a stable identifier to help distinguish failure patterns. For clean or unrecognized logs, reports omit the fingerprint unless the guest process has terminated.