Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

docs: Complete Phase 6 - Dashboard Historical Metrics

Juan Denis453697a2d223
diff --git a/.planning/STATE.md b/.planning/STATE.md
index de8cae81..d8381268 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -2,8 +2,8 @@
## Current Status
- **Milestone**: 1 - Infrastructure Fixes, Private URLs & UI Polish
-- **Current Phase**: 6 - Dashboard Historical Metrics
-- **Phase Status**: Planned
+- **Current Phase**: 7 - App Detail Page Redesign
+- **Phase Status**: Pending
- **Last Updated**: 2026-01-19
## Phase Progress
@@ -15,12 +15,22 @@
| 3 | completed | 2026-01-19 | 2026-01-19 |
| 4 | skipped | - | - |
| 5 | completed | 2026-01-19 | 2026-01-19 |
-| 6 | planned | 2026-01-19 | - |
+| 6 | completed | 2026-01-19 | 2026-01-19 |
| 7 | pending | - | - |
| 8 | pending | - | - |
| 9 | pending | - | - |
| 10 | pending | - | - |
+## Phase 6 Summary
+Dashboard historical metrics fully implemented:
+- MetricsHistory model with minute/hour/day aggregation levels
+- MetricsHistoryService with background collection every 60 seconds
+- Auto-aggregation (minute→hour→day) and cleanup per retention policy
+- REST API endpoints for history, stats, and collection control
+- MetricsGraph component with Recharts LineChart
+- Period selector (1h, 6h, 24h, 7d, 30d)
+- Integrated into Dashboard below real-time metrics
+
## Phase 5 Summary
Private URL system fully implemented:
- Database schema with private_slug and private_url_enabled fields
@@ -51,12 +61,13 @@ Completed all 8 tasks:
None currently identified.
## Notes
-- Phase 5 complete - private URL feature ready for testing
-- Database migration required on deploy (new fields in Application model)
-- Nginx config auto-generates when private URLs enabled
+- Phase 6 complete - historical metrics with graphs ready
+- Metrics collection starts automatically on app startup
+- Database migration runs automatically via SQLAlchemy
## Quick Links
- [ROADMAP.md](./ROADMAP.md)
- [PROJECT.md](./PROJECT.md)
- [Phase 1 Summary](./phases/01-docker-domain-debugging/SUMMARY.md)
- [Phase 5 Summary](./phases/05-private-urls/SUMMARY.md)
+- [Phase 6 Summary](./phases/06-dashboard-historical-metrics/SUMMARY.md)
diff --git a/.planning/phases/06-dashboard-historical-metrics/SUMMARY.md b/.planning/phases/06-dashboard-historical-metrics/SUMMARY.md
new file mode 100644
index 00000000..ec57b6aa
--- /dev/null
+++ b/.planning/phases/06-dashboard-historical-metrics/SUMMARY.md
@@ -0,0 +1,89 @@
+# Phase 6: Dashboard Historical Metrics - Summary
+
+## Overview
+Added time-series graphs to the dashboard showing CPU, Memory, and Disk usage trends over configurable time periods with automatic data collection and aggregation.
+
+## Completed
+- [x] Task 1: Create MetricsHistory Model
+- [x] Task 2: Create Metrics History Service
+- [x] Task 3: Add Background Metrics Collection
+- [x] Task 4: Create Historical Metrics API
+- [x] Task 5: Create MetricsGraph Component
+- [x] Task 6: Create useMetricsHistory Hook (integrated in component)
+- [x] Task 7: Add Graphs to Dashboard
+- [x] Task 8: Add Styles for Metrics Graphs
+- [x] Task 9: Initialize Collection on App Start
+
+## Implementation Details
+
+### Backend
+- **MetricsHistory Model** (`backend/app/models/metrics_history.py`)
+ - Stores CPU, Memory, Disk metrics at three aggregation levels: minute, hour, day
+ - Composite index on (level, timestamp) for efficient queries
+ - Retention: 24h minute data, 7 days hourly, 30 days daily
+
+- **MetricsHistoryService** (`backend/app/services/metrics_history_service.py`)
+ - Background thread collects metrics every 60 seconds
+ - Auto-aggregates minute→hour (every hour) and hour→day (daily)
+ - Auto-cleanup of expired data per retention policy
+ - Period configurations: 1h, 6h, 24h use minute level; 7d uses hour; 30d uses day
+
+- **Metrics API** (`backend/app/api/metrics.py`)
+ - `GET /api/v1/metrics/history?period=1h` - Get historical data
+ - `GET /api/v1/metrics/stats` - Get storage statistics
+ - `POST /api/v1/metrics/collection/start|stop` - Control collection
+ - `POST /api/v1/metrics/aggregate` - Trigger manual aggregation
+
+### Frontend
+- **MetricsGraph Component** (`frontend/src/components/MetricsGraph.jsx`)
+ - Recharts-based LineChart with CPU, Memory, Disk lines
+ - Period selector (1h, 6h, 24h, 7d, 30d)
+ - Summary row with averages
+ - Compact mode for smaller displays
+ - Custom tooltip with data details
+
+- **Styles** (`frontend/src/styles/components/_metrics-graph.less`)
+ - Card layout matching design system
+ - Loading, error, empty states
+ - Responsive breakpoints for mobile
+
+## API Response Format
+```json
+{
+ "period": "1h",
+ "level": "minute",
+ "points": 60,
+ "data": [
+ {
+ "timestamp": "2026-01-19T10:00:00",
+ "cpu": { "percent": 45.2, "min": null, "max": null },
+ "memory": { "percent": 62.1, "used_gb": 8.5, "total_gb": 16.0 },
+ "disk": { "percent": 35.0, "used_gb": 200, "total_gb": 500 },
+ "load": { "1m": 1.2, "5m": 1.1, "15m": 0.9 }
+ }
+ ],
+ "summary": {
+ "cpu_avg": 42.5,
+ "memory_avg": 61.8,
+ "disk_avg": 35.0
+ }
+}
+```
+
+## Files Changed
+- `backend/app/models/metrics_history.py` (new)
+- `backend/app/models/__init__.py` (export added)
+- `backend/app/services/metrics_history_service.py` (new)
+- `backend/app/api/metrics.py` (new)
+- `backend/app/__init__.py` (blueprint + auto-start)
+- `frontend/src/components/MetricsGraph.jsx` (new)
+- `frontend/src/services/api.js` (API methods)
+- `frontend/src/pages/Dashboard.jsx` (integration)
+- `frontend/src/styles/components/_metrics-graph.less` (new)
+- `frontend/src/styles/main.less` (import)
+
+## Notes
+- Collection starts automatically on app startup
+- Windows compatibility: load averages will be null (not available on Windows)
+- Database migration runs automatically (SQLAlchemy create_all)
+- Charts update on period change; no auto-refresh (uses cached data)