Skip to content

13 logging and debug

github-actions[bot] edited this page Nov 21, 2026 · 7 revisions

13 — Logging & Debug

Serilog setup, sinks, the Debug Window, and bug-reporting. Related: 04 — Architecture · 08 — UI Layer

Serilog bootstrap

Serilog 4.4.0 (+ Serilog.Sinks.Async 2.1.0, Serilog.Sinks.Debug 3.0.0, Serilog.Sinks.File 7.0.0) is configured in App.OnStartup (App.xaml.cs:117-137):

  • File sink: rolling daily file in the local app-data folder (%LocalAppData%\SimpleLauncher\error_user.log by default, or LogPath override), 7 days retained.
  • DebugWindowSink: pushes log events to the live Debug Window (buffered; flushed when the window connects).
  • BugReportApiSink: queues events for the bug-report API (see below).
  • Fallback: if Serilog initialization fails, the app falls back to debug output instead of crashing.

ILogger (Serilog) is injected everywhere — Core and app projects both have a global using Serilog; (see 02 — Projects & Solution).

Debug Window

  • DebugWindow (app): singleton live log viewer; closing hides the window instead of destroying it; logging continues; reopening flushes the buffered history.
  • Launched via the tray menu / Help menu, or automatically with the -debug command-line flag (opens alongside the main window).
  • The legacy IDebugLogger/NoOpDebugLogger abstraction was removed. All logging now goes through Serilog ILogger/Log.Logger.

Bug report pipeline

BugReportApiSink (SimpleLauncher.Core\Services\DebugAndBugReport\BugReportApiSink.cs):

  1. Every Warning-or-higher Serilog event is queued (bounded, ~100-cap) and submitted to the bug-report API.
  2. On success: queued logs are deleted.
  3. On failure: critical_error.log (or error.log / error_user.log) is written locally with environment details.
  4. Reports always include Date, Application Name, Application Version, OS Version, Architecture, Bitness, Windows, Linux or MacOsX Version (resolved by OperatingSystemDetails on all three platforms), Processor Count, Base Directory, Temp Path, then the error and the full inner-exception chain. Payloads are truncated client-side to the API limits (4,000 chars for message, 8,000 for stackTrace) with a visible marker.
  5. The updater uses the same Serilog-only pipeline; its former BugReportService (a second, independent reporter) was removed.

The Support Window (SupportWindow + SupportViewModel) is the user-facing entry point: name/email/message validation, "Sending support request…" overlay, POST to the support API, and an emergency return button on the overlay.

Expected conditions (Information level)

Project policy: expected environment/user conditions are logged at Information, never Warning/Error, so they are not forwarded to the bug-report API. Current examples:

  • Audio — missing libsndfile/libasound, no usable audio device, a missing/empty configured sound file, or a corrupt/unsupported sound file (PlaySoundEffects.IsExpectedPlaybackFailure; MP3/WAV use managed decoders, so the built-in sounds work without native packages).
  • Mounting — mounting Windows-only disc/archive images ("not supported on this platform") on Linux/macOS; SimpleXisoDrive exiting before the virtual drive appears or timing out (its captured stderr/stdout and exit code are included in the Information log so unsupported images and missing drivers stay diagnosable); SimpleZipDrive/CHDMounter FUSE conditions with automatic extraction/conversion fallbacks.
  • Launching — invalid/unlaunchable executables (Windows codes 193/216, Unix errno 8/13) and user-canceled elevation prompts.
  • Updates — GitHub 403/429, download timeouts after retry, updater "process not found", a GitHub release without assets for the current platform (LB-23).
  • Settings database — a settings.dat written by a newer app build (downgrade): migration and saves fail safe at Information, leaving the database and the legacy files untouched (NewerSchemaVersionException).
  • Files — missing files on launch/delete, a non-writable install/extraction folder (the app shows the move-to-writable-folder guidance; see ExtractionService).

Log locations summary

Path Content
%LocalAppData%\SimpleLauncher\error_user.log rolling daily log (7 days)
%LocalAppData%\SimpleLauncher\error.log error-level log
%LocalAppData%\SimpleLauncher\critical_error.log written when the bug-report API is unreachable
Debug Window (in-app) live stream via DebugWindowSink

Related docs

Clone this wiki locally