Files

T

Developer 4d520ab0e3 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

2.8 KiB

Raw Blame History

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:

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.
No Grafana health/status card on the Observability page. Users cannot see whether their configured Grafana instance is reachable.
No Prometheus health/status card. The targets endpoint shows scrape config, but not whether Prometheus itself is up.
Prometheus widget only supports instant queries. There is no range-query chart widget or table widget.
Grafana widget only supports dashboard deep-links. There is no "open Explore with a query" shortcut.
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:

Observability page discovers configured Grafana and Prometheus service instances and uses their base_url instead of VITE_GRAFANA_URL.
Add health/status cards for Grafana and Prometheus (reachable/unreachable + version if available).
Add backend health-check endpoints for Grafana (/api/monitoring/grafana-status) and Prometheus (/api/monitoring/prometheus-status) that proxy a lightweight health endpoint.
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.
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.

2.8 KiB Raw Blame History