Діагностика та профілювання в Production: CPU Profiling, Clinica.js та Core Dumps

[ Інстанс Node.js у Production ]
                              |
              +---------------+---------------+
              | (Процес працює)               | (Аварійний крах / SegFault)
              v                               v
    [ Агент діагностики ]             [ Ядро Linux ]
     - node:inspector                  - ulimit -c unlimited
     - v8.writeHeapSnapshot            - kernel.core_pattern
              |                               |
              +---------------+               v
              |               |       [ Файл core.[pid] ]
              v               v               |
      [ Профіль CPU ]  [ Знімок купи ]        v
      (.cpuprofile)      (.heapsnapshot)  [ lldb + llnode ]
              |               |               |
              v               v               v
       [ Clinica Flame / Chrome DevTools ]  [ Реконструкція стека та пам'яті ]

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 });
    }
  }

  /**
   * Запуск статистичного профілювання CPU на заданий час без перезапуску інстансу
   */
  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) => {
      // Активація профайлера V8
      session.post("Profiler.enable", (err) => {
        if (err) {
          this.cleanupSession();
          return reject(err);
        }

        // Встановлення інтервалу семплування у мікросекундах (1000 мкс = 1 мс)
        session.post("Profiler.setSamplingInterval", { interval: 1000 }, (intervalErr) => {
          if (intervalErr) {
            this.cleanupSession();
            return reject(intervalErr);
          }

          // Старт запису семплів викликів
          session.post("Profiler.start", (startErr) => {
            if (startErr) {
              this.cleanupSession();
              return reject(startErr);
            }

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

            // Очікування тривалості запису
            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);
          });
        });
      });
    });
  }

  /**
   * Створення моментального знімка купи (Heap Snapshot) із потоковим записом
   */
  public captureHeapSnapshot(): string {
    const filename = `heap-snapshot-${process.pid}-${Date.now()}.heapsnapshot`;
    const fullPath = path.join(this.storageDir, filename);

    console.info(`[Diagnostics] Writing Heap Snapshot to ${fullPath}...`);
    // Нативний метод V8: скидає дані пам'яті безпосередньо на диск через шар C++ без алокацій у купі JS
    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: зняття Heap Snapshot на вимогу без зупинки обробки запитів
  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.`);
}