Files
frameledger/docs/10_LOGGING_AND_BUG_REPORTS.md
T
poli0981andClaude Fable 5.1 e16185f60e feat(app): the first .resx family with its generator and gate, and the App shell -- Generic Host, FluentWindow, the Agent pill over the pipe, theme + language persisted (P3 PR-2) (#155)
resx: src/FrameLedger.App/Strings.resx + .vi + .ja (65 keys; ja machine-drafted,
marked `review`), tools/resx-gen.ps1 writing the committed Strings.Designer.cs (the
SDK-style WPF project runs no ResXFileCodeGenerator), tools/resx-audit.ps1 as
build.ps1 step 15: -SelfTest (11 fixture cases, 9 red) then live. Per family:
identifier keys, non-empty neutral values, EXACT key sets in vi/ja, Safety_* in ja
marked `safety: human review required` with the English verbatim (that is how "shown
as en until signed" is true by construction) or `safety: reviewed by <name>`, and the
accessor current. No family under src/ is red, not green.

App: Generic Host per 16_WPFUI §App bootstrap; FluentWindow with the Agent pill in
the TitleBar, the Menu row (unbuilt items say so in a snackbar), NavigationView with
Settings in the footer, the offline InfoBar + Retry, SnackbarPresenter,
ContentDialogHost. Theme (Light/Dark/System + SystemThemeWatcher) and language
(rebuilds the shell in the new culture) persisted in `settings` under D16's
ui.theme/ui.language through SqliteSettingsStore -- the App opens ledger.db directly
(06_DATA_MODEL §Writer ownership, D15). Services.AgentConnection is 07_IPC §Client
behavior as a state machine over PipeClient: 8 x 250 ms, start
FrameLedger.Agent.exe --serve beside the App when absent, Hello/GetStatus, keepalive,
the event stream, retry every 5 s. Dashboard shows the Agent card with N/A until
answered; Games/Compare/Logs are empty states. Serilog logs/ui-.log per 10_LOGGING.

Three things 16_WPFUI now records: MainWindow is transient with
ShutdownMode=OnExplicitShutdown and the host lifetime ending the process; the run is
one Task from a synchronous OnStartup (async void overrides are VSTHRD100 here); and
ApplicationThemeManager.Apply(..., updateAccent: true) must precede the first
window's XAML or the accent resources are missing at first Measure (measured:
XamlParseException 'SystemAccentColorPrimary').

tests/FrameLedger.App.Tests (16): every key resolves in en/vi/ja and the satellites
really load; the accessor's keys are the resx's; appearance settings round-trip; the
connection against an in-process PipeServer -- Missing with nothing to start,
Connected on Hello, Starting -> Connected through a launcher that brings the server
up, Offline then Connected again when it returns. First window measured at 1.3 s.

Docs corrected in place: 09_I18N (generator, audit as built, the ja Safety_* rule),
12_BUILD line 15, 13_CI_CD, CLAUDE.md (App is the shell; resx-audit exists),
08_UI §Shell built note, 16_WPFUI deviations + gotcha, 10_LOGGING ui log, HANDOFF
§P3 row 2 struck (Shared's family waits for PR-4 on purpose). CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 12:45:40 +07:00

4.1 KiB

10 — Logging, diagnostics, bug reports

Serilog configuration

  • Sinks: rolling file per process — logs/ui-.log, logs/agent-.log (rollingInterval: Day, retainedFileCountLimit: 7, fileSizeLimitBytes: 10 MB, rollOnFileSizeLimit: true). Console sink in DEBUG builds. (ui-.log is written since 2026-09-13, P3 PR-2, with Process=ui enriched and every unhandled path — Dispatcher, AppDomain, unobserved task — logged as Fatal/Error; the crash dialog and minidump of §Crash handling are still P4's.)
  • Minimum level Information (Debug toggle in Settings → applies live via LoggingLevelSwitch).
  • Enrichers: process name, version, SessionGuid and GamePid scoped properties during capture (LogContext.PushProperty).
  • Template: [{Timestamp:HH:mm:ss.fff} {Level:u3}] {SourceContext} {Message:lj} {Properties:j}{NewLine}{Exception}.
  • Never log: full user paths outside %LOCALAPPDATA%\FrameLedger (redact to <user>), machine name, any exe arguments of games. A RedactingEnricher enforces the path rule.
  • Capture hot path logs nothing per-frame; counters summarized at finalize.

Crash handling (the app's own crashes)

  • Hook AppDomain.CurrentDomain.UnhandledException, DispatcherUnhandledException, TaskScheduler.UnobservedTaskException (both processes).
  • On fatal: Serilog Fatal with full exception → write minidump via MiniDumpWriteDump (CsWin32, MiniDumpWithIndirectlyReferencedMemory | WithThreadInfo) to crashdumps/ (keep last 5) → UI shows crash dialog offering the bug-report flow → exit code 1.
  • Agent crash mid-session → .partial recovery path (04_CAPTURE) on next start finalizes an interrupted session.

In-app log viewer (Logs screen)

Tails the active files (shared read), level filter, text search, pause autoscroll, "Open logs folder", "Export bug bundle". Reads at most last 2 MB per file into the view.

Bug report flow (FR-13)

  1. Entry points: Help → Report a bug, crash dialog, Logs screen button.
  2. Bundle builder creates FrameLedger-bugreport-YYYYMMDD-HHmm.zip in a user-chosen location:
    • logs/ (last 7 days, redacted copies)
    • sysinfo.json (app + agent + overlay build id, OS build, CPU/GPU name, driver version, telemetry source, Vulkan layer state, PawnIO present?, elevation state, locale)
    • overlay-<pid>-*.log for the last hooked sessions, plus hook fault details and the ring's dropped/fault counters — these are what make injection bugs diagnosable at all. (The file exists since 2026-09-06 — 17_HOOK_ENGINE §Native logging: written at init, on the Agent's request at session end, and on the stop; FAULT lines carry the exception code and the hook's name, UNHOOK_* lines say per patch whether it was restored or left to a later hooker.)
    • settings.json (sanitized — no paths)
    • optional checkbox: last session metadata + aggregates JSON (never raw blobs by default)
    • crash dumps included only when the user ticks the checkbox (size warning shown)
  3. Preview step: the dialog lists every file included and lets the user open the zip before continuing. Nothing is ever sent automatically.
  4. "Open GitHub issue" → launches browser to https://github.com/poli0981/frameledger/issues/new?template=bug_report.yml&title=[Bug]%20&labels=bug&app_version=…&os=… (short fields only — GitHub URLs cannot carry logs) with on-screen instruction: "Drag the zip file into the issue description." Clipboard fallback copies the environment summary as Markdown.
  5. bug_report.yml issue form (in .github/ISSUE_TEMPLATE/) fields: description, steps, expected/actual, app version (prefilled), OS (prefilled), attachments note.

Diagnostics extras

  • Tools → Agent status… shows the HelloAck capability set (telemetry source, overlay build id, Vulkan layer — tier availability, which meant "is the ETW fallback reachable" and has no meaning under a two-rung ladder) + last 20 Agent log lines.
  • Never include a game's own logs, saves, or config files in a bug bundle, even when a crash looks game-related. We ship our logs only.
  • --diag CLI flag on the App prints environment + capability report to stdout (support requests).