enrich renderer crash events for error tracking

Author: charlesvien

apps/code/src/main/index.ts

@@ -30,6 +30,7 @@ import type { SuspensionService } from "./services/suspension/service";
 import type { TaskLinkService } from "./services/task-link/service";
 import type { UpdatesService } from "./services/updates/service";
 import type { WorkspaceService } from "./services/workspace/service";
+import { collectMemorySnapshot } from "./utils/crash-diagnostics";
 import { ensureClaudeConfigDir } from "./utils/env";
 import {
   getChromiumLogFilePath,
@@ -72,6 +73,8 @@ function isCrashLoop(): boolean {
 }
 
 app.on("render-process-gone", (_event, webContents, details) => {
+  const memory = collectMemorySnapshot(() => app.getAppMetrics());
+  const chromiumLogTail = readChromiumLogTail();
   const props = {
     source: "main",
     type: "render-process-gone",
@@ -80,15 +83,20 @@ app.on("render-process-gone", (_event, webContents, details) => {
     url: webContents.getURL(),
     title: webContents.getTitle(),
     webContentsId: String(webContents.id),
+    appUptimeSeconds: Math.round(process.uptime()),
+    memoryTotalWorkingSetKb: memory?.totalWorkingSetKb,
+    memoryPeakWorkingSetKb: memory?.peakWorkingSetKb,
+    memoryProcessCount: memory?.processCount,
+    memoryByType: memory ? JSON.stringify(memory.byType) : undefined,
   };
-  log.error("Renderer process gone", {
+  log.error("Renderer process gone", { ...props, chromiumLogTail });
+  captureException(new Error(`Renderer process gone: ${details.reason}`), {
     ...props,
-    chromiumLogTail: readChromiumLogTail(),
+    chromiumLogTail,
+    // Stack is always this handler, so default grouping collapses every
+    // renderer death into one issue. Split by reason instead.
+    $exception_fingerprint: ["render-process-gone", details.reason],
   });
-  captureException(
-    new Error(`Renderer process gone: ${details.reason}`),
-    props,
-  );
   getPostHogClient()
     ?.flush()
     .catch(() => {});
@@ -121,6 +129,8 @@ app.on("render-process-gone", (_event, webContents, details) => {
 });
 
 app.on("child-process-gone", (_event, details) => {
+  const memory = collectMemorySnapshot(() => app.getAppMetrics());
+  const chromiumLogTail = readChromiumLogTail();
   const props = {
     source: "main",
     type: "child-process-gone",
@@ -129,14 +139,24 @@ app.on("child-process-gone", (_event, details) => {
     exitCode: String(details.exitCode),
     serviceName: details.serviceName ?? "",
     name: details.name ?? "",
+    appUptimeSeconds: Math.round(process.uptime()),
+    memoryTotalWorkingSetKb: memory?.totalWorkingSetKb,
+    memoryPeakWorkingSetKb: memory?.peakWorkingSetKb,
+    memoryProcessCount: memory?.processCount,
+    memoryByType: memory ? JSON.stringify(memory.byType) : undefined,
   };
-  log.error("Child process gone", {
-    ...props,
-    chromiumLogTail: readChromiumLogTail(),
-  });
+  log.error("Child process gone", { ...props, chromiumLogTail });
   captureException(
     new Error(`Child process gone (${details.type}): ${details.reason}`),
-    props,
+    {
+      ...props,
+      chromiumLogTail,
+      $exception_fingerprint: [
+        "child-process-gone",
+        details.type,
+        details.reason,
+      ],
+    },
   );
   getPostHogClient()
     ?.flush()

apps/code/src/main/services/posthog-analytics.ts

@@ -1,8 +1,10 @@
 import { PostHog } from "posthog-node";
 import { getAppVersion } from "../utils/env";
+import { uuidv7 } from "../utils/uuidv7";
 
 let posthogClient: PostHog | null = null;
 let currentUserId: string | null = null;
+let sessionId: string | null = null;
 
 export function initializePostHog() {
   if (posthogClient) {
@@ -32,6 +34,29 @@ export function getCurrentUserId() {
   return currentUserId;
 }
 
+/**
+ * The PostHog session id is OWNED BY MAIN. Main mints one UUIDv7 and every
+ * renderer window bootstraps posthog-js with it (`bootstrap.sessionID`).
+ * Because main outlives the renderer, the id stays stable across a renderer
+ * crash + reload, so the replay is one continuous session spanning the crash
+ * and main-captured crash events (the renderer can't report its own OOM)
+ * always carry the right `$session_id` with no race or hand-off.
+ *
+ * Minted lazily on first request (a window asks at boot, before posthog-js
+ * init) so its UUIDv7 timestamp precedes the session's first event, as
+ * posthog-js requires.
+ */
+export function getOrCreateSessionId(): string {
+  if (!sessionId) {
+    sessionId = uuidv7();
+  }
+  return sessionId;
+}
+
+export function getSessionId(): string | null {
+  return sessionId;
+}
+
 export function trackAppEvent(
   eventName: string,
   properties?: Record<string, string | number | boolean>,
@@ -96,6 +121,7 @@ export function captureException(
   const distinctId = currentUserId || "anonymous-app-event";
   posthogClient.captureException(error, distinctId, {
     team: "posthog-code",
+    ...(sessionId ? { $session_id: sessionId } : {}),
     ...additionalProperties,
     app_version: getAppVersion(),
   });

apps/code/src/main/trpc/routers/analytics.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import {
+  getOrCreateSessionId,
   identifyUser,
   resetUser,
   setCurrentUserId,
@@ -29,6 +30,15 @@ export const analyticsRouter = router({
       }
     }),
 
+  /**
+   * Return the main-owned session id for a window to bootstrap posthog-js with
+   * (`bootstrap.sessionID`). Main owns it so crash events captured from main
+   * link to the right replay, and the id survives renderer crash+reload.
+   */
+  getSessionId: publicProcedure
+    .output(z.object({ sessionId: z.string() }))
+    .query(() => ({ sessionId: getOrCreateSessionId() })),
+
   /**
    * Reset the current user (on logout)
    */

apps/code/src/main/utils/crash-diagnostics.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { collectMemorySnapshot } from "./crash-diagnostics";
+
+function metric(
+  type: string,
+  workingSetSize: number,
+  peakWorkingSetSize: number,
+): Electron.ProcessMetric {
+  return {
+    type,
+    memory: { workingSetSize, peakWorkingSetSize, privateBytes: 0 },
+  } as unknown as Electron.ProcessMetric;
+}
+
+describe("collectMemorySnapshot", () => {
+  it("sums working set, tracks peak, and groups by process type", () => {
+    const snapshot = collectMemorySnapshot(() => [
+      metric("Browser", 100, 150),
+      metric("Tab", 200, 500),
+      metric("Tab", 50, 60),
+      metric("GPU", 80, 90),
+    ]);
+
+    expect(snapshot).toEqual({
+      totalWorkingSetKb: 430,
+      peakWorkingSetKb: 500,
+      processCount: 4,
+      byType: { Browser: 100, Tab: 250, GPU: 80 },
+    });
+  });
+
+  it("returns a zeroed snapshot for no processes", () => {
+    expect(collectMemorySnapshot(() => [])).toEqual({
+      totalWorkingSetKb: 0,
+      peakWorkingSetKb: 0,
+      processCount: 0,
+      byType: {},
+    });
+  });
+
+  it("returns undefined instead of throwing (crash handler must not fail)", () => {
+    expect(
+      collectMemorySnapshot(() => {
+        throw new Error("getAppMetrics unavailable");
+      }),
+    ).toBeUndefined();
+  });
+});

apps/code/src/main/utils/crash-diagnostics.ts

@@ -0,0 +1,49 @@
+export interface MemorySnapshot {
+  totalWorkingSetKb: number;
+  peakWorkingSetKb: number;
+  processCount: number;
+  byType: Record<string, number>;
+}
+
+/**
+ * Summarize per-process memory (from `app.getAppMetrics()`, passed in by the
+ * caller so this stays free of a direct `electron` import) for crash
+ * diagnostics. Working-set sizes are in KB. Attached to renderer/child crash
+ * events so PostHog Error Tracking can show whether the app was under memory
+ * pressure: a hard OOM kills the renderer before it can log anything, so the
+ * chromium log usually goes silent and this is the only reliable signal.
+ *
+ * Defensive on purpose: a throw here would run before the crash handler's
+ * auto-recovery reload, so failures return `undefined` instead.
+ *
+ * Caveat: at `render-process-gone` time the dead renderer is already gone from
+ * the metrics, so the `Tab` total understates the renderer's real peak. The
+ * `unresponsive` sample (renderer still alive) is the more telling one.
+ */
+export function collectMemorySnapshot(
+  getMetrics: () => Electron.ProcessMetric[],
+): MemorySnapshot | undefined {
+  try {
+    const metrics = getMetrics();
+    let totalWorkingSetKb = 0;
+    let peakWorkingSetKb = 0;
+    const byType: Record<string, number> = {};
+    for (const metric of metrics) {
+      const workingSet = metric.memory.workingSetSize;
+      totalWorkingSetKb += workingSet;
+      peakWorkingSetKb = Math.max(
+        peakWorkingSetKb,
+        metric.memory.peakWorkingSetSize,
+      );
+      byType[metric.type] = (byType[metric.type] ?? 0) + workingSet;
+    }
+    return {
+      totalWorkingSetKb,
+      peakWorkingSetKb,
+      processCount: metrics.length,
+      byType,
+    };
+  } catch {
+    return undefined;
+  }
+}

apps/code/src/main/utils/uuidv7.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { uuidv7 } from "./uuidv7";
+
+const UUID_V7 =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+describe("uuidv7", () => {
+  it("produces a valid v7 string (version nibble 7, variant 10)", () => {
+    for (let i = 0; i < 100; i++) {
+      expect(uuidv7()).toMatch(UUID_V7);
+    }
+  });
+
+  it("encodes the current time so ids sort in creation order", () => {
+    const before = Date.now();
+    const id = uuidv7();
+    const after = Date.now();
+
+    // First 48 bits (first 12 hex chars, minus the dash) are the unix-ms stamp.
+    const stampMs = Number.parseInt(id.slice(0, 8) + id.slice(9, 13), 16);
+    expect(stampMs).toBeGreaterThanOrEqual(before);
+    expect(stampMs).toBeLessThanOrEqual(after);
+  });
+
+  it("is unique across rapid calls", () => {
+    const ids = new Set(Array.from({ length: 1000 }, () => uuidv7()));
+    expect(ids.size).toBe(1000);
+  });
+});

apps/code/src/main/utils/uuidv7.ts

@@ -0,0 +1,29 @@
+import { randomBytes } from "node:crypto";
+
+/**
+ * Generate a UUIDv7 (time-ordered, RFC 9562). posthog-js requires this exact
+ * format for `bootstrap.sessionID`: a valid v7 whose 48-bit timestamp precedes
+ * the session's first event. Main mints it before any window starts posthog-js,
+ * so the ordering holds.
+ *
+ * Layout: 48-bit big-endian unix-ms timestamp, 4-bit version (7), 2-bit variant
+ * (10), 74 random bits. Hand-rolled to avoid a phantom dependency on `uuid`
+ * (transitive only, and several major versions resolve in the tree).
+ */
+export function uuidv7(): string {
+  const bytes = randomBytes(16);
+  const timestamp = Date.now();
+
+  bytes[0] = Math.floor(timestamp / 2 ** 40) & 0xff;
+  bytes[1] = Math.floor(timestamp / 2 ** 32) & 0xff;
+  bytes[2] = Math.floor(timestamp / 2 ** 24) & 0xff;
+  bytes[3] = Math.floor(timestamp / 2 ** 16) & 0xff;
+  bytes[4] = Math.floor(timestamp / 2 ** 8) & 0xff;
+  bytes[5] = timestamp & 0xff;
+
+  bytes[6] = (bytes[6] & 0x0f) | 0x70; // version 7
+  bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant 10
+
+  const hex = bytes.toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

apps/code/src/main/window.ts

@@ -14,6 +14,7 @@ import { MAIN_TOKENS } from "./di/tokens";
 import { buildApplicationMenu } from "./menu";
 import type { ElectronMainWindow } from "./platform-adapters/electron-main-window";
 import { trpcRouter } from "./trpc/router";
+import { collectMemorySnapshot } from "./utils/crash-diagnostics";
 import { isDevBuild } from "./utils/env";
 import { logger, readChromiumLogTail } from "./utils/logger";
 import { type WindowStateSchema, windowStateStore } from "./utils/store";
@@ -110,13 +111,17 @@ function setupCrashLogging(window: BrowserWindow): void {
       reason: details.reason,
       exitCode: details.exitCode,
       url: window.webContents.getURL(),
+      memory: collectMemorySnapshot(() => app.getAppMetrics()),
       chromiumLogTail: readChromiumLogTail(),
     });
   });
 
+  // Unresponsive often precedes an OOM kill, and here the renderer is still
+  // alive, so this memory sample reflects its real (bloated) footprint.
   window.on("unresponsive", () => {
     log.warn("Window unresponsive", {
       url: window.webContents.getURL(),
+      memory: collectMemorySnapshot(() => app.getAppMetrics()),
       chromiumLogTail: readChromiumLogTail(),
     });
   });

apps/code/src/renderer/App.tsx

@@ -52,13 +52,25 @@ function App() {
 
   // Initialize PostHog analytics and register the app version super property.
   useEffect(() => {
-    initializePostHog();
-    trpcClient.os.getAppVersion
-      .query()
-      .then(registerAppVersion)
-      .catch((error) => {
-        log.warn("Failed to register app version super property", { error });
-      });
+    // Fetch the main-owned session id BEFORE initializing posthog-js so the
+    // recording shares the id main stamps on crash events. Init is gated on it
+    // so the id is set before the first event (posthog-js requires the
+    // bootstrap id's timestamp to precede the session's first event).
+    void (async () => {
+      let sessionId: string | undefined;
+      try {
+        ({ sessionId } = await trpcClient.analytics.getSessionId.query());
+      } catch (error) {
+        log.warn("Failed to fetch session id from main", { error });
+      }
+      initializePostHog(sessionId);
+      trpcClient.os.getAppVersion
+        .query()
+        .then(registerAppVersion)
+        .catch((error) => {
+          log.warn("Failed to register app version super property", { error });
+        });
+    })();
   }, []);
 
   // Initialize connectivity monitoring

apps/code/src/renderer/utils/analytics.ts

@@ -36,7 +36,12 @@ type PendingFlagListener = {
 // Subscribers added before initializePostHog runs.
 const pendingFlagListeners = new Set<PendingFlagListener>();
 
-export function initializePostHog() {
+/**
+ * @param sessionId Main-owned session id (UUIDv7) to bootstrap posthog-js with,
+ *   so the recording shares the id main stamps on crash events. Main owns it so
+ *   it survives a renderer crash+reload as one continuous session.
+ */
+export function initializePostHog(sessionId?: string) {
   const apiKey = import.meta.env.VITE_POSTHOG_API_KEY;
   const apiHost =
     import.meta.env.VITE_POSTHOG_API_HOST || "https://internal-c.posthog.com";
@@ -51,6 +56,12 @@ export function initializePostHog() {
     api_host: apiHost,
     ui_host: uiHost,
     disable_session_recording: false,
+    // Hold the session open through long idle (max posthog-js allows) so its
+    // own rotation doesn't replace main's bootstrapped id mid-run. This app
+    // sits idle for hours with background tasks, which is exactly when a
+    // shorter timeout would silently rotate and break crash->replay linking.
+    session_idle_timeout_seconds: 36000,
+    ...(sessionId ? { bootstrap: { sessionID: sessionId } } : {}),
     capture_exceptions: import.meta.env.DEV
       ? false
       : {