postgresai 0.14.0 → 0.15.0-dev.10

package/instances.demo.yml

@@ -0,0 +1,14 @@
+# Demo PostgreSQL instance for `pgai mon local-install --demo`
+# This file is copied to instances.yml during demo mode setup.
+
+- name: target_database
+  conn_str: postgresql://monitor:monitor_pass@target-db:5432/target_database
+  preset_metrics: full
+  custom_metrics:
+  is_enabled: true
+  group: default
+  custom_tags:
+    env: demo
+    cluster: local
+    node_name: node-01
+    sink_type: ~sink_type~  # sed token substituted by generate-pgwatch-sources.sh; values: postgres, prometheus

package/lib/checkup-api.ts

@@ -1,3 +1,4 @@
+import * as http from "http";
 import * as https from "https";
 import { URL } from "url";
 import { normalizeBaseUrl } from "./util";
@@ -27,7 +28,7 @@ function isRetryableError(err: unknown): boolean {
     // Retry on server errors (5xx), not on client errors (4xx)
     return err.statusCode >= 500 && err.statusCode < 600;
   }
-  
+
   // Check for Node.js error codes (works on Error and Error-like objects)
   if (typeof err === "object" && err !== null && "code" in err) {
     const code = String((err as { code: unknown }).code);
@@ -35,7 +36,7 @@ function isRetryableError(err: unknown): boolean {
       return true;
     }
   }
-  
+
   if (err instanceof Error) {
     const msg = err.message.toLowerCase();
     // Retry on network-related errors based on message content
@@ -49,7 +50,7 @@ function isRetryableError(err: unknown): boolean {
       msg.includes("network")
     );
   }
-  
+
   return false;
 }
 
