Enhance heap snapshot consistency and labeling

To facilitate more accurate and consistent heap memory snapshots, a new function forceConsistentGC was added before taking a snapshot. This ensures the garbage collector (GC) runs multiple times, stabilizing the heap state for more reliable analysis. This is particularly helpful when debugging memory-related issues.

Updates to the memory-leak-detector script now allow labeling of snapshot runs using the --label flag. This helps in distinguishing different runs for easier tracking and comparison of memory usage across test sessions. Additionally, the --expose-gc flag ensures that the GC can be manually triggered during test runs, leading to more consistent memory states and potentially uncovering hidden memory leaks.

Author: ericallam

apps/webapp/app/routes/admin.api.v1.snapshot.ts

@@ -24,6 +24,27 @@ function formatDate(date: Date) {
     .padStart(2, "0")}_${milliseconds.toString().padStart(3, "0")}`;
 }
 
+// Force consistent garbage collection before taking heap snapshot
+async function forceConsistentGC(rounds = 5): Promise<void> {
+  if (typeof global.gc !== 'function') {
+    console.warn('⚠️ global.gc not available - heap snapshots may be inconsistent');
+    return;
+  }
+
+  // Force multiple GC rounds to ensure consistent state
+  for (let i = 0; i < rounds; i++) {
+    global.gc(true);  // Major GC
+    await new Promise(resolve => setTimeout(resolve, 20));
+    global.gc(false); // Minor GC (if available)
+    if (i < rounds - 1) {
+      await new Promise(resolve => setTimeout(resolve, 50));
+    }
+  }
+  
+  // Final wait for any pending cleanup
+  await new Promise(resolve => setTimeout(resolve, 200));
+}
+
 export async function loader({ request }: DataFunctionArgs) {
   const authenticationResult = await authenticateApiRequestWithPersonalAccessToken(request);
 
@@ -41,6 +62,9 @@ export async function loader({ request }: DataFunctionArgs) {
     throw new Response("You must be an admin to perform this action", { status: 403 });
   }
 
+  // Force consistent GC state before taking snapshot
+  await forceConsistentGC();
+
   const tempDir = os.tmpdir();
   const filepath = path.join(
     tempDir,

apps/webapp/memory-leak-detector.js

@@ -20,7 +20,7 @@ class MemoryLeakDetector {
     // Create timestamped directory for this run
     const runTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
     const baseDir = options.baseDir || "./.memory-snapshots";
-    const runDir = `${baseDir}/${runTimestamp}`;
+    const runDir = `${baseDir}/${runTimestamp}-${options.label || "memory-leak-detector"}`;
 
     this.options = {
       // Server configuration
@@ -234,7 +234,7 @@ class MemoryLeakDetector {
         this.log(`Using NODE_PATH: ${nodePath}`);
 
         // Start the server with memory inspection flags
-        this.serverProcess = spawn("node", ["--max-old-space-size=16384", "./build/server.js"], {
+        this.serverProcess = spawn("node", ["--max-old-space-size=16384", "--expose-gc", "./build/server.js"], {
           cwd: process.cwd(),
           stdio: ["ignore", "pipe", "pipe"],
           env: {
@@ -809,6 +809,9 @@ function parseArgs() {
       case "--sentry-dsn":
         options.sentryDsn = value;
         break;
+      case "--label":
+        options.label = value;
+        break;
       case "--verbose":
         options.verbose = true;
         i--; // No value for this flag
@@ -824,6 +827,7 @@ Options:
   --requests <number>    Number of test requests (default: 100)  
   --delay <ms>          Delay between requests (default: 50)
   --endpoints <list>     Comma-separated API endpoints to test
+  --label <string>       Label for the run
   --threshold <MB>       Memory leak threshold in MB (default: 50)
   --token <string>       Admin Bearer token for V8 heap snapshots
   --api-key <string>     API key for API requests