Production Diagnostics and Profiling: CPU Profiling, Clinica.js, and Core Dumps

[ Node.js Production Instance ]
                             |
             +---------------+---------------+
             | (Process is Running)          | (Fatal Crash / SegFault)
             v                               v
   [ Diagnostics Agent ]             [ Linux Kernel ]
    - node:inspector                  - ulimit -c unlimited
    - v8.writeHeapSnapshot            - kernel.core_pattern
             |                               |
             +---------------+               v
             |               |      [ core.[pid] Dump File ]
             v               v               |
     [ CPU Profile ]  [ Heap Snapshot ]      v
     (.cpuprofile)      (.heapsnapshot)  [ lldb + llnode ]
             |               |               |
             v               v               v
      [ Clinica Flame / Chrome DevTools ]  [ Inspect JS Stack & Memory ]

import inspector from "node:inspector";
import fs from "node:fs";
import path from "node:path";
import v8 from "node:v8";

export class ProductionDiagnosticsAgent {
  private session: inspector.Session | null = null;
  private isProfiling = false;
  private readonly storageDir: string;

  constructor(storageDir = "/tmp/diagnostics") {
    this.storageDir = storageDir;
    if (!fs.existsSync(this.storageDir)) {
      fs.mkdirSync(this.storageDir, { recursive: true });
    }
  }

  /**
   * Captures statistical CPU profile over a specified duration without process restart
   */
  public async captureCpuProfile(durationSeconds = 10): Promise<string> {
    if (this.isProfiling) {
      throw new Error("CPU profiling session is already in progress");
    }

    this.isProfiling = true;
    const session = new inspector.Session();
    this.session = session;
    session.connect();

    return new Promise<string>((resolve, reject) => {
      // Enable V8 Profiler domain
      session.post("Profiler.enable", (err) => {
        if (err) {
          this.cleanupSession();
          return reject(err);
        }

        // Set sampling interval in microseconds (1000 µs = 1 ms)
        session.post("Profiler.setSamplingInterval", { interval: 1000 }, (intervalErr) => {
          if (intervalErr) {
            this.cleanupSession();
            return reject(intervalErr);
          }

          // Start sampling execution stacks
          session.post("Profiler.start", (startErr) => {
            if (startErr) {
              this.cleanupSession();
              return reject(startErr);
            }

            console.info(`[Diagnostics] CPU Profiling started for ${durationSeconds}s...`);

            // Await profiling duration
            setTimeout(() => {
              session.post("Profiler.stop", (stopErr, { profile }) => {
                this.cleanupSession();

                if (stopErr) {
                  return reject(stopErr);
                }

                const filename = `cpu-profile-${process.pid}-${Date.now()}.cpuprofile`;
                const fullPath = path.join(this.storageDir, filename);

                fs.writeFileSync(fullPath, JSON.stringify(profile));
                console.info(`[Diagnostics] CPU Profile saved to ${fullPath}`);
                resolve(fullPath);
              });
            }, durationSeconds * 1000);
          });
        });
      });
    });
  }

  /**
   * Captures an instant heap snapshot serialized directly to disk
   */
  public captureHeapSnapshot(): string {
    const filename = `heap-snapshot-${process.pid}-${Date.now()}.heapsnapshot`;
    const fullPath = path.join(this.storageDir, filename);

    console.info(`[Diagnostics] Streaming Heap Snapshot to ${fullPath}...`);
    // Native V8 method: Streams memory directly to disk via C++ runtime, bypassing JS heap allocations
    v8.writeHeapSnapshot(fullPath);
    console.info(`[Diagnostics] Heap Snapshot completed: ${fullPath}`);

    return fullPath;
  }

  private cleanupSession(): void {
    if (this.session) {
      this.session.post("Profiler.disable");
      this.session.disconnect();
      this.session = null;
    }
    this.isProfiling = false;
  }
}

import { ProductionDiagnosticsAgent } from "./diagnostics-agent";

export function initializeDiagnosticsSignals(): void {
  const agent = new ProductionDiagnosticsAgent();

  // SIGUSR2: Trigger on-demand Heap Snapshot without service interruption
  process.on("SIGUSR2", () => {
    try {
      console.warn(`[Process ${process.pid}] Received SIGUSR2: triggering Heap Snapshot`);
      const snapshotPath = agent.captureHeapSnapshot();
      console.warn(`[Process ${process.pid}] Heap Snapshot ready: ${snapshotPath}`);
    } catch (error) {
      console.error("[Diagnostics] Failed to capture snapshot on SIGUSR2:", error);
    }
  });

  console.info(`[Diagnostics] Signal listeners attached to PID ${process.pid}. Send SIGUSR2 for Heap Snapshot.`);
}