node-runtime-monitor 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# node-runtime-monitor
+
+Lightweight Node.js runtime monitoring for Express apps.
+
+It collects runtime stats (CPU, memory, process info, GC, and event loop behavior), exposes them as JSON, and provides a simple browser dashboard.
+
+Zero external runtime dependencies in Node.js. The dashboard UI uses only Chart.js loaded from a CDN in `src/public/index.html`.
+
+## Install
+
+```bash
+npm install node-runtime-monitor
+```
+
+## Quick start
+
+```js
+const express = require('express');
+const {
+	monitor,
+	metricsHandler,
+	dashboardHandler,
+} = require('node-runtime-monitor');
+
+const app = express();
+
+// Start background metric collection
+app.use(monitor({ interval: 5000 }));
+
+// Raw metrics JSON
+app.get('/status', metricsHandler);
+
+// Dashboard UI
+app.get('/status-dashboard', dashboardHandler({ metricsPath: '/status' }));
+
+app.listen(3000, () => {
+	console.log('Server running on http://localhost:3000');
+});
+```
+
+## What this package exports
+
+The package exports 3 functions:
+
+- `monitor(options?)`: Starts metric collection (once) and returns an Express middleware.
+	- `options.interval` (number, optional): collection interval in milliseconds.
+	- Default: `5000`.
+- `metricsHandler(req, res)`: Express route handler that returns all collected metrics as JSON.
+- `dashboardHandler(options?)`: Returns an Express route handler that serves the built-in dashboard HTML.
+	- `options.metricsPath` (string, optional): endpoint the dashboard should call for metrics.
+	- Default: `/status`.
+
+## Suggested routes
+
+- JSON metrics: `/status`
+- Dashboard: `/status-dashboard`
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,58 @@
+const path = require('path');
+const fs = require('fs');
+
+const startCollector = require('./src/scheduler/startCollector');
+const metricsRoute = require('./src/middlewares/metricsRoute');
+const metricsStore = require('./src/store/metricStore');
+
+let initialized = false;
+
+function monitor(options = {}) {
+
+    if (!initialized) {
+        initialized = true;
+
+        const interval = options.interval || 5000;
+        startCollector(interval);
+    }
+
+    return function (req, res, next) {
+        next();
+    }
+}
+
+function metricsHandler(req, res) {
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify(metricsStore));
+}
+
+function dashboardHandler(options = {}) {
+    const metricsPath = options.metricsPath || '/status';
+
+    return function (req, res) {
+        const filePath = path.join(__dirname, 'src', 'public', 'index.html');
+        fs.readFile(filePath, 'utf-8', (err, html) => {
+
+            if (err) {
+                res.statusCode = 500;
+                return res.end('Failed to load dashboard');
+            }
+
+            // Inject metrics route
+            html = html.replace(
+                '__METRICS_PATH__',
+                metricsPath
+            );
+
+            res.setHeader('Content-Type', 'text/html');
+
+            res.end(html);
+        });
+    }
+}
+
+module.exports = {
+    monitor,
+    metricsHandler,
+    dashboardHandler
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "node-runtime-monitor",
+  "version": "0.1.0",
+  "description": "Lightweight Node.js runtime monitoring and observability middleware using perf_hooks and native APIs.",
+  "main": "index.js",
+  "type": "commonjs",
+  "keywords": [
+    "nodejs",
+    "monitoring",
+    "observability",
+    "metrics",
+    "performance",
+    "event-loop",
+    "gc",
+    "express",
+    "runtime-monitor",
+    "perf-hooks"
+  ],
+  "homepage": "https://github.com/jhamayank02/node-runtime-monitor",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jhamayank02/node-runtime-monitor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jhamayank02/node-runtime-monitor/issues"
+  },
+  "license": "MIT",
+  "author": "jhamayank02"
+}

package/src/collectors/cpu.js

@@ -0,0 +1,7 @@
+const process = require('process');
+
+function getCpuMetrics() {
+    return process.cpuUsage();
+}
+
+module.exports = getCpuMetrics;

package/src/collectors/event-loop.js

