Logging, diagnostics and performance tracking for error reporting

[freezy]

The engine part of the logging and error reporting work: a cleaned-up NLog setup, diagnostics that describe the session for bug reports, performance tracking, and the building blocks the player's Sentry integration uses. Sentry itself lives in the player (VisualPinball/VisualPinball.Engine.Player); the engine has no dependency on it.

Logging

• Setup: NLog is configured at SubsystemRegistration. All targets except the editor console sit behind our own queue, so the logging thread only enqueues and rendering and file I/O happen on a writer thread. NLog's AsyncTargetWrapper renders events with exceptions on the logging thread, which the simulation thread can't afford.
• Session log: one file per session (newest 10 kept), flushed per batch, plus an in-memory tail of the last 2000 lines for reports. -vpe-log-level overrides the level.
• Bridges and hooks: UnityLogBridge forwards Debug.Log from Unity and third-party code into NLog. CrashHooks log unhandled and unobserved exceptions. UnityTarget renders exceptions as text instead of Debug.LogException.
• Simulation thread: catches what kills it, logs it after the no-GC region ends, and SimulationThreadComponent raises SimulationFaulted.
• Level policy, applied across the runtime: Error is for VPE bugs. Problems a table author or user can cause (unmapped coils, switches, lamps, missing sounds, unknown component types, invalid table files) are warnings. Per-item and per-frame lines are Debug/Trace, and hot paths go through LogThrottle/LogOncePerKey. Errors use message templates, so reports group by template. LoggingRulesTests scans the runtime code of every swept package and enforces this.
• Bugs fixed on the way:
  • a hit event for an item without a hit handler threw KeyNotFoundException;
  • PackagedRefs threw on a missing component;
  • the trough logged an error on every drain.

Diagnostics

DiagnosticsContext holds named sections, logged when they change and attached to reports:

• System: OS, CPU and cores, RAM, GPU, driver, VRAM, displays, Unity, render pipeline, command line with secrets removed.
• Build: the app version, the commit of every VPE repository and the version of every VPE package.
• Table: a LoadAttempt tracks phase, package format, metadata and a fingerprint. It survives a failed load.
• Gamelogic and plugins: what engines and plugins report through the new IDiagnosticsSource.

Redaction removes the home folder and user name from paths, including inside JSON (RedactJson). DiagnosticsWriter never writes values of settings that look like secrets.

Plugins

IPluginLog (levelled, with exceptions) is added next to the old text log. It is written to NLog as Plugin.<id>. An error callback receives exceptions from plugin hooks with their stack trace.

IGamelogicStartupStatus lets engines report what the user can fix (missing ROM, emulator not installed) instead of throwing from OnInit.

Performance

PerformanceMonitor is a PlayerLoop system and the only frame timing capturer; FramePacingGraph and the player's overlay read from it.

• Classification: it closes 1 s windows and decides what bounds the frame (capped, gpu, cpu-main, cpu-render), with hysteresis.
• Logging: a line when FPS moves by 20 % or the bound changes, at most every 10 s, with a 5-minute heartbeat. Hitches and a nearly full GPU budget warn, throttled.
• Memory: RAM comes from the OS (Unity's counter on macOS), VRAM usage and budget from DXGI on Windows.
• Session summary: written when the table ends; it includes average FPS, worst 1 %, bound shares and peaks.

Error reporting building blocks

• ReportDedupe: the first automatic report of each kind per session, at most ten, fatal ones always.
• Diagnostics snapshot file next to each session log, for the crash follow-up.
• DiagnosticsContext.Removed, so the report scope forgets a closed table.
• InvalidPackageException: a file that isn't a loadable .vpe package is the user's problem, not a bug. The reader also only starts its background reads once the file passed these checks.

Testing

• EditMode tests: logging, diagnostics, redaction, logging rules, frame-bound classifier, report dedupe and invalid packages, all passing in VisualPinball.Unity.Project.Hdrp.
• Player sessions: verified in the player editor and in a Windows release build against Sentry.

Merge order

Merge this first. The plugin PRs depend on the new plugin API (IPluginLog, IDiagnosticsSource, IGamelogicStartupStatus).

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The changes appear safe to merge; both previous findings are fixed and no new actionable issues were found.

Summary

Adds queued session logging, diagnostics, plugin logging APIs, performance tracking, and error-reporting helpers.

• Reports can include redacted details about the session.
• Runtime logs now use clearer levels and avoid repeating noisy messages.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Engine and plugin logs] --> Q[Shared log queue]
  U[Unity logs] --> B[UnityLogBridge]
  B --> Q
  Q --> W[Writer thread]
  W --> F[Session file]
  W --> T[In-memory tail]
  W --> R[Host reporting targets]

Loading

_{Reviews (2) · Last reviewed commit: "logging: Send the first fatal report of ..." · Reviewed by Greptile}