@@ -226,7 +227,25 @@ async function postRpc<T>(params: {
       resolve(value);
     };
 
-    const req = https.request(
+    // Transport is picked from the URL protocol so the CLI can talk to a
+    // local-dev PostgREST over plain HTTP. Production URLs are always HTTPS;
+    // to guard against typos (e.g. a missing 's' in 'https://') silently
+    // leaking the API key in cleartext, refuse HTTP to non-loopback hosts
+    // unless the operator explicitly opts in via CHECKUP_ALLOW_HTTP=1.
+    if (url.protocol === "http:") {
+      // WHATWG URL keeps IPv6 literals bracketed in .hostname
+      // (e.g. `[::1]`), so strip the brackets before matching the allowlist.
+      const hostname = url.hostname.replace(/^\[|\]$/g, "");
+      const isLoopback = ["localhost", "127.0.0.1", "::1"].includes(hostname);
+      if (!isLoopback && process.env.CHECKUP_ALLOW_HTTP !== "1") {
+        throw new Error(
+          `Refusing to send API key over plaintext HTTP to '${url.host}'. ` +
+          `Use https://, a loopback hostname, or set CHECKUP_ALLOW_HTTP=1.`
+        );
+      }
+    }
+    const transport = url.protocol === "http:" ? http : https;
+    const req = transport.request(
       url,
       {
         method: "POST",
@@ -277,7 +296,7 @@ async function postRpc<T>(params: {
       req.destroy();  // Backup: ensure request is terminated
       settledReject(new Error(`RPC ${rpcName} timed out after ${timeoutMs}ms (no response)`));
     }, timeoutMs);
-    
+
     req.on("error", (err: Error) => {
       // Handle abort as timeout (may already be rejected by timeout handler)
       if (err.name === "AbortError" || (err as any).code === "ABORT_ERR") {
@@ -295,7 +314,7 @@ async function postRpc<T>(params: {
         settledReject(err);
       }
     });
-    
+
     req.write(body);
     req.end();
   });

package/lib/checkup.ts

@@ -243,6 +243,50 @@ export interface RedundantIndex {
   redundant_to_parse_error?: string;
 }
 
+/**
+ * I/O statistics by backend type (I001) - matches I001.schema.json backendIOStats
+ */
+export interface BackendIOStats {
+  backend_type: string;
+  reads: number;
+  /** Read MiB. The historical `_mb` suffix is retained for schema compatibility. */
+  read_bytes_mb: number;
+  read_time_ms: number;
+  writes: number;
+  /** Written MiB. The historical `_mb` suffix is retained for schema compatibility. */
+  write_bytes_mb: number;
+  write_time_ms: number;
+  writebacks: number;
+  /** Writeback MiB. The historical `_mb` suffix is retained for schema compatibility. */
+  writeback_bytes_mb: number;
+  writeback_time_ms: number;
+  fsyncs: number;
+  fsync_time_ms: number;
+  /** Relation extension operations reported by pg_stat_io for PostgreSQL 16+. */
+  extends?: number;
+  /** Extended MiB; PG16 derives extends * op_bytes, PG18+ uses native extend_bytes. */
+  extend_bytes_mb?: number;
+  hits: number;
+  evictions: number;
+  reuses: number;
+}
+
+/**
+ * I/O statistics analysis summary (I001)
+ */
+export interface IOAnalysis {
+  total_read_mb: number;
+  total_write_mb: number;
+  /** read_time_ms + write_time_ms across backends. Excludes writeback and fsync time. */
+  total_io_time_ms: number;
+  /** Buffer hit ratio: hits / (hits + reads) * 100. */
+  read_hit_ratio_pct: number;
+  /** Average read latency, or null when there are no reads. */
+  avg_read_time_ms: number | null;
+  /** Average write latency, or null when there are no writes. */
+  avg_write_time_ms: number | null;
+}
+
 /**
  * Node result for reports
  */
@@ -284,7 +328,7 @@ export function parseVersionNum(versionNum: string): { major: string; minor: str
   } catch (err) {
     // parseInt shouldn't throw, but handle edge cases defensively
     const errorMsg = err instanceof Error ? err.message : String(err);
-    console.log(`[parseVersionNum] Warning: Failed to parse "${versionNum}": ${errorMsg}`);
+    console.error(`[parseVersionNum] Warning: Failed to parse "${versionNum}": ${errorMsg}`);
     return { major: "", minor: "" };
   }
 }
@@ -729,7 +773,7 @@ export async function getStatsReset(client: Client, pgMajorVersion: number = 16)
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
     postmasterStartupError = `Failed to query postmaster start time: ${errorMsg}`;
-    console.log(`[getStatsReset] Warning: ${postmasterStartupError}`);
+    console.error(`[getStatsReset] Warning: ${postmasterStartupError}`);
   }
   
   const statsResult: StatsReset = {
@@ -811,7 +855,7 @@ export async function getRedundantIndexes(client: Client, pgMajorVersion: number
       const errorMsg = err instanceof Error ? err.message : String(err);
       const indexName = String(transformed.index_name || "unknown");
       parseError = `Failed to parse redundant_to_json: ${errorMsg}`;
-      console.log(`[H004] Warning: ${parseError} for index "${indexName}"`);
+      console.error(`[H004] Warning: ${parseError} for index "${indexName}"`);
     }
     
     const result: RedundantIndex = {
@@ -905,7 +949,7 @@ function resolveBuildTs(): string | null {
     // package.json not found is expected in some environments (e.g., bundled) - debug only
     if (process.env.DEBUG) {
       const errorMsg = err instanceof Error ? err.message : String(err);
-      console.log(`[resolveBuildTs] Could not stat package.json, using current time: ${errorMsg}`);
+      console.error(`[resolveBuildTs] Could not stat package.json, using current time: ${errorMsg}`);
     }
     return new Date().toISOString();
   }
@@ -1103,7 +1147,7 @@ async function generateD004(client: Client, nodeName: string): Promise<Report> {
     }
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
-    console.log(`[D004] Error querying pg_stat_statements: ${errorMsg}`);
+    console.error(`[D004] Error querying pg_stat_statements: ${errorMsg}`);
     pgssError = errorMsg;
   }
 
@@ -1156,7 +1200,7 @@ async function generateD004(client: Client, nodeName: string): Promise<Report> {
     }
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
-    console.log(`[D004] Error querying pg_stat_kcache: ${errorMsg}`);
+    console.error(`[D004] Error querying pg_stat_kcache: ${errorMsg}`);
     kcacheError = errorMsg;
   }
 
@@ -1242,6 +1286,236 @@ async function generateF001(client: Client, nodeName: string): Promise<Report> {
   return report;
 }
 
+/**
+ * Generate F004 report - Autovacuum: heap bloat (estimated)
+ *
+ * Estimates table bloat based on statistical analysis of table pages vs expected pages.
+ * Uses pg_stats for column statistics to estimate row sizes.
+ * SQL loaded from config/pgwatch-prometheus/metrics.yml (pg_table_bloat metric).
+ */
+async function generateF004(client: Client, nodeName: string): Promise<Report> {
+  const report = createBaseReport("F004", "Autovacuum: heap bloat (estimated)", nodeName);
+  const postgresVersion = await getPostgresVersion(client);
+  const pgMajorVersion = parseInt(postgresVersion.server_major_ver, 10);
+
+  interface BloatedTable {
+    schema_name: string;
+    table_name: string;
+    real_size: number;
+    extra_size: number;
+    extra_pct: number;
+    bloat_size: number;
+    bloat_pct: number;
+    fillfactor: number;
+    last_vacuum: string | null;
+    last_vacuum_epoch: number;
+    real_size_pretty: string;
+    extra_size_pretty: string;
+    bloat_size_pretty: string;
+  }
+
+  let bloatedTables: BloatedTable[] = [];
+
+  try {
+    // Get bloat data
+    const sql = getMetricSql(METRIC_NAMES.F004, pgMajorVersion);
+    const bloatResult = await client.query(sql);
+
+    // Get vacuum stats for all tables
+    const vacuumStatsResult = await client.query(`
+      SELECT schemaname, relname, last_vacuum, last_autovacuum
+      FROM pg_stat_user_tables
+    `);
+    const vacuumStats = new Map<string, { last_vacuum: string | null; last_vacuum_epoch: number }>();
+    for (const row of vacuumStatsResult.rows) {
+      const key = `${row.schemaname}.${row.relname}`;
+      // Use last_autovacuum if last_vacuum is null, otherwise prefer last_vacuum
+      const vacuumTime = row.last_vacuum || row.last_autovacuum;
+      vacuumStats.set(key, {
+        last_vacuum: vacuumTime ? new Date(vacuumTime).toISOString() : null,
+        last_vacuum_epoch: vacuumTime ? Math.floor(new Date(vacuumTime).getTime() / 1000) : 0,
+      });
+    }
+
+    bloatedTables = bloatResult.rows.map((row) => {
+      const t = transformMetricRow(row);
+      const schemaName = String(t.schemaname || "");
+      const tableName = String(t.tblname || "");
+      const realSizeBytes = Math.round((parseFloat(String(t.real_size_mib)) || 0) * 1024 * 1024);
+      const extraSize = parseInt(String(t.extra_size || 0), 10);
+      const bloatSize = parseInt(String(t.bloat_size || 0), 10);
+
+      const vacuumInfo = vacuumStats.get(`${schemaName}.${tableName}`) || {
+        last_vacuum: null,
+        last_vacuum_epoch: 0,
+      };
+
+      return {
+        schema_name: schemaName,
+        table_name: tableName,
+        real_size: realSizeBytes,
+        extra_size: extraSize,
+        extra_pct: parseFloat(String(t.extra_pct)) || 0,
+        bloat_size: bloatSize,
+        bloat_pct: parseFloat(String(t.bloat_pct)) || 0,
+        fillfactor: parseInt(String(t.fillfactor || 100), 10),
+        last_vacuum: vacuumInfo.last_vacuum,
+        last_vacuum_epoch: vacuumInfo.last_vacuum_epoch,
+        real_size_pretty: formatBytes(realSizeBytes),
+        extra_size_pretty: formatBytes(extraSize),
+        bloat_size_pretty: formatBytes(bloatSize),
+      };
+    });
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    console.error(`[F004] Error estimating table bloat: ${errorMsg}`);
+    if (errorMsg.includes("postgres_ai.")) {
+      console.error(`  Hint: Run "postgresai prepare-db <connection>" to create required objects.`);
+    }
+  }
+
+  // Get database info
+  const { datname: dbName, size_bytes: dbSizeBytes } = await getCurrentDatabaseInfo(client, pgMajorVersion);
+
+  // Calculate totals
+  const totalCount = bloatedTables.length;
+  const totalBloatSizeBytes = bloatedTables.reduce((sum, t) => sum + t.bloat_size, 0);
+
+  const dbEntry = {
+    bloated_tables: bloatedTables,
+    total_count: totalCount,
+    total_bloat_size_bytes: totalBloatSizeBytes,
+    total_bloat_size_pretty: formatBytes(totalBloatSizeBytes),
+    database_size_bytes: dbSizeBytes,
+    database_size_pretty: formatBytes(dbSizeBytes),
+  };
+
+  report.results[nodeName] = {
+    data: { [dbName]: dbEntry },
+    postgres_version: postgresVersion,
+  };
+
+  return report;
+}
+
+/**
+ * Generate F005 report - Autovacuum: index bloat (estimated)
+ *
+ * Estimates B-tree index bloat based on statistical analysis of index pages vs expected pages.
+ * SQL loaded from config/pgwatch-prometheus/metrics.yml (pg_btree_bloat metric).
+ */
+async function generateF005(client: Client, nodeName: string): Promise<Report> {
+  const report = createBaseReport("F005", "Autovacuum: index bloat (estimated)", nodeName);
+  const postgresVersion = await getPostgresVersion(client);
+  const pgMajorVersion = parseInt(postgresVersion.server_major_ver, 10);
+
+  interface BloatedIndex {
+    schema_name: string;
+    table_name: string;
+    index_name: string;
+    real_size: number;
+    table_size: number;
+    extra_size: number;
+    extra_pct: number;
+    bloat_size: number;
+    bloat_pct: number;
+    fillfactor: number;
+    last_vacuum: string | null;
+    last_vacuum_epoch: number;
+    real_size_pretty: string;
+    table_size_pretty: string;
+    extra_size_pretty: string;
+    bloat_size_pretty: string;
+  }
+
+  let bloatedIndexes: BloatedIndex[] = [];
+
+  try {
+    // Get bloat data
+    const sql = getMetricSql(METRIC_NAMES.F005, pgMajorVersion);
+    const bloatResult = await client.query(sql);
+
+    // Get vacuum stats for all tables (indexes inherit vacuum time from their table)
+    const vacuumStatsResult = await client.query(`
+      SELECT schemaname, relname, last_vacuum, last_autovacuum
+      FROM pg_stat_user_tables
+    `);
+    const vacuumStats = new Map<string, { last_vacuum: string | null; last_vacuum_epoch: number }>();
+    for (const row of vacuumStatsResult.rows) {
+      const key = `${row.schemaname}.${row.relname}`;
+      const vacuumTime = row.last_vacuum || row.last_autovacuum;
+      vacuumStats.set(key, {
+        last_vacuum: vacuumTime ? new Date(vacuumTime).toISOString() : null,
+        last_vacuum_epoch: vacuumTime ? Math.floor(new Date(vacuumTime).getTime() / 1000) : 0,
+      });
+    }
+
+    bloatedIndexes = bloatResult.rows.map((row) => {
+      const t = transformMetricRow(row);
+      const schemaName = String(t.schemaname || "");
+      const tableName = String(t.tblname || "");
+      const indexName = String(t.idxname || "");
+      const realSizeBytes = Math.round((parseFloat(String(t.real_size_mib)) || 0) * 1024 * 1024);
+      const tableSizeBytes = Math.round((parseFloat(String(t.table_size_mib)) || 0) * 1024 * 1024);
+      const extraSize = parseInt(String(t.extra_size || 0), 10);
+      const bloatSize = parseInt(String(t.bloat_size || 0), 10);
+
+      const vacuumInfo = vacuumStats.get(`${schemaName}.${tableName}`) || {
+        last_vacuum: null,
+        last_vacuum_epoch: 0,
+      };
+
+      return {
+        schema_name: schemaName,
+        table_name: tableName,
+        index_name: indexName,
+        real_size: realSizeBytes,
+        table_size: tableSizeBytes,
+        extra_size: extraSize,
+        extra_pct: parseFloat(String(t.extra_pct)) || 0,
+        bloat_size: bloatSize,
+        bloat_pct: parseFloat(String(t.bloat_pct)) || 0,
+        fillfactor: parseInt(String(t.fillfactor || 90), 10),
+        last_vacuum: vacuumInfo.last_vacuum,
+        last_vacuum_epoch: vacuumInfo.last_vacuum_epoch,
+        real_size_pretty: formatBytes(realSizeBytes),
+        table_size_pretty: formatBytes(tableSizeBytes),
+        extra_size_pretty: formatBytes(extraSize),
+        bloat_size_pretty: formatBytes(bloatSize),
+      };
+    });
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    console.error(`[F005] Error estimating index bloat: ${errorMsg}`);
+    if (errorMsg.includes("postgres_ai.")) {
+      console.error(`  Hint: Run "postgresai prepare-db <connection>" to create required objects.`);
+    }
+  }
+
+  // Get database info
+  const { datname: dbName, size_bytes: dbSizeBytes } = await getCurrentDatabaseInfo(client, pgMajorVersion);
+
+  // Calculate totals
+  const totalCount = bloatedIndexes.length;
+  const totalBloatSizeBytes = bloatedIndexes.reduce((sum, idx) => sum + idx.bloat_size, 0);
+
+  const dbEntry = {
+    bloated_indexes: bloatedIndexes,
+    total_count: totalCount,
+    total_bloat_size_bytes: totalBloatSizeBytes,
+    total_bloat_size_pretty: formatBytes(totalBloatSizeBytes),
+    database_size_bytes: dbSizeBytes,
+    database_size_pretty: formatBytes(dbSizeBytes),
+  };
+
+  report.results[nodeName] = {
+    data: { [dbName]: dbEntry },
+    postgres_version: postgresVersion,
+  };
+
+  return report;
+}
+
 /**
  * Generate G001 report - Memory-related settings
  */
@@ -1340,7 +1614,7 @@ async function generateG001(client: Client, nodeName: string): Promise<Report> {
     }
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
-    console.log(`[G001] Error calculating memory usage: ${errorMsg}`);
+    console.error(`[G001] Error calculating memory usage: ${errorMsg}`);
     memoryError = errorMsg;
   }
 
@@ -1418,7 +1692,7 @@ async function generateG003(client: Client, nodeName: string): Promise<Report> {
     }
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
-    console.log(`[G003] Error querying deadlock stats: ${errorMsg}`);
+    console.error(`[G003] Error querying deadlock stats: ${errorMsg}`);
     deadlockError = errorMsg;
   }
 
