spore/docs/MonitoringService.md

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:

{
  "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.