Developer
4d520ab0e3
- 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.
45 lines
2.8 KiB
Markdown
45 lines
2.8 KiB
Markdown
# 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.
|