CPU Usage Monitoring

Free — GPL coresize Splanned, not built

Generated from docs/plan/core/cpu-usage-monitoring/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Server operators need to monitor CPU usage to detect sustained high load and plan capacity. This feature tracks CPU time across cores and shows load trends.

The problem

During peak hours, my customers experience slow page loads, but I don’t know if my CPU is maxed out. I can’t tell if I need to add more servers or optimize my code.

What it does

• Poll Node.js os.cpus() and os.loadavg() every 1 minute and store in cpu_profile collection
• Calculate per-core CPU time (idle vs active) and average load across 1, 5, 15-minute windows
• Display current CPU usage (%) and load average in admin dashboard as gauge and trend line
• Show which processes/queries are consuming CPU via integration with query_profile (optional in v1; can be plugin later)
• Alert if CPU load exceeds threshold (e.g., 80% of available cores) for >5 minutes
• Store up to 7 days of CPU data; older data auto-purged

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Per-process CPU breakdown (requires /proc sampling on Linux, complex) — defer to hosting provider’s native tools
• Automatic scaling triggers based on CPU thresholds — that is infra ops, not monitoring
• Thread-level CPU profiling — requires native modules; too invasive for core feature

Data model

cpu_profile collection: {id, timestamp, load_1min, load_5min, load_15min, cpu_percent, core_count}. No migration; new collection.

API

• GET /api/admin/monitoring/cpu — fetch current CPU status and recent history
• GET /api/admin/monitoring/cpu/history?hours=24 — fetch CPU data for date range
• POST /api/admin/monitoring/cpu/threshold — set alert threshold (%)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Admin panel shows ‘Server Health’ section. CPU card displays: (1) current CPU usage (%), (2) gauge with color codes (green <60%, yellow 60-80%, red >80%), (3) load average (1, 5, 15m), (4) 24-hour trend line.

The seam — why this is core

Core owns CPU monitoring UI and profile collection. os module (Node.js built-in) is free. No paid seam — this is operational infrastructure.

Core owns the interface + honest CPU tracker; infrastructure monitoring is infrastructure, not a per-country obligation or credential.

Dependencies

• Existing admin dashboard
• scheduler (to run CPU polling every 1 minute)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Confirm cpu_profile collection receives samples with load_1min, load_5min, load_15min populated
• Verify cpu_percent accuracy by running CPU-intensive workload and confirming CPU usage increases
• Set threshold to 30% and trigger alert by running CPU load; verify UI shows alert
• Confirm trend line renders for 24+ hours without gaps
• Verify old CPU data (>7 days) is purged without deleting recent data

Risks

CPU profiling has minimal overhead, but polling os.cpus() can vary by OS; test on Linux, macOS, and Windows. Load average is Unix-specific; Windows uses different metrics — implement fallback for Process CPU time on Windows.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.