docs(openspec): add SDD artifacts for next changes

- jellyfin-service-registry: proposal, design, and tasks for completing the Jellyfin migration off machine-level config. - grafana-prometheus-polish: proposal, design, and tasks for improving the Grafana/Prometheus observability integration. Both are planning-only artifacts; implementation not started.
2026-06-23 20:40:35 +00:00
parent ca8927834e
commit 4d520ab0e3
6 changed files with 391 additions and 0 deletions
@@ -0,0 +1,44 @@
+# Proposal — Grafana/Prometheus integration polish
+
+**Change:** `grafana-prometheus-polish`
+**Phase:** proposal
+**Date:** 2026-06-23
+
+## Problem
+
+Grafana and Prometheus are already modeled as service-registry service types and provide dashboard widgets (`GrafanaLinkWidget`, `PrometheusMetricWidget`). The Observability page already shows Alertmanager alerts, Prometheus targets, and a hard-coded Grafana base URL (`VITE_GRAFANA_URL`).
+
+However, the integration is still piecemeal:
+
+1. **Hard-coded Grafana URL** in `frontend/src/components/ObservabilityPage.tsx` (`GRAFANA_BASE_URL = import.meta.env.VITE_GRAFANA_URL || "http://localhost:3000"`). This ignores any Grafana service instances configured in the registry.
+2. **No Grafana health/status card** on the Observability page. Users cannot see whether their configured Grafana instance is reachable.
+3. **No Prometheus health/status card**. The targets endpoint shows scrape config, but not whether Prometheus itself is up.
+4. **Prometheus widget only supports instant queries**. There is no range-query chart widget or table widget.
+5. **Grafana widget only supports dashboard deep-links**. There is no "open Explore with a query" shortcut.
+6. **Observability page mixes service-bound and hard-coded sources**. It should derive Grafana/Prometheus URLs from configured service instances instead of env vars.
+
+## Goal
+
+Polish the Grafana/Prometheus integration so the Observability page and dashboard widgets feel first-class:
+
+1. Observability page discovers configured Grafana and Prometheus service instances and uses their `base_url` instead of `VITE_GRAFANA_URL`.
+2. Add health/status cards for Grafana and Prometheus (reachable/unreachable + version if available).
+3. Add backend health-check endpoints for Grafana (`/api/monitoring/grafana-status`) and Prometheus (`/api/monitoring/prometheus-status`) that proxy a lightweight health endpoint.
+4. Extend widget kinds:
+   - Prometheus: add `range_chart` widget kind for simple sparkline charts.
+   - Grafana: add `explore_link` widget kind to open Grafana Explore with a pre-filled query.
+5. Keep the existing `link` and `metric` widgets backward-compatible.
+
+## Non-goals
+
+- Do NOT build a full in-app metric explorer or charting library.
+- Do NOT store Prometheus query history or persist widget state beyond existing dashboard widgets.
+- Do NOT replace the Alertmanager proxy or Prometheus targets endpoint.
+
+## Acceptance
+
+- `VITE_GRAFANA_URL` is no longer required; the Observability page falls back to configured Grafana instances.
+- `/api/monitoring/grafana-status` and `/api/monitoring/prometheus-status` return `{up, version, error?}`.
+- New widget kinds are registered in backend integrations and frontend `SERVICE_REGISTRY`.
+- Frontend lint/build/test and backend pytest remain green.
+- Docs/CHANGELOG updated.