@@ -1434,6 +1708,186 @@ async function generateG003(client: Client, nodeName: string): Promise<Report> {
   return report;
 }
 
+/**
+ * Get I/O statistics from pg_stat_io (PostgreSQL 16+).
+ * Uses 'pg_stat_io' metric from metrics.yml.
+ *
+ * @param client - Connected PostgreSQL client
+ * @param pgMajorVersion - PostgreSQL major version; defaults to 0 so omitted versions return unavailable
+ * @param metricSqlOverride - Optional SQL override; empty or placeholder SQL returns [] without querying
+ * @returns Array of I/O stats by backend type, or empty array if unavailable
+ */
+export async function getIOStatistics(
+  client: Client,
+  pgMajorVersion: number = 0,
+  metricSqlOverride?: string
+): Promise<BackendIOStats[]> {
+  // pg_stat_io requires PostgreSQL 16+
+  if (pgMajorVersion < 16) {
+    return [];
+  }
+
+  try {
+    const sql = metricSqlOverride ?? getMetricSql(METRIC_NAMES.I001, pgMajorVersion);
+    // Skip if metric returns empty/placeholder SQL
+    if (!sql || sql.trim().startsWith(";")) {
+      return [];
+    }
+
+    const result = await client.query(sql);
+    return result.rows.map((row) => {
+      const transformed = transformMetricRow(row);
+      return {
+        backend_type: String(transformed.backend_type || "unknown"),
+        reads: parseInt(String(transformed.reads || 0), 10),
+        read_bytes_mb: parseInt(String(transformed.read_bytes_mb || 0), 10),
+        read_time_ms: parseInt(String(transformed.read_time_ms || 0), 10),
+        writes: parseInt(String(transformed.writes || 0), 10),
+        write_bytes_mb: parseInt(String(transformed.write_bytes_mb || 0), 10),
+        write_time_ms: parseInt(String(transformed.write_time_ms || 0), 10),
+        writebacks: parseInt(String(transformed.writebacks || 0), 10),
+        writeback_bytes_mb: parseInt(String(transformed.writeback_bytes_mb || 0), 10),
+        writeback_time_ms: parseInt(String(transformed.writeback_time_ms || 0), 10),
+        fsyncs: parseInt(String(transformed.fsyncs || 0), 10),
+        fsync_time_ms: parseInt(String(transformed.fsync_time_ms || 0), 10),
+        extends: parseInt(String(transformed.extends || 0), 10),
+        extend_bytes_mb: parseInt(String(transformed.extend_bytes_mb || 0), 10),
+        hits: parseInt(String(transformed.hits || 0), 10),
+        evictions: parseInt(String(transformed.evictions || 0), 10),
+        reuses: parseInt(String(transformed.reuses || 0), 10),
+      };
+    });
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    console.log(`[I001] Error fetching I/O statistics: ${errorMsg}`);
+    return [];
+  }
+}
+
+/**
+ * Generate I001 report - I/O statistics (pg_stat_io)
+ *
+ * This report collects I/O statistics from pg_stat_io (PostgreSQL 16+),
+ * providing insights into read/write operations by backend type.
+ *
+ * @param client - Connected PostgreSQL client
+ * @param nodeName - Node name for the report payload
+ * @returns I001 report payload
+ */
+async function generateI001(client: Client, nodeName: string): Promise<Report> {
+  const report = createBaseReport("I001", "I/O statistics (pg_stat_io)", nodeName);
+  const postgresVersion = await getPostgresVersion(client);
+  const parsedPgMajorVersion = parseInt(postgresVersion.server_major_ver, 10);
+  const pgMajorVersion = Number.isFinite(parsedPgMajorVersion) ? parsedPgMajorVersion : 0;
+
+  // pg_stat_io requires PostgreSQL 16+
+  if (pgMajorVersion < 16) {
+    report.results[nodeName] = {
+      data: {
+        available: false,
+        min_version_required: "16",
+        by_backend_type: [],
+        analysis: {
+          total_read_mb: 0,
+          total_write_mb: 0,
+          total_io_time_ms: 0,
+          read_hit_ratio_pct: 0,
+          avg_read_time_ms: null,
+          avg_write_time_ms: null,
+        },
+        stats_reset_s: null,
+      },
+      postgres_version: postgresVersion,
+    };
+    return report;
+  }
+
+  const ioStats = await getIOStatistics(client, pgMajorVersion);
+
+  // Sort by backend_type, putting 'total' first if present
+  ioStats.sort((a, b) => {
+    if (a.backend_type === "total") return -1;
+    if (b.backend_type === "total") return 1;
+    return a.backend_type.localeCompare(b.backend_type);
+  });
+
+  // Find 'total' row for analysis, or sum all rows if not present
+  let totalStats = ioStats.find((s) => s.backend_type === "total");
+  if (!totalStats && ioStats.length > 0) {
+    totalStats = {
+      backend_type: "total",
+      reads: ioStats.reduce((sum, s) => sum + s.reads, 0),
+      read_bytes_mb: ioStats.reduce((sum, s) => sum + s.read_bytes_mb, 0),
+      read_time_ms: ioStats.reduce((sum, s) => sum + s.read_time_ms, 0),
+      writes: ioStats.reduce((sum, s) => sum + s.writes, 0),
+      write_bytes_mb: ioStats.reduce((sum, s) => sum + s.write_bytes_mb, 0),
+      write_time_ms: ioStats.reduce((sum, s) => sum + s.write_time_ms, 0),
+      writebacks: ioStats.reduce((sum, s) => sum + s.writebacks, 0),
+      writeback_bytes_mb: ioStats.reduce((sum, s) => sum + s.writeback_bytes_mb, 0),
+      writeback_time_ms: ioStats.reduce((sum, s) => sum + s.writeback_time_ms, 0),
+      fsyncs: ioStats.reduce((sum, s) => sum + s.fsyncs, 0),
+      fsync_time_ms: ioStats.reduce((sum, s) => sum + s.fsync_time_ms, 0),
+      extends: ioStats.reduce((sum, s) => sum + (s.extends || 0), 0),
+      extend_bytes_mb: ioStats.reduce((sum, s) => sum + (s.extend_bytes_mb || 0), 0),
+      hits: ioStats.reduce((sum, s) => sum + s.hits, 0),
+      evictions: ioStats.reduce((sum, s) => sum + s.evictions, 0),
+      reuses: ioStats.reduce((sum, s) => sum + s.reuses, 0),
+    };
+  }
+
+  // Calculate analysis
+  const totalReadMb = totalStats?.read_bytes_mb || 0;
+  const totalWriteMb = totalStats?.write_bytes_mb || 0;
+  const totalReadTime = totalStats?.read_time_ms || 0;
+  const totalWriteTime = totalStats?.write_time_ms || 0;
+  const totalIoTimeMs = totalReadTime + totalWriteTime;
+  const totalReads = totalStats?.reads || 0;
+  const totalWrites = totalStats?.writes || 0;
+  const totalHits = totalStats?.hits || 0;
+
+  // Hit ratio: hits / (hits + reads) * 100
+  const totalRequests = totalHits + totalReads;
+  const readHitRatioPct = totalRequests > 0 ? Math.round((totalHits / totalRequests) * 10000) / 100 : 0;
+
+  // Average times
+  const avgReadTimeMs = totalReads > 0 ? Math.round((totalReadTime / totalReads) * 1000) / 1000 : null;
+  const avgWriteTimeMs = totalWrites > 0 ? Math.round((totalWriteTime / totalWrites) * 1000) / 1000 : null;
+
+  // Direct-connect checkup queries stats_reset separately instead of reading it from pgwatch metrics.
+  let statsResetS: number | null = null;
+  try {
+    const resetResult = await client.query(`
+      select max(extract(epoch from now() - stats_reset)::int) as stats_reset_s
+      from pg_stat_io
+    `);
+    if (resetResult.rows.length > 0 && resetResult.rows[0].stats_reset_s !== null) {
+      const parsedStatsResetS = parseInt(resetResult.rows[0].stats_reset_s, 10);
+      statsResetS = Number.isFinite(parsedStatsResetS) ? parsedStatsResetS : null;
+    }
+  } catch (err) {
+    // Ignore errors getting stats_reset - not critical
+  }
+
+  report.results[nodeName] = {
+    data: {
+      available: ioStats.length > 0,
+      by_backend_type: ioStats,
+      analysis: {
+        total_read_mb: totalReadMb,
+        total_write_mb: totalWriteMb,
+        total_io_time_ms: totalIoTimeMs,
+        read_hit_ratio_pct: readHitRatioPct,
+        avg_read_time_ms: avgReadTimeMs,
+        avg_write_time_ms: avgWriteTimeMs,
+      },
+      stats_reset_s: statsResetS,
+    },
+    postgres_version: postgresVersion,
+  };
+
+  return report;
+}
+
 /**
  * Available report generators
  */
