Repository navigation
feat(diagnostics): a diagnostics log with Explorer stall probes (#322) - #325
Merged
Merged
Conversation
…322) prism-term-core is pinned to core-v0.27.0-rc.1 (the diagnostics log's release candidate, Maxaubert/PrismTerminal#141) and Prism goes to 0.94.0, the next minor above every open PR. - The preload spreads the core's diag bridge (createDiagApi). - Settings gets the core's DiagnosticsPage (Detailed logging, Log files, Mark a problem) as a rail page in the bottom group, beside About; its rows are in Find a setting (coreSettingsIndex diagnostics: true) and in ROW_ORDER before About's. - diagnosticsOptions joins the core's plain .ts modules resolved by path (vite, vitest, tsconfig), for the settings tests. - settingsLook's rail and pages include Diagnostics. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FHHaWKR4M5QtW7Wecyuk4t
The terminal core's diagnostics log (Maxaubert/PrismTerminal#140), wired into Prism's main and page. - startDiagnostics once the single-instance lock is won, before every ipcMain registration, with <userData>\logs as its folder. - LONG_WAIT_CHANNELS (src/main/diagChannels.ts): Prism's dialogs, searches, the folder size scan, the extraction window's jobs, the video convert, the update download, copies and the decoders. In-process work stays timed: there a slow answer is the stall. A test holds every name to a registration. - logWindow writes each window event into the log as well; window-crashes.log is kept. - withStackPolicy on the window's document, so the page stack can be read. - watchWindow on every window made, stop on the quit that goes ahead, a synchronous flush at a Windows shutdown. - The boot entry starts the page's half before the app chunk loads. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FHHaWKR4M5QtW7Wecyuk4t
…og (#322) What the diagnostics design asked of the Explorer, so a stall there can be told from its numbers: - open-folder (useFolderBrowsing): path, reason (navigate, back, forward, refresh, focus, dir-changed, retry, arrival), ms, entries, cached; a navigation's read is said once though the location effect joins it. - sort-slow (sortTiming.ts): the sort-and-filter pass times itself, with the row count and the input that made it run again (sizes, query, sort, listing, dates). Suspect 3. - guard-slow (desktopAccess): one guard call of 50 ms or more, with the paths asked about and the grants held. Folder sizes filter a list as ONE call (insideDesktopAll), so the loop is what is timed. Suspect 1. - search-start / search-end (ms, hits, source) / search-cancel; the filter per keystroke and a search replaced by the next are Detailed only. - folder-size (path, ms), watch (path, ms): main crumbs through mainCrumb; a quick one is Detailed only. - archive-job start and end (result, ms) from the extraction window's channel. - preview on and off. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FHHaWKR4M5QtW7Wecyuk4t
The rest of Prism's timeline for the diagnostics log: - lib/tabCrumbs (pure, tested): tab-open, tab-close, tab-switch, project-open and player-open, read off the tab state rather than said at each of the dozen places a tab changes. - sort: a column picked in the Explorer. - settings-page: the Settings page looked at. The update window, its install and dictation say theirs in the core. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FHHaWKR4M5QtW7Wecyuk4t
README: the log is kept on this PC only, in %APPDATA%\Prism\logs, never sent, and Settings > Diagnostics opens it. CLAUDE.md: read a stall from the log first (Prism Terminal's docs/diagnostics.md, npm run diag -- --app prism there), and where the wiring, the long-wait channels and the Explorer's probes live. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FHHaWKR4M5QtW7Wecyuk4t
diagLog makes the page stall, throw and reject, and calls an e2e-only channel main answers after 600 ms (e2e:slow-ipc, registered under --e2e alone), then quits and reads the log: the page-stall with its stack, the error, the rejection and the ipc-slow line must all be there. It joins e2e:terminal, since the log is the core's. explorerDiag opens a folder of six files and a subfolder and presses the Name header: the log must hold an open-folder crumb (reason navigate, the read's ms, 7 entries, whether a cache painted first) and a sort crumb. Every scenario's own log is read after it, and the run ends with a Stalls table: lines of 1 s or more and errors, per scenario. A report, not a gate: a slow line on a busy machine is a lead, not a failure. diagLog's own lines are marked "(expected)". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FHHaWKR4M5QtW7Wecyuk4t
From 0.27.0-rc.1 to the release. It also carries core 0.26.0's on switch in the theme's accent (#138), so settingsLook leaves role="switch" out of its "only Save wears the accent" count, the same change as the 0.26.0 bump (Prism #323). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FHHaWKR4M5QtW7Wecyuk4t
…e-v0.27.0 Main moved to 0.96.0 with core-v0.26.0; this branch keeps core-v0.27.0 (the released diagnostics log) and takes the next minor, 0.97.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FHHaWKR4M5QtW7Wecyuk4t
- Window guard lines: gone, unresponsive and responsive are left to the core (they were written twice); a hang and the watchdog are window-slow, which npm run diag lists; handoff and restore are crumbs. - The log stops LAST on the quit, after the shell, sidecar and conversion teardown. - open-folder: the navigate marker is per tab and taken back once its read answers (a navigation to the folder on screen swallowed the next crumb); an abandoned read is still said (abandoned: true); the refresh key is taken before any early return, so a refresh from another tab is not mislabelled; a quick dir-changed or focus re-read is Detailed only. - search-start is Detailed only; search-end reaches the quiet log only at 500 ms or more, and carries the query. - sort-slow is rate-gated per trigger (one line per 5 s, held passes counted on the next line). - player-open from the preview pane beside the list is Detailed only. - Long-wait channels: open:folder, comic:open, file:duplicate, file:restore and dictation:transcribe; the archive reads that can run in main's thread stay timed, and the rule says why. - ownsDesktopDirectory times itself; the watch crumb is written only when a watcher was set up (or refused). - The Document-Policy header hook is filtered to main frames, so other responses never reach main's thread. - e2e: explorerDiag asserts one crumb per navigation and a focus re-read after a same-folder navigation (fails without the marker fix); the harness flushes main's log before app.exit for the Stalls table. - README says the log holds full paths and search text; the CLAUDE.md entry is cut to the rule and the pointers. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FHHaWKR4M5QtW7Wecyuk4t
A CI runner's temp folder is an 8.3 short path. The guard resolves a granted folder that exists but not a child that does not, so the two timing tests' paths read as outside on CI only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FHHaWKR4M5QtW7Wecyuk4t
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #322
Owner: "implement some robust logging and debugging into the program especially to catch stalls for example in explorer or in general".
The core half is Prism Terminal #141 (merged), released as
core-v0.27.0. This PR pinscore-v0.27.0and supersedes bot PR #324, which bumped the same pin without Prism's half. Prism goes to 0.97.0 (minor, a feature).What changes
%APPDATA%\Prism\logs\diag.jsonl(the core's writer): session line, window events, IPC timing (ipc-slow,ipc-error), main-thread lag with the calls in flight (main-lag), page stalls with a stack (page-stall,page-stack), page errors and rejections. Detailed logging (a setting) adds every call and the quick crumbs.open-folder,navigate(per tab, with its reason: refresh, focus, dir-changed),watch,search-start/search-end(with the query),folder-size,archive-job,player-open,sort-slow(rate-gated: one line per trigger per 5 s, withheld/heldMaxMs),guard-slow(the desktop path guard times itself). Quick re-reads (under 200 ms) and per-keystroke crumbs are Detailed only, so a dir-changed storm does not flood the quiet log.src/main/diagWindow.ts:gone/unresponsive/responsiveare left to the core (no double lines);hangandwatchdogbecomewindow-slow, whichnpm run diagalready ranks as a problem;handoffandrestoreare crumbs.cancelAllConversions(), so the last lines of a quit are written.diagLog,explorerDiag, and a closing Stalls table after every run (a report, not a gate). Under--e2emain exposes__e2eDiagFlush, called beforeapp.exit.longWaitChannels(neveripc-slow, never in amain-lag's inflight)The rule: the call waits on the USER, or it is a long job by design whose work runs OFF main's thread and has a window, crumb or progress of its own. Work in main's thread stays timed (there a slow answer is the stall).
dialog:pick-folder,open:folder,dialog:pick-files,open:dialog,subs:pick,image:save-copybrowse:search,browse:suggest,search:filessearch-*crumbs time itfolder:sizefolder-sizecrumbarchive:extract-to,archive:extract-members-picked,archive:extract-all,archive:extract-dir,archive:member-outarchive-jobcrumbscomic:openvideo:convertupdate:installfile:paste-into,file:movefile:duplicatefile:restoremedia:peaks,audio:synthdictation:transcribe(DCH.transcribe)Kept timed on purpose:
archive:delete,archive:add,archive:move-members,archive:rename,doc:html(in process),folder:sizes-cached(its path guard is suspect 1), andarchive:list/archive:extract/archive:member(a small .zip is read by adm-zip on main's thread, and an automatic preview is size-capped). A unit test holds every name to a registration inindex.tsor the core's dictation table.Gates
diagLogandexplorerDiag: pass. Thenavigatedmarker fix was checked in reverse: without it the focus re-read never appears andexplorerDiagfails.npm run e2e:terminal: all checks passed.tools/e2e/run.mjs), includingcolumnHeaders,panelsAlign,jsonc,dragLabel,toolbarIcons.Stalls (from the full e2e run; a report, not a gate)
diagE2eBusyC:\Users\Admin\.agents,.bun(size scans, off main)C:\$Recycle.Bin,C:\asrwindow-preferences:setThe one real suspect the log found in our own suite is
window-preferences:setinsidebarGround(1.2 s on main's thread), worth a follow-up issue. Runs 1, 5, 6 and 7 showed no stalls.Follow-up (not in this PR)
dictation:transcribebelongs in the core's ownLONG_WAITtoo, so Prism Terminal gets the same fix; that is a core version bump in Prism Terminal.🤖 Generated with Claude Code
https://claude.ai/code/session_01FHHaWKR4M5QtW7Wecyuk4t