@@ -0,0 +1,17 @@
+const { PerformanceObserver, performance, monitorEventLoopDelay } = require("perf_hooks");
+
+const histogram = monitorEventLoopDelay({
+    resolution: 20
+});
+
+histogram.enable();
+
+function getEventLoopMetrics() {
+    return {
+        mean: histogram.mean / 1e6,
+        max: histogram.max / 1e6,
+        p95: histogram.percentile(95) / 1e6
+    }
+}
+
+module.exports = getEventLoopMetrics;

package/src/collectors/gc.js

@@ -0,0 +1,45 @@
+const { PerformanceObserver, constants } = require('perf_hooks');
+const metricsStore = require('../store/metricStore');
+
+const gcTypes = {
+    [constants.NODE_PERFORMANCE_GC_MAJOR]: 'major',
+    [constants.NODE_PERFORMANCE_GC_MINOR]: 'minor',
+    [constants.NODE_PERFORMANCE_GC_INCREMENTAL]: 'incremental',
+    [constants.NODE_PERFORMANCE_GC_WEAKCB]: 'weakcb'
+};
+
+let observer;
+
+function startGcObserver() {
+    if (observer) {
+        return;
+    }
+
+    observer = new PerformanceObserver((list) => {
+        const entries = list.getEntries();
+
+        entries.forEach((entry) => {
+            if(!metricsStore.gc){
+                metricsStore.gc = [];
+            }
+            
+            metricsStore.gc.push({
+                duration: entry.duration,
+                kind: entry.kind,
+                type: gcTypes[entry.kind],
+                timestamp: Date.now()
+            });
+
+            // Keep only last 100 events
+            if (metricsStore.gc.length > 100) {
+                metricsStore.gc.shift();
+            }
+        });
+    });
+
+    observer.observe({
+        entryTypes: ['gc']
+    });
+}
+
+module.exports = startGcObserver;

package/src/collectors/memory.js

@@ -0,0 +1,7 @@
+const process = require('process');
+
+function getMemoryMetrics() {
+    return process.memoryUsage();
+}
+
+module.exports = getMemoryMetrics;

package/src/collectors/process.js

@@ -0,0 +1,11 @@
+const process = require('process');
+
+function getProcessMetrics() {
+    return {
+        pid: process.pid,
+        platform: process.platform,
+        uptime: process.uptime()
+    }
+}
+
+module.exports = getProcessMetrics;

package/src/middlewares/metricsRoute.js

@@ -0,0 +1,7 @@
+const metricsStore = require('../store/metricStore');
+
+function metricsRoute(req, res) {
+    res.json(metricsStore);
+}
+
+module.exports = metricsRoute;

package/src/public/index.html

