Skip to main content

System Health & Runtime Diagnostics (/admin/system-health)

The platform provides a dual-layer health and diagnostics subsystem: a public, lightweight uptime probe (/api/health) for cloud container orchestrators and an exhaustive, real-time diagnostic command center (/[locale]/admin/system-health) for platform administrators.

1. Public Uptime Health Probe (GET /api/health)​

  • Route: src/app/api/health/route.ts
  • Execution: export const dynamic = "force-dynamic"
  • Authentication: None (Public)
  • Use Case: Used by Azure App Service Health Check probes, Kubernetes liveness probes, and external ping services (UptimeRobot, Datadog) to verify HTTP routing integrity.

Sample Response (HTTP 200 OK)​

{
  "status": "ok",
  "timestamp": "2026-10-20T16:45:00.123Z"
}

2. Advanced System Health Dashboard (/admin/system-health)​

Located at /[locale]/admin/system-health and powered by Server Actions in src/components/feature/system-health/actions.ts, this panel delivers deep, low-overhead introspection into the host container, Node.js process, V8 runtime, and MongoDB replica set:

3. Diagnostic Categories & Metric Specifications​

3.1 Database Diagnostics (DatabaseDiagnostics)​

  • Connection Status: Verifies Mongoose connection state (0: disconnected, 1: connected, 2: connecting, 3: disconnecting).
  • Ping Latency: Issues an administrative { ping: 1 } command directly to the MongoDB primary node and records roundtrip latency in milliseconds (typically under 15ms).
  • Collection Inventory: Enumerates all active collections across the cluster and audits document counts and index footprints.

3.2 Host System Metrics (HostSystemMetrics)​

  • CPU Architecture & Core Count: Reports logical processor threads, clock speeds, and model strings via os.cpus().
  • System Load Averages: 1-minute, 5-minute, and 15-minute load averages via os.loadavg().
  • Total & Free System Memory: Tracks host RAM utilization to identify container resource starvation.

3.3 Process Resource Metrics (ProcessResourceMetrics)​

  • Process ID & Platform: Active Node.js worker PID and platform identifier (linux, win32, darwin).
  • Process Uptime: Monotonic process lifetime formatted into human-readable hours, minutes, and seconds.
  • Memory Footprint (process.memoryUsage()):
    • rss (Resident Set Size): Total physical memory allocated to the Node.js process.
    • heapTotal & heapUsed: Total V8 heap vs active JavaScript objects.
    • external: Memory bound to C++ objects (Buffers, crypto operations).

3.4 V8 Engine Heap Space Profiler (V8HeapMetrics)​

Introspects V8 memory spaces via native v8.getHeapSpaceStatistics():

  • new_space: Young generation object allocations.
  • old_space: Survived long-lived application objects.
  • code_space: JIT-compiled bytecode and executable memory.
  • map_space: Hidden classes and object shape descriptors.
  • large_object_space: Large object allocations exceeding normal chunk limits.

3.5 Node Runtime Environment (NodeRuntimeVersions)​

Reports runtime engine versions to ensure compatibility:

  • Node.js version (strictly validated against >= 22.0.0).
  • V8 engine version.
  • libuv asynchronous I/O thread pool version.
  • OpenSSL cryptographic engine version.