Desktop diagnostics and performance

Desktop Diagnostics & Performance

When a desktop application fails on a user's machine, you cannot SSH into their laptop. Build fast cold-start paths, bounded memory usage, and self-contained, redacted diagnostic reporting so issues can be diagnosed without guesswork.

Cold-Start & Runtime Performance Discipline

1. Keep the Main / Core Process Startup Path Lean:
   • Measure time from process launch to window.ready-to-show.
   • Defer non-essential module imports, cloud/CLI health probes, and background indexers until after the first window frame is painted (ready-to-show).
   • Bundle main-process and preload code (e.g., via Vite/esbuild/Rollup) rather than forcing Node.js to resolve thousands of individual node_modules files from disk on cold start.
2. Prevent Renderer & IPC Bottlenecks:
   • Never serialize multi-megabyte JSON payloads or raw file buffers across ipcRenderer.invoke on every keystroke or log line (structured-clone serialization blocks both Renderer and Main threads).
   • Batch high-frequency subprocess/log events (e.g., flushing every 50ms–100ms), paginate large history queries, and serve large media or artifacts via custom streaming protocols (protocol.handle('app-asset', ...) or local loopback range requests).
3. Monitor & Bound Memory Growth:
   • Track main process RSS, renderer V8 heap (process.getProcessMemoryInfo()), and child-process counts. Dispose detached BrowserWindow listeners, clear completed subprocess buffers, and cap in-memory log rings.

Crash Recovery & Privacy-Safe Diagnostics

1. Graceful Renderer & Utility Process Crash Handling:
   • Listen for webContents.on('render-process-gone', (event, details) => ...) and utilityProcess.on('exit', ...). If the renderer crashes (reason === 'crashed' or 'oom') or the embedded backend exits unexpectedly, log the exit code/reason and show a recovery screen with a one-click "Reload Window" / "Restart Local Service" action instead of leaving a dead blank window.
2. Structured, Redacted Local Log Files:
   • Write rotated, size-capped log files (maxSize: 10MB, maxFiles: 5) in app.getPath('logs') capturing startup phases, embedded server boot, IPC errors, and CLI preflight results.
   • Scrub all secrets before writing to disk: redact Authorization headers, API keys (sk-..., ghp_...), session tokens, and private environment variables.
3. One-Click Diagnostic Bundle / Copy System Info:
   • Provide a built-in diagnostic summary (App Version, Commit SHA, OS & Arch, Electron/Tauri Version, Detected CLI Statuses, Database Schema Version, and recent redacted error log tail) so users can attach actionable evidence to bug reports without opening a terminal.