@@ -1446,11 +1900,14 @@ export const REPORT_GENERATORS: Record<string, (client: Client, nodeName: string
   D001: generateD001,
   D004: generateD004,
   F001: generateF001,
+  F004: generateF004,
+  F005: generateF005,
   G001: generateG001,
   G003: generateG003,
   H001: generateH001,
   H002: generateH002,
   H004: generateH004,
+  I001: generateI001,
 };
 
 /**

package/lib/config.ts

@@ -8,8 +8,11 @@ import * as os from "os";
 export interface Config {
   apiKey: string | null;
   baseUrl: string | null;
+  storageBaseUrl: string | null;
   orgId: number | null;
   defaultProject: string | null;
+  /** Docker Compose project name for monitoring stack */
+  projectName: string | null;
 }
 
 /**
@@ -46,8 +49,10 @@ export function readConfig(): Config {
   const config: Config = {
     apiKey: null,
     baseUrl: null,
+    storageBaseUrl: null,
     orgId: null,
     defaultProject: null,
+    projectName: null,
   };
 
   // Try user-level config first
@@ -58,8 +63,10 @@ export function readConfig(): Config {
       const parsed = JSON.parse(content);
       config.apiKey = parsed.apiKey ?? null;
       config.baseUrl = parsed.baseUrl ?? null;
+      config.storageBaseUrl = parsed.storageBaseUrl ?? null;
       config.orgId = parsed.orgId ?? null;
       config.defaultProject = parsed.defaultProject ?? null;
+      config.projectName = parsed.projectName ?? null;
       return config;
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);