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>
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 intodocs/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:
- Route conflict. The notes dashboard (
/admin/, endpointadmin.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). - Data contract mismatch (the real cause). The template reads
metrics.database.countand.avg/.min/.max, butstarpunk.monitoring.get_metrics_stats()returnsby_type.database.countandavg_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()instarpunk/routes/admin.pyflattensby_type.<type>to<type>fordatabase,httpandrender, renamesavg_duration_ms/min_duration_ms/max_duration_mstoavg/min/max, and keepstotal_count,max_sizeandprocess_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.monitoringor 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 existingurl_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.mddocs/design/v1.1.1/2025-11-25-hotfix-v1.1.1-rc.2-implementation.mddocs/design/v1.1.1/hotfix-v1.1.1-rc2-review.md- ADR-053 (performance monitoring)