Files
StarPunk/docs/decisions/ADR-060-production-hotfix-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

4.1 KiB

ADR-060: Route Adapter for the Metrics Dashboard

Status

Superseded by ADR-072 (was: Accepted, v1.1.1-rc.2, 2025-11-25)

The metrics dashboard was removed in v2.12.0. (status updated 2026-11-03)

Reconstructed on 2026-11-03 from code, changelog and related documents; the original was lost. The original (ADR-060-production-hotfix-metrics-dashboard.md) was deleted in the v1.1.1-rc.2 architectural review as "a bug fix, not an architectural decision", and its content was merged into docs/design/v1.1.1/hotfix-v1.1.1-rc2-consolidated.md. Code (starpunk/routes/admin.py) and CHANGELOG 1.1.1-rc.2 still cite it, so this record restores the number.

Not to be confused with the "Option 2 (ADR-060)" for Media RSS mentioned in ADR-059: that ADR was planned but never written (see docs/design/v1.2.0/2025-12-10-documentation-audit-v1.2.0.md).

Context

v1.1.1-rc.1 added a metrics dashboard. In production it returned 500:

jinja2.exceptions.UndefinedError: 'dict object' has no attribute 'database'

Two problems were found:

  1. Route conflict. The notes dashboard (/admin/, endpoint admin.dashboard) and the new metrics dashboard (/admin/dashboard) were easily confused. This was fixed first by moving the metrics dashboard to /admin/metrics-dashboard (the "ADR-022" route-naming fix cited in the CHANGELOG; see Numbering below).
  2. Data contract mismatch (the real cause). The template reads metrics.database.count and .avg/.min/.max, but starpunk.monitoring.get_metrics_stats() returns by_type.database.count and avg_duration_ms, min_duration_ms, max_duration_ms.

Either the monitoring module, the template (and its JavaScript), or the route could change.

Decision

Adapt the data in the route handler (presentation layer) and leave both the monitoring module's API and the template unchanged.

  • transform_metrics_for_template() in starpunk/routes/admin.py flattens by_type.<type> to <type> for database, http and render, renames avg_duration_ms/min_duration_ms/max_duration_ms to avg/min/max, and keeps total_count, max_size and process_id. Missing types get zero values.
  • If collecting metrics fails, the route flashes a warning and renders the same structure with zeros.
  • The monitoring imports are defensive: if starpunk.monitoring or the pool statistics are unavailable, stub functions return an error value and the dashboard still renders.
  • The metrics dashboard lives at /admin/metrics-dashboard (admin.metrics_dashboard); /admin/ (admin.dashboard) stays the notes list, so existing url_for("admin.dashboard") redirects are unaffected.

Consequences

Positive

  • Minimal, low-risk hotfix: one route changed, no template or monitoring changes.
  • The monitoring module's output stays the same for the JSON endpoint (/admin/metrics) and other consumers.
  • The dashboard degrades instead of failing when metrics are missing.

Negative

  • Treats the symptom: the template and the monitoring module still disagree about the data shape, and the adapter must be kept in step with both (noted in docs/design/v1.1.1/hotfix-v1.1.1-rc2-review.md).
  • Errors loading metrics are shown as zeros, which can hide a problem.

Alternatives Considered

  • Change the monitoring module to return the template's shape: breaks its other consumers.
  • Change the template and its JavaScript: larger change in a hotfix, with more to test.

Numbering

The CHANGELOG for 1.1.1-rc.2 says "See ADR-022 and ADR-060". The ADR-022 it meant was ADR-022-admin-dashboard-route-conflict-hotfix.md, deleted in the same review; its number collided with the existing ADR-022 (IndieAuth callback route) and it was not restored. Its decision (the route rename) is recorded above.

References

  • starpunk/routes/admin.py: transform_metrics_for_template(), metrics_dashboard()
  • docs/design/v1.1.1/hotfix-v1.1.1-rc2-consolidated.md
  • docs/design/v1.1.1/2025-11-25-hotfix-v1.1.1-rc.2-implementation.md
  • docs/design/v1.1.1/hotfix-v1.1.1-rc2-review.md
  • ADR-053 (performance monitoring)