# 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.