chore(desktop): fleet memory telemetry — periodic resource_snapshot to PostHog

Merged
KI
4mo ago
+410-0

What

Adds a privacy-safe aggregate memory telemetry sampler in the desktop main process (SUPER-1550). Every ~5 minutes it emits one flat, numbers-only resource_snapshot PostHog event so we finally have fleet memory data (renderer RSS vs process/window/webview counts, release-over-release regression detection, before/after proof for perf fixes). ~12 tiny events/user/hour.

Closes SUPER-1550.

Schema — resource_snapshot

All properties are finite numbers. Enforced by the RESOURCE_SNAPSHOT_KEYS allowlist; emission filters the payload to exactly these keys.

keysource
uptime_secondsprocess.uptime() (rounded)
process_rss_bytes, process_heap_used_bytes, process_heap_total_bytes, process_external_bytes, process_array_buffers_bytesprocess.memoryUsage()
electron_main_rss_bytes, electron_renderer_rss_bytes, electron_other_rss_bytes, electron_total_rss_bytesapp.getAppMetrics() by process class (KB→bytes)
electron_main_process_count, electron_renderer_process_count, electron_other_process_count, electron_process_countapp.getAppMetrics() counts
window_countBrowserWindow.getAllWindows().length
web_contents_countwebContents.getAllWebContents().length

(plus the standard track() context: app_name, platform, desktop_version.)

Privacy

  • Hard allowlist: emitResourceSnapshot copies only allowlisted keys whose value is a finite number. Anything else is structurally impossible to emit. A test asserts no key matches /id|name|path|command|repo|url|user|org|title/i.
  • No IDs, names, paths, commands, or repo/terminal/user data — deliberately excluded terminal/workspace/org counts to avoid coupling to those subsystems and keep scope narrow.
  • No ps subprocess: app.getAppMetrics() reads Electron internals; process.memoryUsage() is in-process. Never spawns per-sample process scans (does not touch the existing resource-metrics ps path).

Perf / lifecycle

  • Self-rescheduling setTimeout at ~5 min with up to 60s per-tick jitter (fleet doesn't emit in lockstep).
  • .unref()ed — never keeps the process alive.
  • Idempotent startMemoryTelemetry() (dup-timer guard) so startup + HMR re-entry can't double-schedule.
  • stopMemoryTelemetry() wired into before-quit cleanup; emit is wrapped so a telemetry error can never crash the app.
  • Gated off in test/dev and honors DEFAULT_TELEMETRY_ENABLED; track() additionally no-ops until a user is identified and a PostHog key is set.

electron is imported as a namespace and dereferenced lazily inside defaultDeps, so the module links in the test suite regardless of which per-file electron mock is active (a static named import { webContents } breaks when another test replaces the mock).

Validation

  • bun test (full desktop suite) — 2173 pass, 0 fail across 221 files. The memory-telemetry unit tests (9) are fake-timer based and cover cadence, payload allowlist, disabled state, and cleanup/unref; each was verified to fail under a deliberate mutation (leaked key / broken cleanup).
  • bun run lint — clean (0 warnings). tsc --noEmit — clean across all packages.
  • CDP (real dev app, this worktree): app boots with the telemetry wiring (Tray + notifications up, no crash); renderer renders the full signed-in workspace UI (no white screen); resourceMetrics.getSnapshot — which calls the same app.getAppMetrics() the sampler uses — returns valid live per-class RSS (main 425MB / renderer 735MB). The resource_snapshot emission itself is intentionally disabled in dev (gated, no PostHog key), so it is not observable in dev by design; that path is covered by the unit tests above.

Summary by CodeRabbit

  • New Features

    • Added privacy-safe, aggregated memory and resource usage telemetry to the desktop app.
    • Resource snapshots are collected periodically with an allowlisted set of numeric metrics.
    • Telemetry automatically starts on app startup and stops during app shutdown.
  • Reliability

    • Telemetry emissions are guarded so failures won’t disrupt normal app operation.
    • Background sampling is prevented from keeping the app alive after shutdown.
  • Tests

    • Added a comprehensive unit test suite covering snapshot building, emission rules, start/stop behavior, and enablement.