Local Metrics Collector

Project roadmap

1. 01

   Define the metrics and endpoints

   ~1h

   Write README.md: the metrics (CPU usage overall and per core as percentages, memory total, available and used, swap used, load averages and uptime), the sampling interval (default 5 seconds), the endpoints (GET /metrics.json for the latest values, GET /summary for averages and peaks over 1, 5 and 15 minutes, GET /metrics in Prometheus format, and GET /health), and that it listens on 127.0.0.1 by default. Set up a CMake project with Boost. Done when: README.md defines the metrics and endpoints.

2. 02

   Read metrics from /proc

   ~2h

   Write functions that parse /proc/stat (CPU time counters per core), /proc/meminfo, /proc/loadavg and /proc/uptime, taking the path as a parameter so tests can use fixture files. Calculate CPU usage from the difference between two readings (busy time change divided by total time change). Handle unexpected formats with clear errors. Done when: the values match what top and free show.

3. 03

   Store samples

   ~1.5h

   Take a sample every interval with a boost::asio::steady_timer, store it in a fixed-size ring buffer holding one hour of samples, and compute averages and peaks over the last 1, 5 and 15 minutes. Protect the buffer with a std::shared_mutex (the timer writes, and requests read), holding the lock only briefly. Done when: the buffer never grows past its size, and the summaries are correct.

4. 04

   Serve the endpoints with Boost.Beast

   ~2.5h

   Build an asynchronous HTTP server with Boost.Beast: accept connections, read requests, and route GET requests to the endpoints, returning JSON (built with Boost.JSON) or the Prometheus text format with HELP and TYPE lines and labels such as cpu="0", and 404 or 405 for other requests. Set timeouts on connections. Done when: curl on each endpoint returns correct data, and promtool check metrics accepts /metrics.

5. 05

   Run it reliably

   ~1h

   Add command-line options for the port, address and interval, shut down cleanly on SIGINT and SIGTERM (with boost::asio::signal_set), and write a systemd unit file example. Check the collector's own CPU and memory use stays small and note it in README.md. Done when: the collector runs for an hour with low, steady resource use and stops cleanly.

6. 06

   Test it

   ~1.5h

   Write tests (with GoogleTest or Catch2) using fixture copies of /proc files: parsing, CPU usage from two readings, the ring buffer and summaries, and the Prometheus output format. Add an integration test that starts the server on a free port and requests each endpoint. Done when: all tests pass.

Resources

• Docsproc(5) man page
• DocsBoost.Beast documentation
• DocsBoost.JSON documentation
• DocsPrometheus: exposition formats
• Docsstd::shared_mutex (cppreference)