Files
StarPunk/docs/decisions/ADR-072-remove-metrics-dashboard.md
T
PhilandClaude Opus 5.5 742e2e3ec3 Remove the metrics dashboard and monitoring package (v2.12.0)
The in-memory metrics system covered one gunicorn process at a time, was
lost on restart and was never used. Remove /admin/metrics-dashboard,
/admin/metrics, starpunk/monitoring, the HTTP/query timing, memory monitor,
feed counters, METRICS_* settings and psutil. Keep /health, /admin/health
(without its metrics block), pool stats and the feed cache. ADR-072.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 16:07:47 -07:00

2.0 KiB

ADR-072: Remove the metrics dashboard

Status

Accepted (v2.12.0, 2026-11-03). Supersedes ADR-053 and ADR-060.

Context

v1.1.1 and v1.1.2 added built-in performance monitoring (ADR-053): HTTP request timing middleware, a wrapper on every database connection that timed queries, a memory-sampling thread, feed-generation counters, an in-memory buffer of the results, and an HTML dashboard at /admin/metrics-dashboard with a JSON twin at /admin/metrics (ADR-060 covered adapting the data for the dashboard template).

In practice it told us little:

  • The buffer lives in memory in each of the four gunicorn processes, so the dashboard showed whichever process served the request, and everything was lost on restart or deploy.
  • Nothing in it was ever used to find or fix a problem. Logs (with correlation IDs), /health and /admin/health were.
  • It cost something on every request and every query, kept a thread per process, and needed psutil, about 1,300 lines of code and three test files.

Decision

Remove the dashboard and everything that only fed it: the starpunk/monitoring package, the HTTP metrics middleware (including its X-Request-ID response header), MonitoredConnection, the memory monitor, the feed-generation tracking calls, /admin/metrics-dashboard, /admin/metrics, the METRICS_* settings and the psutil dependency.

Keep:

  • /health and /health?detailed=true;
  • /admin/health, without its metrics section (database, pool statistics, filesystem and disk checks stay);
  • connection pool statistics (get_pool_stats) and the feed cache, which do work of their own;
  • structured logs with correlation IDs (ADR-054).

Consequences

  • Less code and one fewer dependency; no timing work on each request or query; one fewer thread per process.
  • Slow database queries are no longer logged. If that is ever needed, a query timer can be added at the pool level, or an external tool used.
  • METRICS_* environment variables are ignored if still set.
  • Bookmarks to /admin/metrics-dashboard now get a 404.