@@ -0,0 +1,635 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Node Runtime Monitor</title>
+    <!-- Dashboard UI uses only Chart.js from CDN. No other external UI dependencies. -->
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.4.1/chart.umd.js"></script>
+    <style>
+        *,
+        *::before,
+        *::after {
+            box-sizing: border-box;
+            margin: 0;
+            padding: 0;
+        }
+
+        body {
+            background: #0f1117;
+            color: #c9d1d9;
+            font-family: ui-monospace, 'SFMono-Regular', 'Cascadia Code', monospace;
+            font-size: 13px;
+            padding: 20px 24px;
+        }
+
+        header {
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            margin-bottom: 20px;
+            padding-bottom: 12px;
+            border-bottom: 1px solid #21262d;
+        }
+
+        .header-left {
+            display: flex;
+            align-items: center;
+            gap: 12px;
+            color: #8b949e;
+        }
+
+        .status-dot {
+            width: 7px;
+            height: 7px;
+            border-radius: 50%;
+            background: #3fb950;
+            flex-shrink: 0;
+            animation: blink 2s ease-in-out infinite;
+        }
+
+        @keyframes blink {
+
+            0%,
+            100% {
+                opacity: 1;
+            }
+
+            50% {
+                opacity: 0.35;
+            }
+        }
+
+        .title {
+            color: #e6edf3;
+            font-weight: 600;
+        }
+
+        .sep {
+            color: #30363d;
+        }
+
+        .header-right {
+            color: #8b949e;
+            font-size: 12px;
+        }
+
+        .error-bar {
+            display: none;
+            background: #161b22;
+            border: 1px solid #f85149;
+            border-radius: 4px;
+            padding: 6px 12px;
+            color: #f85149;
+            font-size: 12px;
+            margin-bottom: 16px;
+        }
+
+        .error-bar.show {
+            display: block;
+        }
+
+        .stats {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+            gap: 8px;
+            margin-bottom: 16px;
+        }
+
+        .stat {
+            background: #161b22;
+            border: 1px solid #21262d;
+            border-radius: 6px;
+            padding: 10px 12px;
+        }
+
+        .stat .lbl {
+            font-size: 11px;
+            color: #8b949e;
+            margin-bottom: 5px;
+        }
+
+        .stat .val {
+            font-size: 18px;
+            font-weight: 600;
+            color: #e6edf3;
+            line-height: 1;
+        }
+
+        .stat .unit {
+            font-size: 11px;
+            color: #8b949e;
+            margin-left: 2px;
+        }
+
+        .stat .sub {
+            font-size: 11px;
+            color: #8b949e;
+            margin-top: 4px;
+        }
+
+        .charts {
+            display: grid;
+            grid-template-columns: 1fr 1fr;
+            gap: 8px;
+            margin-bottom: 16px;
+        }
+
+        @media (max-width: 700px) {
+            .charts {
+                grid-template-columns: 1fr;
+            }
+        }
+
+        .chart-box {
+            background: #161b22;
+            border: 1px solid #21262d;
+            border-radius: 6px;
+            padding: 12px;
+        }
+
+        .box-title {
+            font-size: 11px;
+            color: #8b949e;
+            margin-bottom: 10px;
+        }
+
+        .bottom {
+            display: grid;
+            grid-template-columns: 200px 1fr;
+            gap: 8px;
+        }
+
+        @media (max-width: 700px) {
+            .bottom {
+                grid-template-columns: 1fr;
+            }
+        }
+
+        .box {
+            background: #161b22;
+            border: 1px solid #21262d;
+            border-radius: 6px;
+            padding: 12px;
+        }
+
+        .el-rows {
+            margin-top: 8px;
+        }
+
+        .el-row {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            padding: 5px 0;
+            border-bottom: 1px solid #21262d;
+        }
+
+        .el-row:last-child {
+            border-bottom: none;
+        }
+
+        .el-row .k {
+            color: #8b949e;
+        }
+
+        .el-row .v {
+            color: #e6edf3;
+        }
+
+        table {
+            width: 100%;
+            border-collapse: collapse;
+            margin-top: 8px;
+        }
+
+        th {
+            font-size: 11px;
+            color: #8b949e;
+            text-align: left;
+            padding: 0 0 6px;
+            border-bottom: 1px solid #21262d;
+            font-weight: 400;
+        }
+
+        td {
+            padding: 5px 0;
+            border-bottom: 1px solid #161b22;
+            color: #8b949e;
+            font-size: 12px;
+        }
+
+        td:first-child {
+            color: #e6edf3;
+        }
+
+        tr:last-child td {
+            border-bottom: none;
+        }
+
+        .badge {
+            font-size: 10px;
+            padding: 1px 6px;
+            border-radius: 3px;
+            font-weight: 600;
+        }
+
+        .minor {
+            background: rgba(63, 185, 80, .15);
+            color: #3fb950;
+        }
+
+        .major {
+            background: rgba(248, 130, 74, .15);
+            color: #f8824a;
+        }
+
+        .incr {
+            background: rgba(88, 166, 255, .15);
+            color: #58a6ff;
+        }
+    </style>
+</head>
+
+<body>
+
+    <header>
+        <div class="header-left">
+            <div class="status-dot"></div>
+            <span class="title">node-runtime-monitor</span>
+            <span class="sep">|</span>
+            <span id="pidVal">pid —</span>
+            <span class="sep">|</span>
+            <span id="platformVal">—</span>
+            <span class="sep">|</span>
+            <span>up <span id="uptimeVal">—</span></span>
+        </div>
+        <div class="header-right">updated <span id="lastUpdate">—</span> · polling every 5s</div>
+    </header>
+
+    <div class="error-bar" id="errorBar">⚠ Server unreachable — waiting for metrics</div>
+
+    <div class="stats">
+        <div class="stat">
+            <div class="lbl">cpu user</div>
+            <div class="val"><span id="cpuUser">—</span><span class="unit">µs</span></div>
+        </div>
+        <div class="stat">
+            <div class="lbl">cpu system</div>
+            <div class="val"><span id="cpuSys">—</span><span class="unit">µs</span></div>
+        </div>
+        <div class="stat">
+            <div class="lbl">rss</div>
+            <div class="val"><span id="memRss">—</span><span class="unit">mb</span></div>
+        </div>
+        <div class="stat">
+            <div class="lbl">heap used</div>
+            <div class="val"><span id="heapUsed">—</span><span class="unit">mb</span></div>
+            <div class="sub">of <span id="heapTotal">—</span> mb total</div>
+        </div>
+        <div class="stat">
+            <div class="lbl">external</div>
+            <div class="val"><span id="memExt">—</span><span class="unit">mb</span></div>
+        </div>
+    </div>
+
+    <div class="charts">
+        <div class="chart-box">
+            <div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:10px;">
+                <div class="box-title" style="margin-bottom:0;">cpu (µs)</div>
+                <div style="display:flex;gap:12px;">
+                    <span style="display:flex;align-items:center;gap:5px;font-size:11px;color:#8b949e;"><span
+                            style="width:10px;height:2px;background:#3fb950;display:inline-block;border-radius:1px;"></span>user</span>
+                    <span style="display:flex;align-items:center;gap:5px;font-size:11px;color:#8b949e;"><span
+                            style="width:10px;height:2px;background:#58a6ff;display:inline-block;border-radius:1px;"></span>system</span>
+                </div>
+            </div>
+            <div style="position:relative;height:130px;">
+                <canvas id="cpuChart" role="img" aria-label="CPU usage over time"></canvas>
+            </div>
+        </div>
+        <div class="chart-box">
+            <div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:10px;">
+                <div class="box-title" style="margin-bottom:0;">memory (mb)</div>
+                <div style="display:flex;gap:12px;">
+                    <span style="display:flex;align-items:center;gap:5px;font-size:11px;color:#8b949e;"><span
+                            style="width:10px;height:2px;background:#f8824a;display:inline-block;border-radius:1px;"></span>rss</span>
+                    <span style="display:flex;align-items:center;gap:5px;font-size:11px;color:#8b949e;"><span
+                            style="width:10px;height:2px;background:#d2a8ff;display:inline-block;border-radius:1px;"></span>heap</span>
+                    <span style="display:flex;align-items:center;gap:5px;font-size:11px;color:#8b949e;"><span
+                            style="width:10px;height:2px;background:#ffa657;display:inline-block;border-radius:1px;"></span>ext</span>
+                </div>
+            </div>
+            <div style="position:relative;height:130px;">
+                <canvas id="memChart" role="img" aria-label="Memory usage over time"></canvas>
+            </div>
+        </div>
+    </div>
+
+    <div class="bottom">
+        <div class="box">
+            <div class="box-title">event loop lag</div>
+            <div class="el-rows">
+                <div class="el-row"><span class="k">mean</span><span class="v" id="elMean">—</span></div>
+                <div class="el-row"><span class="k">p95</span> <span class="v" id="elP95">—</span></div>
+                <div class="el-row"><span class="k">max</span> <span class="v" id="elMax">—</span></div>
+            </div>
+        </div>
+        <div class="box">
+            <div class="box-title">gc events</div>
+            <table style="width:100%;border-collapse:collapse;">
+                <thead>
+                    <tr>
+                        <th>type</th>
+                        <th>duration</th>
+                        <th>kind</th>
+                        <th>time</th>
+                    </tr>
+                </thead>
+            </table>
+            <div style="height:108px;overflow-y:auto;">
+                <table style="width:100%;border-collapse:collapse;">
+                    <tbody id="gcBody">
+                        <tr>
+                            <td colspan="4" style="color:#8b949e">—</td>
+                        </tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+    </div>
+
+    <!-- ── Glossary ───────────────────────────────────────────────────────── -->
+    <div style="margin-top:16px;background:#161b22;border:1px solid #21262d;border-radius:6px;overflow:hidden;">
+        <div style="padding:10px 14px;border-bottom:1px solid #21262d;font-size:11px;color:#8b949e;letter-spacing:.06em;">METRIC REFERENCE</div>
+
+        <div style="display:flex;align-items:baseline;gap:10px;padding:9px 14px;border-bottom:1px solid #21262d;">
+            <div style="width:180px;min-width:180px;display:flex;align-items:baseline;gap:6px;flex-wrap:wrap;">
+                <span style="color:#e6edf3;font-weight:600;font-size:12px;">cpu user</span>
+                <span style="font-size:10px;color:#6e7681;">µs</span>
+            </div>
+            <div style="font-size:12px;color:#8b949e;line-height:1.55;">Time the CPU spent running <em>your app's own code</em> — JS, business logic, JSON parsing, loops. High value = your code is doing heavy computation.</div>
+        </div>
+
+        <div style="display:flex;align-items:baseline;gap:10px;padding:9px 14px;border-bottom:1px solid #21262d;">
+            <div style="width:180px;min-width:180px;display:flex;align-items:baseline;gap:6px;flex-wrap:wrap;">
+                <span style="color:#e6edf3;font-weight:600;font-size:12px;">cpu system</span>
+                <span style="font-size:10px;color:#6e7681;">µs</span>
+            </div>
+            <div style="font-size:12px;color:#8b949e;line-height:1.55;">Time the OS kernel spent doing work <em>on behalf of your process</em> — file reads, network accepts, memory allocation. High value = heavy I/O or frequent syscalls.</div>
+        </div>
+
+        <div style="display:flex;align-items:baseline;gap:10px;padding:9px 14px;border-bottom:1px solid #21262d;">
+            <div style="width:180px;min-width:180px;display:flex;align-items:baseline;gap:6px;flex-wrap:wrap;">
+                <span style="color:#e6edf3;font-weight:600;font-size:12px;">rss</span>
+                <span style="font-size:10px;color:#6e7681;">mb · resident set size</span>
+            </div>
+            <div style="font-size:12px;color:#8b949e;line-height:1.55;">Total physical RAM the process occupies — JS heap + V8 engine + native addons + stack. What your OS task manager shows next to the node process.</div>
+        </div>
+
+        <div style="display:flex;align-items:baseline;gap:10px;padding:9px 14px;border-bottom:1px solid #21262d;">
+            <div style="width:180px;min-width:180px;display:flex;align-items:baseline;gap:6px;flex-wrap:wrap;">
+                <span style="color:#e6edf3;font-weight:600;font-size:12px;">heap used</span>
+                <span style="font-size:10px;color:#6e7681;">mb</span>
+            </div>
+            <div style="font-size:12px;color:#8b949e;line-height:1.55;">JS heap space actually filled with live objects — variables, closures, arrays, cached data. Drops when GC runs. If it only ever climbs and never comes back down, you have a memory leak.</div>
+        </div>
+
+        <div style="display:flex;align-items:baseline;gap:10px;padding:9px 14px;border-bottom:1px solid #21262d;">
+            <div style="width:180px;min-width:180px;display:flex;align-items:baseline;gap:6px;flex-wrap:wrap;">
+                <span style="color:#e6edf3;font-weight:600;font-size:12px;">heap total</span>
+                <span style="font-size:10px;color:#6e7681;">mb</span>
+            </div>
+            <div style="font-size:12px;color:#8b949e;line-height:1.55;">Total JS heap V8 has <em>reserved</em> from the OS — the container, not just the filled part. V8 grows this proactively to avoid asking the OS on every allocation. Heap used always sits inside heap total.</div>
+        </div>
+
+        <div style="display:flex;align-items:baseline;gap:10px;padding:9px 14px;border-bottom:1px solid #21262d;">
+            <div style="width:180px;min-width:180px;display:flex;align-items:baseline;gap:6px;flex-wrap:wrap;">
+                <span style="color:#e6edf3;font-weight:600;font-size:12px;">external</span>
+                <span style="font-size:10px;color:#6e7681;">mb · incl. arrayBuffers</span>
+            </div>
+            <div style="font-size:12px;color:#8b949e;line-height:1.55;">C++ memory controlled by JS but living <em>outside</em> the JS heap — mainly <code style="color:#c9d1d9;">Buffer</code>, <code style="color:#c9d1d9;">TypedArray</code>, TLS/zlib internals. Freed when the JS reference is GC'd.</div>
+        </div>
+
+        <div style="display:flex;align-items:baseline;gap:10px;padding:9px 14px;border-bottom:1px solid #21262d;">
+            <div style="width:180px;min-width:180px;display:flex;align-items:baseline;gap:6px;flex-wrap:wrap;">
+                <span style="color:#e6edf3;font-weight:600;font-size:12px;">event loop lag</span>
+                <span style="font-size:10px;color:#6e7681;">ms · mean / p95 / max</span>
+            </div>
+            <div style="font-size:12px;color:#8b949e;line-height:1.55;">How long the event loop is blocked between ticks. <strong style="color:#c9d1d9;">Mean</strong> = average. <strong style="color:#c9d1d9;">p95</strong> = 95% of ticks were faster than this. <strong style="color:#c9d1d9;">Max</strong> = worst single block. Above 10 ms means responses will feel slow.</div>
+        </div>
+
+        <div style="display:flex;align-items:baseline;gap:10px;padding:9px 14px;border-bottom:1px solid #21262d;">
+            <div style="width:180px;min-width:180px;display:flex;align-items:center;gap:6px;">
+                <span style="color:#e6edf3;font-weight:600;font-size:12px;">gc</span>
+                <span style="font-size:10px;background:rgba(63,185,80,.15);color:#3fb950;padding:1px 5px;border-radius:3px;font-weight:600;">minor</span>
+            </div>
+            <div style="font-size:12px;color:#8b949e;line-height:1.55;">Scavenge GC — fast collection of short-lived objects in the young generation of the heap. Happens frequently, very cheap (&lt;5 ms). Completely normal.</div>
+        </div>
+
+        <div style="display:flex;align-items:baseline;gap:10px;padding:9px 14px;border-bottom:1px solid #21262d;">
+            <div style="width:180px;min-width:180px;display:flex;align-items:center;gap:6px;">
+                <span style="color:#e6edf3;font-weight:600;font-size:12px;">gc</span>
+                <span style="font-size:10px;background:rgba(248,130,74,.15);color:#f8824a;padding:1px 5px;border-radius:3px;font-weight:600;">major</span>
+            </div>
+            <div style="font-size:12px;color:#8b949e;line-height:1.55;">Mark-sweep GC — full collection across the whole heap including long-lived objects. Expensive (10–100 ms), pauses the event loop. Frequent major GCs signal memory pressure.</div>
+        </div>
+
+        <div style="display:flex;align-items:baseline;gap:10px;padding:9px 14px;">
+            <div style="width:180px;min-width:180px;display:flex;align-items:center;gap:6px;">
+                <span style="color:#e6edf3;font-weight:600;font-size:12px;">gc</span>
+                <span style="font-size:10px;background:rgba(88,166,255,.15);color:#58a6ff;padding:1px 5px;border-radius:3px;font-weight:600;">incremental</span>
+            </div>
+            <div style="font-size:12px;color:#8b949e;line-height:1.55;">Mark-sweep split into small steps interleaved with JS execution instead of one long pause. V8's way of spreading the cost of a major GC across multiple ticks to reduce latency spikes.</div>
+        </div>
+
+    </div>
+
+    <script>
+        const METRICS_URL = "__METRICS_PATH__";
+        const MAX_POINTS = 20;
+        const POLL_INTERVAL = 5000;
+
+        // Rolling data arrays shared by both charts
+        const labels     = [];
+        const cpuUser    = [], cpuSystem = [];
+        const rssData    = [], heapData  = [], extData = [];
+
+        // Tracks whether the arrays have been flood-filled on the first reading.
+        // Until filled, values are appended freely. Once filled, every new point
+        // shifts the oldest one out — keeping arrays at exactly MAX_POINTS.
+        let chartsFilled = false;
+
+        // ── Chart options ────────────────────────────────────────────────────
+
+        const chartDefaults = {
+            responsive: true,
+            maintainAspectRatio: false,
+            animation: { duration: 400 },
+            plugins: {
+                legend: { display: false },
+                tooltip: {
+                    backgroundColor: '#1c2128',
+                    borderColor: '#30363d',
+                    borderWidth: 1,
+                    titleColor: '#8b949e',
+                    bodyColor: '#e6edf3',
+                    titleFont: { family: 'monospace', size: 11 },
+                    bodyFont:  { family: 'monospace', size: 11 }
+                }
+            },
+            scales: {
+                x: {
+                    grid:  { color: '#21262d' },
+                    ticks: { color: '#8b949e', font: { size: 10, family: 'monospace' }, maxTicksLimit: 6 }
+                },
+                y: {
+                    grid:       { color: '#21262d' },
+                    ticks:      { color: '#8b949e', font: { size: 10, family: 'monospace' } },
+                    beginAtZero: true
+                }
+            }
+        };
+
+        const cpuChart = new Chart(document.getElementById('cpuChart'), {
+            type: 'line',
+            data: {
+                labels,
+                datasets: [
+                    { label: 'user',   data: cpuUser,   borderColor: '#3fb950', backgroundColor: 'rgba(63,185,80,.08)',   borderWidth: 1.5, fill: true,  tension: 0.4, pointRadius: 0 },
+                    { label: 'system', data: cpuSystem, borderColor: '#58a6ff', backgroundColor: 'rgba(88,166,255,.08)', borderWidth: 1.5, fill: true,  tension: 0.4, pointRadius: 0 }
+                ]
+            },
+            options: { ...chartDefaults }
+        });
+
+        const memChart = new Chart(document.getElementById('memChart'), {
+            type: 'line',
+            data: {
+                labels,
+                datasets: [
+                    { label: 'rss',  data: rssData,  borderColor: '#f8824a', borderWidth: 1.5, fill: false, tension: 0.4, pointRadius: 0 },
+                    { label: 'heap', data: heapData, borderColor: '#d2a8ff', borderWidth: 1.5, fill: false, tension: 0.4, pointRadius: 0 },
+                    { label: 'ext',  data: extData,  borderColor: '#ffa657', borderWidth: 1.5, fill: false, tension: 0.4, pointRadius: 0, borderDash: [4, 3] }
+                ]
+            },
+            options: { ...chartDefaults }
+        });
+
+        // ── Helpers ──────────────────────────────────────────────────────────
+
+        // Push a value into a rolling array, evicting the oldest once full.
+        function pushRolling(arr, value) {
+            arr.push(value);
+            if (arr.length > MAX_POINTS) arr.shift();
+        }
+
+        // On the very first reading, flood-fill all arrays to MAX_POINTS with
+        // that value so the chart renders a stable full-width baseline immediately.
+        // After this every new point displaces exactly one old point.
+        function fillInitial(label, user, system, rss, heap, ext) {
+            for (let i = 0; i < MAX_POINTS; i++) {
+                labels.push(label);
+                cpuUser.push(user);   cpuSystem.push(system);
+                rssData.push(rss);    heapData.push(heap);    extData.push(ext);
+            }
+            chartsFilled = true;
+        }
+
+        function toMb(bytes)       { return (bytes / 1048576).toFixed(1); }
+        function fmtMs(value)      { return value == null ? '—' : value.toFixed(3) + 'ms'; }
+        function currentTime()     { return new Date().toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' }); }
+
+        function fmtUptime(seconds) {
+            const hours   = Math.floor(seconds / 3600);
+            const minutes = Math.floor((seconds % 3600) / 60);
+            const secs    = Math.floor(seconds % 60);
+            return hours ? `${hours}h ${minutes}m` : minutes ? `${minutes}m ${secs}s` : `${secs}s`;
+        }
+
+        function gcKindLabel(kind) {
+            const map = { 1: 'scavenge', 2: 'minor ms', 4: 'mark-sweep', 8: 'incremental', 15: 'all' };
+            return map[kind] ?? kind;
+        }
+
+        function gcTypeBadge(type) {
+            const map = { minor: 'minor', major: 'major', incremental: 'incr' };
+            return map[type] ?? 'minor';
+        }
+
+        // ── Render ───────────────────────────────────────────────────────────
+
+        function render(data) {
+            // Header
+            document.getElementById('pidVal').textContent      = 'pid ' + data.process.pid;
+            document.getElementById('platformVal').textContent = data.process.platform;
+            document.getElementById('uptimeVal').textContent   = fmtUptime(data.process.uptime);
+            document.getElementById('lastUpdate').textContent  = currentTime();
+
+            // Stat tiles
+            document.getElementById('cpuUser').textContent  = data.cpu.user.toLocaleString();
+            document.getElementById('cpuSys').textContent   = data.cpu.system.toLocaleString();
+            document.getElementById('memRss').textContent   = toMb(data.memory.rss);
+            document.getElementById('heapUsed').textContent = toMb(data.memory.heapUsed);
+            document.getElementById('heapTotal').textContent = toMb(data.memory.heapTotal);
+            document.getElementById('memExt').textContent   = toMb(data.memory.external + (data.memory.arrayBuffers || 0));
+
+            // Event loop
+            document.getElementById('elMean').textContent = fmtMs(data.eventLoop.mean);
+            document.getElementById('elP95').textContent  = fmtMs(data.eventLoop.p95);
+            document.getElementById('elMax').textContent  = fmtMs(data.eventLoop.max);
+
+            // GC table — most recent 6 events, newest first
+            const gcEvents = data.gc || [];
+            document.getElementById('gcBody').innerHTML = gcEvents.length === 0
+                ? '<tr><td colspan="4" style="color:#8b949e">no events</td></tr>'
+                : [...gcEvents].reverse().slice(0, 6).map(event => `
+                    <tr>
+                        <td><span class="badge ${gcTypeBadge(event.type)}">${event.type}</span></td>
+                        <td>${event.duration.toFixed(3)}ms</td>
+                        <td>${gcKindLabel(event.kind)}</td>
+                        <td>${new Date(event.timestamp).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' })}</td>
+                    </tr>`).join('');
+
+            // Chart data
+            const label  = currentTime();
+            const user   = data.cpu.user;
+            const system = data.cpu.system;
+            const rss    = parseFloat(toMb(data.memory.rss));
+            const heap   = parseFloat(toMb(data.memory.heapUsed));
+            const ext    = parseFloat(toMb(data.memory.external));
+
+            if (!chartsFilled) {
+                // First reading: flood-fill so the axis scale is stable immediately.
+                fillInitial(label, user, system, rss, heap, ext);
+            } else {
+                // Steady state: slide one new point in, one old point out.
+                pushRolling(labels,    label);
+                pushRolling(cpuUser,   user);   pushRolling(cpuSystem, system);
+                pushRolling(rssData,   rss);    pushRolling(heapData,  heap);   pushRolling(extData, ext);
+            }
+
+            cpuChart.update();
+            memChart.update();
+        }
+
+        // ── Polling ──────────────────────────────────────────────────────────
+
+        async function poll() {
+            try {
+                const response = await fetch(METRICS_URL, { cache: 'no-store', signal: AbortSignal.timeout(2500) });
+                if (!response.ok) throw new Error('bad response');
+                document.getElementById('errorBar').classList.remove('show');
+                render(await response.json());
+            } catch {
+                document.getElementById('errorBar').classList.add('show');
+            }
+        }
+
+        poll();
+        setInterval(poll, POLL_INTERVAL);
+    </script>
+</body>
+
+</html>

package/src/scheduler/startCollector.js

@@ -0,0 +1,23 @@
+const getCpuMetrics = require('../collectors/cpu');
+const getEventLoopMetrics = require('../collectors/event-loop');
+const startGcObserver = require('../collectors/gc');
+const getMemoryMetrics = require('../collectors/memory');
+const getProcessMetrics = require('../collectors/process');
+
+const metricsStore = require('../store/metricStore');
+
+function collectMetrics() {
+    metricsStore.cpu = getCpuMetrics();
+    metricsStore.memory = getMemoryMetrics();
+    metricsStore.process = getProcessMetrics();
+    metricsStore.eventLoop = getEventLoopMetrics();
+    metricsStore.gc = startGcObserver();
+    metricsStore.timestamp = Date.now();
+}
+
+function startCollector(interval = 3000) {
+    collectMetrics();
+    setInterval(collectMetrics, interval);
+}
+
+module.exports = startCollector;

package/src/store/metricStore.js

@@ -0,0 +1,10 @@
+const metricsStore = {
+    cpu: {},
+    memory: {},
+    process: {},
+    eventLoop: {},
+    gc: [],
+    timestamp: null
+}
+
+module.exports = metricsStore;