docs: update

docs/MonitoringService.md

@@ -0,0 +1,79 @@
+# Monitoring Service
+
+Exposes system resource metrics via HTTP for observability.
+
+## Overview
+
+- **Service name**: `MonitoringService`
+- **Endpoint**: `GET /api/monitoring/resources`
+- **Metrics**: CPU usage, memory, filesystem, uptime
+
+## Endpoint
+
+### GET /api/monitoring/resources
+
+Returns real-time system resource metrics.
+
+Response fields:
+- `cpu.current_usage`: Current CPU usage percent
+- `cpu.average_usage`: Average CPU usage percent
+- `cpu.max_usage`: Max observed CPU usage
+- `cpu.min_usage`: Min observed CPU usage
+- `cpu.measurement_count`: Number of measurements
+- `cpu.is_measuring`: Whether measurement is active
+- `memory.free_heap`: Free heap bytes
+- `memory.total_heap`: Total heap bytes (approximate)
+- `memory.min_free_heap`: Minimum free heap (0 on ESP8266)
+- `memory.max_alloc_heap`: Max allocatable heap (0 on ESP8266)
+- `memory.heap_fragmentation`: Fragmentation percent (0 on ESP8266)
+- `filesystem.total_bytes`: LittleFS total bytes
+- `filesystem.used_bytes`: Used bytes
+- `filesystem.free_bytes`: Free bytes
+- `filesystem.usage_percent`: Usage percent
+- `system.uptime_ms`: Uptime in milliseconds
+- `system.uptime_seconds`: Uptime in seconds
+- `system.uptime_formatted`: Human-readable uptime
+
+Example:
+```json
+{
+  "cpu": {
+    "current_usage": 3.5,
+    "average_usage": 2.1,
+    "max_usage": 15.2,
+    "min_usage": 0.0,
+    "measurement_count": 120,
+    "is_measuring": true
+  },
+  "memory": {
+    "free_heap": 48748,
+    "total_heap": 81920,
+    "min_free_heap": 0,
+    "max_alloc_heap": 0,
+    "heap_fragmentation": 0,
+    "heap_usage_percent": 40.4
+  },
+  "filesystem": {
+    "total_bytes": 65536,
+    "used_bytes": 10240,
+    "free_bytes": 55296,
+    "usage_percent": 15.6
+  },
+  "system": {
+    "uptime_ms": 123456,
+    "uptime_seconds": 123,
+    "uptime_formatted": "0h 2m 3s"
+  }
+}
+```
+
+## Implementation Notes
+
+- `MonitoringService` reads from `CpuUsage` and ESP8266 SDK APIs.
+- Filesystem metrics are gathered from LittleFS.
+- CPU measurement is bracketed by `Spore::loop()` calling `cpuUsage.startMeasurement()` and `cpuUsage.endMeasurement()`.
+
+## Troubleshooting
+
+- If `filesystem.total_bytes` is zero, ensure LittleFS is enabled in `platformio.ini` and an FS image is uploaded.
+- CPU usage values remain zero until the main loop runs and CPU measurement is started.