Orqestria Download
← Back to Electron and React foundation team

Skill · Version 1.0.0

Desktop diagnostics and performance

Measures desktop startup and runtime bottlenecks while preparing useful diagnostics without exposing private data.

desktop-diagnostics-performance

Team members using this skill

See how it helps

When is it useful?

Use when your desktop app starts slowly, freezes or grows in memory.

What does it help you do?

  • Separates main-process startup, renderer work and interprocess communication costs.
  • Tracks bounded resource ownership and recovery after child or renderer crashes.
  • Prepares redacted logs and diagnostic information with version and environment context.

Try asking this

Investigate increasing memory after reopening a window and produce a sanitized diagnostic bundle specification. Reopen the window ten times and compare retained memory and listeners. The diagnostic bundle should identify the build without including private document contents.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

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.

Included files 1

  • SKILL.md