pgserve 1.1.3 → 1.1.4

package/src/stats-collector.js

@@ -0,0 +1,267 @@
+/**
+ * Stats Collector - Centralized statistics gathering for pgserve
+ *
+ * Aggregates stats from:
+ * - Router (active connections)
+ * - PostgreSQL Manager (databases, storage)
+ * - PostgreSQL internals (pg_stat_activity, pg_stat_database)
+ * - Process (memory, uptime)
+ */
+
+// CPU sampling threshold - avoid noise from too-frequent calls
+const CPU_SAMPLE_MIN_INTERVAL_MS = 100;
+
+// /proc/diskstats minimum fields per device line
+// Fields: major minor device reads rd_merged rd_sectors rd_ms writes wr_merged wr_sectors wr_ms io_in_progress io_ms weighted_io_ms
+const PROC_DISKSTATS_MIN_FIELDS = 14;
+
+export class StatsCollector {
+  constructor(options = {}) {
+    this.pgManager = options.pgManager;
+    this.router = options.router;
+    this.clusterStats = options.clusterStats; // Function that returns cluster stats
+    this.logger = options.logger;
+
+    // Override values for cluster mode where router is null
+    this.serverPort = options.port;
+    this.serverHost = options.host;
+
+    // Cache to avoid over-querying (configurable for different monitoring needs)
+    this.cache = null;
+    this.cacheTime = 0;
+    this.cacheTTL = options.cacheTTL || 1000; // Default 1s cache
+
+    // CPU tracking
+    this.lastCpuUsage = process.cpuUsage();
+    this.lastCpuTime = Date.now();
+
+    // Disk I/O tracking (Linux)
+    this.lastDiskStats = null;
+    this.lastDiskTime = 0;
+  }
+
+  /**
+   * Collect all available stats
+   * @returns {Promise<StatsSnapshot>}
+   */
+  async collect() {
+    // Return cached if recent
+    if (this.cache && Date.now() - this.cacheTime < this.cacheTTL) {
+      return this.cache;
+    }
+
+    const pgStats = this.pgManager?.getStats?.() || {};
+    const routerStats = this.router?.getStats?.() || {};
+    // Prefer clusterStats (cluster mode aggregates from all workers)
+    // Fall back to routerStats (single-process mode)
+    const clusterStats = this.clusterStats?.() || null;
+
+    const snapshot = {
+      timestamp: Date.now(),
+      uptime: process.uptime(),
+
+      // Connection stats - cluster mode has aggregated stats, single-process uses router directly
+      connections: {
+        active: clusterStats?.connections?.active ?? routerStats.activeConnections ?? 0,
+        totalConnected: clusterStats?.connections?.totalConnected ?? 0,
+        totalDisconnected: clusterStats?.connections?.totalDisconnected ?? 0,
+        max: this.router?.maxConnections || 1000
+      },
+
+      // Server config
+      server: {
+        port: this.serverPort || routerStats.port || this.router?.port || 8432,
+        host: this.serverHost || routerStats.host || this.router?.host || '127.0.0.1',
+        pgPort: routerStats.pgPort || pgStats.port || 0,
+        memoryMode: this.router?.memoryMode ?? !pgStats.persistent,
+        useRam: this.pgManager?.useRam || false
+      },
+
+      // PostgreSQL manager stats
+      postgres: {
+        port: pgStats.port,
+        databases: pgStats.databases || [],
+        databaseDir: pgStats.databaseDir,
+        socketDir: pgStats.socketDir,
+        socketPath: pgStats.socketPath,
+        persistent: pgStats.persistent
+      },
+
+      // Cluster stats (if in cluster mode)
+      cluster: clusterStats ? {
+        workers: clusterStats.workers,
+        pids: clusterStats.pids,
+        workerStats: clusterStats.workerStats || {}
+      } : null,
+
+      // PostgreSQL internals (pg_stat_*)
+      internals: await this.collectPgStats(),
+
+      // Process stats
+      process: {
+        pid: process.pid,
+        memory: process.memoryUsage(),
+        cpu: this.getCpuUsage()
+      },
+
+      // System stats (Linux)
+      system: await this.getSystemStats()
+    };
+
+    this.cache = snapshot;
+    this.cacheTime = Date.now();
+    return snapshot;
+  }
+
+  /**
+   * Get CPU usage percentage
+   */
+  getCpuUsage() {
+    const now = Date.now();
+    const elapsed = now - this.lastCpuTime;
+    if (elapsed < CPU_SAMPLE_MIN_INTERVAL_MS) return this.lastCpuPercent || 0;
+
+    const cpuUsage = process.cpuUsage(this.lastCpuUsage);
+    const totalMicros = cpuUsage.user + cpuUsage.system;
+    const elapsedMicros = elapsed * 1000; // Convert ms to microseconds
+
+    // CPU percentage (can be > 100% on multi-core)
+    const percent = (totalMicros / elapsedMicros) * 100;
+
+    this.lastCpuUsage = process.cpuUsage();
+    this.lastCpuTime = now;
+    this.lastCpuPercent = percent;
+
+    // Return raw percentage - can exceed 100% on multi-core systems
+    // Consumers (dashboard, etc.) can format/cap as needed for display
+    return percent;
+  }
+
+  /**
+   * Get system stats (Linux-specific)
+   */
+  async getSystemStats() {
+    const stats = {
+      loadAvg: null,
+      diskIO: null
+    };
+
+    try {
+      // Load average (works on Linux/macOS)
+      const os = await import('os');
+      const loadAvg = os.loadavg();
+      stats.loadAvg = {
+        '1m': loadAvg[0],
+        '5m': loadAvg[1],
+        '15m': loadAvg[2]
+      };
+
+      // Disk I/O stats (Linux only via /proc/diskstats)
+      if (process.platform === 'linux') {
+        const fs = await import('fs/promises');
+        try {
+          const diskstats = await fs.readFile('/proc/diskstats', 'utf8');
+          const now = Date.now();
+
+          // Parse diskstats - find main disk (sda, nvme0n1, vda, etc.)
+          let readSectors = 0;
+          let writeSectors = 0;
+          let readOps = 0;
+          let writeOps = 0;
+
+          for (const line of diskstats.split('\n')) {
+            const parts = line.trim().split(/\s+/);
+            if (parts.length < PROC_DISKSTATS_MIN_FIELDS) continue;
+
+            const device = parts[2];
+            // Match main disks (sda, sdb, nvme0n1, vda, etc.) but not partitions
+            if (/^(sd[a-z]|nvme\d+n\d+|vd[a-z])$/.test(device)) {
+              readOps += parseInt(parts[3]) || 0;
+              readSectors += parseInt(parts[5]) || 0;
+              writeOps += parseInt(parts[7]) || 0;
+              writeSectors += parseInt(parts[9]) || 0;
+            }
+          }
+
+          if (this.lastDiskStats && this.lastDiskTime) {
+            const elapsed = (now - this.lastDiskTime) / 1000; // seconds
+            if (elapsed > 0) {
+              const readDiff = readSectors - this.lastDiskStats.readSectors;
+              const writeDiff = writeSectors - this.lastDiskStats.writeSectors;
+              const readOpsDiff = readOps - this.lastDiskStats.readOps;
+              const writeOpsDiff = writeOps - this.lastDiskStats.writeOps;
+
+              // Sectors are typically 512 bytes
+              stats.diskIO = {
+                readMBps: ((readDiff * 512) / (1024 * 1024)) / elapsed,
+                writeMBps: ((writeDiff * 512) / (1024 * 1024)) / elapsed,
+                readIOPS: readOpsDiff / elapsed,
+                writeIOPS: writeOpsDiff / elapsed
+              };
+            }
+          }
+
+          this.lastDiskStats = { readSectors, writeSectors, readOps, writeOps };
+          this.lastDiskTime = now;
+        } catch (err) {
+          // /proc/diskstats not available (normal on non-Linux or restricted environments)
+          this.logger?.debug?.({ err: err.message }, 'Could not read /proc/diskstats');
+        }
+      }
+    } catch (err) {
+      // OS module or stats not available (normal on some platforms)
+      this.logger?.debug?.({ err: err.message }, 'Could not collect system stats');
+    }
+
+    return stats;
+  }
+
+  /**
+   * Query PostgreSQL internal statistics
+   */
+  async collectPgStats() {
+    // Get admin pool from pgManager
+    const adminPool = this.pgManager?.adminPool;
+    if (!adminPool) return null;
+
+    try {
+      // Query pg_stat_activity for connection details
+      const activity = await adminPool`
+        SELECT
+          count(*) FILTER (WHERE state = 'active') as active_queries,
+          count(*) FILTER (WHERE state = 'idle') as idle_connections,
+          count(*) as total_connections
+        FROM pg_stat_activity
+        WHERE datname IS NOT NULL
+      `;
+
+      // Query pg_stat_database for DB-level stats
+      const dbStats = await adminPool`
+        SELECT
+          datname,
+          numbackends,
+          xact_commit,
+          xact_rollback,
+          blks_read,
+          blks_hit,
+          tup_returned,
+          tup_fetched,
+          tup_inserted,
+          tup_updated,
+          tup_deleted
+        FROM pg_stat_database
+        WHERE datname NOT IN ('template0', 'template1')
+        ORDER BY numbackends DESC
+        LIMIT 10
+      `;
+
+      return {
+        activity: activity[0] || {},
+        databases: dbStats || []
+      };
+    } catch (err) {
+      this.logger?.debug?.({ err: err.message }, 'Failed to collect pg_stat_*');
+      return null;
+    }
+  }
+}

