Memory Usage Monitoring

Free — GPL coresize Mplanned, not built

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

Server operators need real-time visibility into memory consumption to prevent crashes during traffic spikes. This feature tracks heap usage, garbage collection, and alerts on memory pressure.

The problem

My server crashes without warning during peak traffic. I don’t know if memory is exhausted or if there’s a memory leak. I need to see memory usage in real-time so I can scale or debug before customers are affected.

What it does

• Poll Node.js process.memoryUsage() every 30 seconds and store in memory_profile collection
• Track heap used, heap total, external memory, and array buffers separately
• Calculate memory growth rate (MB/hour) to detect leaks vs normal fluctuation
• Display real-time memory gauge in admin dashboard with current usage and peak of last 24h
• Show memory trend graph (last 24 hours) with GC events marked as dips
• Alert (UI notification + optional webhook) if memory usage exceeds threshold (e.g., 85% of available)
• Store up to 30 days of 30-second samples (86,400 samples); auto-aggregate older data to 5-minute samples

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.

• Heap snapshot analysis or memory leak pinpointing — requires external tools (Chrome DevTools, clinic.js); defer to operator’s existing debugging workflow
• Automatic GC tuning or Node.js flag recommendations — this is infra ops, not core monitoring
• Memory per-feature breakdown (e.g., how much cache uses) — requires instrumentation across the codebase, not feasible as core feature

Data model

memory_profile collection: {id, timestamp, heap_used_mb, heap_total_mb, external_mb, rss_mb, growth_rate_mb_per_hour}. No migration; new collection.

API

• GET /api/admin/monitoring/memory — fetch current memory status and recent history
• GET /api/admin/monitoring/memory/history?days=7 — fetch memory data for date range
• POST /api/admin/monitoring/memory/threshold — set alert threshold (% of heap)

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. Memory card displays: (1) current heap used / total (e.g., 256MB / 512MB), (2) gauge showing % full with color codes (green <70%, yellow 70-85%, red >85%), (3) 24-hour trend line with GC events marked. Alert bell icon and log appear if threshold exceeded.

The seam — why this is core

Core owns memory monitoring UI and profile collection. Node.js API (process.memoryUsage) is open-source and free. No paid seam — this is operational infrastructure.

Core owns the interface + honest memory tracker; infrastructure monitoring is infrastructure, not a support commitment or credential.

Dependencies

• Existing admin dashboard
• scheduler (to run memory polling every 30s)

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 memory_profile collection receives samples every 30 seconds with accurate heap_used_mb value
• Allocate 100MB in a loop and verify growth_rate_mb_per_hour increases
• Set threshold to 50% and trigger alert by increasing heap usage; verify UI shows alert
• Confirm memory samples older than 30 days are aggregated to 5-minute intervals without data loss
• Verify memory gauge colors: green for <70%, yellow for 70-85%, red for >85%

Risks

Polling every 30s can miss flash spikes in traffic. Implement exponential backoff (poll more frequently when memory is near threshold). Storing 30 days of samples can use 1-2MB; monitor collection size and implement aggressive purge if needed.

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.