package/src/stats-dashboard.js

@@ -0,0 +1,382 @@
+/**
+ * Stats Dashboard - Real-time CLI monitoring display for pgserve
+ *
+ * htop-style in-place terminal updates showing:
+ * - Server info (endpoint, mode, uptime)
+ * - Connections (active, total, with progress bar)
+ * - Cluster workers (if in cluster mode)
+ * - PostgreSQL (databases, internal port)
+ * - PG Internals (backends, cache hit ratio)
+ * - Memory usage
+ *
+ * Supports TTY and non-TTY environments.
+ */
+
+// ANSI escape codes
+const ANSI = {
+  CLEAR_LINE: '\x1B[2K',
+  MOVE_UP: (n) => `\x1B[${n}A`,
+  HIDE_CURSOR: '\x1B[?25l',
+  SHOW_CURSOR: '\x1B[?25h',
+
+  // Colors
+  GREEN: '\x1B[32m',
+  YELLOW: '\x1B[33m',
+  CYAN: '\x1B[36m',
+  RED: '\x1B[31m',
+  MAGENTA: '\x1B[35m',
+  DIM: '\x1B[2m',
+  RESET: '\x1B[0m',
+  BOLD: '\x1B[1m',
+  INVERSE: '\x1B[7m'
+};
+
+// Color thresholds for progress bars and values (percentage of max)
+const THRESHOLD_WARN = 0.6;    // Yellow at 60%
+const THRESHOLD_CRITICAL = 0.8; // Red at 80%
+
+export class StatsDashboard {
+  /**
+   * @param {Object} options
+   * @param {number} [options.refreshInterval=2000] - Dashboard refresh interval in ms
+   * @param {() => Promise<StatsSnapshot>} [options.statsProvider] - Async function returning stats object
+   * @param {() => void} [options.onStop] - Callback when dashboard stops
+   */
+  constructor(options = {}) {
+    // Respects NO_COLOR env var (https://no-color.org/ standard)
+    this.enabled = process.stdout.isTTY && !process.env.NO_COLOR;
+    // Default 2s refresh for real-time feel (trade-off: higher CPU vs fresher data)
+    this.refreshInterval = options.refreshInterval || 2000;
+    this.statsProvider = options.statsProvider;
+    this.timer = null;
+    this.displayLines = 0;
+    this.lastStats = null;
+    this.startTime = Date.now();
+    this.onStop = options.onStop; // Optional callback when dashboard stops
+  }
+
+  /**
+   * Start the dashboard refresh loop
+   */
+  start() {
+    if (!this.enabled) {
+      console.log('[Stats Dashboard disabled - non-TTY environment]');
+      return;
+    }
+
+    // Hide cursor during dashboard display
+    process.stdout.write(ANSI.HIDE_CURSOR);
+
+    // Initial render
+    this.render();
+
+    // Start refresh timer
+    this.timer = setInterval(() => this.render(), this.refreshInterval);
+
+    // Handle terminal resize
+    process.stdout.on('resize', () => this.render());
+
+    // Restore cursor on process exit (non-signal exits)
+    // Note: SIGINT/SIGTERM are handled by the main process for graceful shutdown
+    process.on('exit', () => {
+      if (this.enabled) {
+        process.stdout.write(ANSI.SHOW_CURSOR);
+      }
+    });
+  }
+
+  /**
+   * Stop the dashboard
+   */
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.enabled) {
+      process.stdout.write(ANSI.SHOW_CURSOR);
+      // Move below dashboard area
+      if (this.displayLines > 0) {
+        console.log('\n');
+      }
+    }
+    if (this.onStop) {
+      this.onStop();
+    }
+  }
+
+  /**
+   * Render the dashboard
+   */
+  async render() {
+    if (!this.statsProvider) return;
+
+    try {
+      const stats = await this.statsProvider();
+      this.lastStats = stats;
+      this.draw(stats);
+    } catch (err) {
+      // Don't crash on stats collection failure - use cached stats if available
+      // Only log once to avoid spam during persistent issues
+      if (!this._lastError || this._lastError !== err.message) {
+        this._lastError = err.message;
+        console.error(`[stats] Collection failed: ${err.message}`);
+      }
+      if (this.lastStats) {
+        this.draw(this.lastStats);
+      }
+    }
+  }
+
+  /**
+   * Draw the dashboard to terminal
+   */
+  draw(stats) {
+    const output = this.buildDisplay(stats);
+
+    // Count actual lines (including newlines within sections)
+    const totalLines = output.split('\n').length;
+
+    // Clear previous output and redraw
+    if (this.displayLines > 0) {
+      process.stdout.write(ANSI.MOVE_UP(this.displayLines));
+    }
+
+    // Write each line with clear
+    for (const line of output.split('\n')) {
+      process.stdout.write(ANSI.CLEAR_LINE + line + '\n');
+    }
+
+    this.displayLines = totalLines;
+  }
+
+  /**
+   * Build the display lines
+   */
+  buildDisplay(stats) {
+    const lines = [];
+    // Use actual terminal width (no arbitrary cap - users with wide terminals get wider display)
+    const width = process.stdout.columns || 80;
+
+    // Header bar
+    lines.push(this.headerBar(width));
+    lines.push('');
+
+    // Server info section
+    // Determine storage mode label
+    let modeLabel = 'Persistent';
+    if (stats.server?.memoryMode) {
+      modeLabel = stats.server?.useRam ? 'RAM (/dev/shm)' : 'Ephemeral (temp)';
+    }
+
+    lines.push(this.section('SERVER', [
+      `${ANSI.DIM}Endpoint:${ANSI.RESET}  postgresql://${stats.server?.host || '127.0.0.1'}:${stats.server?.port || 8432}/<db>`,
+      `${ANSI.DIM}Mode:${ANSI.RESET}      ${modeLabel}`,
+      `${ANSI.DIM}Uptime:${ANSI.RESET}    ${this.formatUptime(stats.uptime || 0)}`
+    ]));
+    lines.push('');
+
+    // Connections section
+    const connActive = stats.connections?.active || 0;
+    const connMax = stats.connections?.max || 1000;
+    const connTotal = stats.connections?.totalConnected || 0;
+    const connDisc = stats.connections?.totalDisconnected || 0;
+
+    const connLines = [
+      `${ANSI.DIM}Active:${ANSI.RESET}    ${this.colorValue(connActive, connMax * THRESHOLD_WARN, connMax * THRESHOLD_CRITICAL)} / ${connMax}  ${this.miniBar(connActive, connMax, 20)}`
+    ];
+
+    if (connTotal > 0 || connDisc > 0) {
+      connLines.push(`${ANSI.DIM}Total:${ANSI.RESET}     ${this.formatNumber(connTotal)} connected, ${this.formatNumber(connDisc)} disconnected`);
+    }
+
+    lines.push(this.section('CONNECTIONS', connLines));
+    lines.push('');
+
+    // Cluster section (if applicable)
+    if (stats.cluster && stats.cluster.workers > 0) {
+      const workerLines = [`${ANSI.DIM}Workers:${ANSI.RESET}   ${stats.cluster.workers} processes`];
+
+      if (stats.cluster.workerStats && Object.keys(stats.cluster.workerStats).length > 0) {
+        const workerEntries = Object.entries(stats.cluster.workerStats);
+        // Show up to 4 workers inline
+        for (const [id, ws] of workerEntries.slice(0, 4)) {
+          workerLines.push(`  ${ANSI.DIM}Worker ${id}:${ANSI.RESET} ${ws.connections || 0} conn (PID ${ws.pid})`);
+        }
+        if (workerEntries.length > 4) {
+          workerLines.push(`  ${ANSI.DIM}... and ${workerEntries.length - 4} more workers${ANSI.RESET}`);
+        }
+      }
+
+      lines.push(this.section('CLUSTER', workerLines));
+      lines.push('');
+    }
+
+    // PostgreSQL section
+    if (stats.postgres) {
+      const pgLines = [
+        `${ANSI.DIM}Internal Port:${ANSI.RESET} ${stats.postgres.port || 'N/A'}`,
+        `${ANSI.DIM}Databases:${ANSI.RESET}     ${stats.postgres.databases?.length || 0}`
+      ];
+
+      // Show database list if not too many
+      const dbs = stats.postgres.databases || [];
+      if (dbs.length > 0 && dbs.length <= 5) {
+        pgLines.push(`  ${ANSI.DIM}${ANSI.RESET} ${dbs.join(', ')}`);
+      } else if (dbs.length > 5) {
+        pgLines.push(`  ${ANSI.DIM}${ANSI.RESET} ${dbs.slice(0, 5).join(', ')}${ANSI.DIM}... (+${dbs.length - 5})${ANSI.RESET}`);
+      }
+
+      lines.push(this.section('POSTGRESQL', pgLines));
+      lines.push('');
+    }
+
+    // PostgreSQL Internals section (pg_stat_*)
+    if (stats.internals) {
+      const intLines = [];
+
+      if (stats.internals.activity) {
+        const a = stats.internals.activity;
+        intLines.push(`${ANSI.DIM}Backends:${ANSI.RESET}      ${a.total_connections || 0} total, ${a.active_queries || 0} active, ${a.idle_connections || 0} idle`);
+      }
+
+      if (stats.internals.databases?.length > 0) {
+        intLines.push(`${ANSI.DIM}Top DBs by connections:${ANSI.RESET}`);
+        for (const db of stats.internals.databases.slice(0, 3)) {
+          // Use BigInt for precision on high-traffic systems (PostgreSQL returns 8-byte integers)
+          const blksHit = BigInt(db.blks_hit || 0);
+          const blksRead = BigInt(db.blks_read || 0);
+          const total = blksHit + blksRead;
+          // Calculate ratio safely: multiply by 1000 first, then convert to Number for final formatting
+          const hitRatio = total > 0n
+            ? (Number((blksHit * 1000n) / total) / 10).toFixed(1)
+            : '0.0';
+          intLines.push(`  ${ANSI.CYAN}${db.datname}${ANSI.RESET}: ${db.numbackends} conn, ${hitRatio}% cache hit`);
+        }
+      }
+
+      if (intLines.length > 0) {
+        lines.push(this.section('PG INTERNALS', intLines));
+        lines.push('');
+      }
+    }
+
+    // System resources section
+    const resourceLines = [];
+
+    // CPU usage
+    if (stats.process?.cpu !== undefined) {
+      const cpuPct = stats.process.cpu;
+      resourceLines.push(`${ANSI.DIM}CPU:${ANSI.RESET}       ${cpuPct.toFixed(1)}%  ${this.miniBar(cpuPct, 100, 15)}`);
+    }
+
+    // Load average
+    if (stats.system?.loadAvg) {
+      const load = stats.system.loadAvg;
+      resourceLines.push(`${ANSI.DIM}Load Avg:${ANSI.RESET}  ${load['1m'].toFixed(2)} / ${load['5m'].toFixed(2)} / ${load['15m'].toFixed(2)}`);
+    }
+
+    // Memory
+    if (stats.process?.memory) {
+      const mem = stats.process.memory;
+      const rssMB = (mem.rss / 1024 / 1024).toFixed(1);
+      resourceLines.push(`${ANSI.DIM}Memory:${ANSI.RESET}    ${rssMB} MB RSS`);
+    }
+
+    // Disk I/O
+    if (stats.system?.diskIO) {
+      const io = stats.system.diskIO;
+      const readSpeed = io.readMBps.toFixed(1);
+      const writeSpeed = io.writeMBps.toFixed(1);
+      const readIOPS = io.readIOPS.toFixed(0);
+      const writeIOPS = io.writeIOPS.toFixed(0);
+      resourceLines.push(`${ANSI.DIM}Disk I/O:${ANSI.RESET}  R: ${readSpeed} MB/s (${readIOPS} IOPS) | W: ${writeSpeed} MB/s (${writeIOPS} IOPS)`);
+    }
+
+    if (resourceLines.length > 0) {
+      lines.push(this.section('RESOURCES', resourceLines));
+      lines.push('');
+    }
+
+    // Footer
+    lines.push(`${ANSI.DIM}Last update: ${new Date().toLocaleTimeString()} | Refresh: ${this.refreshInterval / 1000}s | Press Ctrl+C to exit${ANSI.RESET}`);
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Render header bar
+   */
+  headerBar(width) {
+    const title = ' pgserve stats ';
+    const padding = Math.max(0, Math.floor((width - title.length) / 2));
+    const rightPad = Math.max(0, width - padding - title.length);
+    return `${ANSI.INVERSE}${' '.repeat(padding)}${title}${' '.repeat(rightPad)}${ANSI.RESET}`;
+  }
+
+  /**
+   * Render a section with title and lines
+   */
+  section(title, contentLines) {
+    const header = `${ANSI.BOLD}${ANSI.CYAN}[${title}]${ANSI.RESET}`;
+    return [header, ...contentLines.map(l => '  ' + l)].join('\n');
+  }
+
+  /**
+   * Color a value based on thresholds
+   */
+  colorValue(value, warnThreshold, errorThreshold) {
+    if (value >= errorThreshold) {
+      return `${ANSI.RED}${value}${ANSI.RESET}`;
+    } else if (value >= warnThreshold) {
+      return `${ANSI.YELLOW}${value}${ANSI.RESET}`;
+    }
+    return `${ANSI.GREEN}${value}${ANSI.RESET}`;
+  }
+
+  /**
+   * Render mini progress bar
+   */
+  miniBar(current, max, width = 10) {
+    // Ensure valid numbers
+    const safeMax = Math.max(1, Number(max) || 1);
+    const safeCurrent = Math.max(0, Math.min(Number(current) || 0, safeMax));
+
+    const pct = safeCurrent / safeMax;
+    // filled is clamped to [0, width], so (width - filled) is always non-negative
+    const filled = Math.max(0, Math.min(width, Math.round(pct * width)));
+    const empty = width - filled;
+
+    let color = ANSI.GREEN;
+    if (pct > THRESHOLD_CRITICAL) color = ANSI.RED;
+    else if (pct > THRESHOLD_WARN) color = ANSI.YELLOW;
+
+    // Use Unicode block characters for progress bar
+    const filledChar = '\u2588'; // Full block
+    const emptyChar = '\u2591';  // Light shade
+
+    return `${color}[${filledChar.repeat(filled)}${ANSI.DIM}${emptyChar.repeat(empty)}${ANSI.RESET}${color}]${ANSI.RESET}`;
+  }
+
+  /**
+   * Format uptime as human-readable string
+   */
+  formatUptime(seconds) {
+    const days = Math.floor(seconds / 86400);
+    const hours = Math.floor((seconds % 86400) / 3600);
+    const mins = Math.floor((seconds % 3600) / 60);
+    const secs = Math.floor(seconds % 60);
+
+    if (days > 0) return `${days}d ${hours}h ${mins}m`;
+    if (hours > 0) return `${hours}h ${mins}m ${secs}s`;
+    if (mins > 0) return `${mins}m ${secs}s`;
+    return `${secs}s`;
+  }
+
+  /**
+   * Format large numbers with commas
+   */
+  formatNumber(num) {
+    return num.toLocaleString();
+  }
+}