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.
107 lines
4.5 KiB
Markdown
107 lines
4.5 KiB
Markdown
# Tasks — Grafana/Prometheus integration polish
|
||
|
||
**Change:** `grafana-prometheus-polish`
|
||
**Phase:** tasks
|
||
**Date:** 2026-06-23
|
||
|
||
## Review workload forecast
|
||
|
||
| Field | Value |
|
||
|-------|-------|
|
||
| Estimated changed lines | ~400–600 |
|
||
| Chained PRs recommended | Yes (2 PRs) |
|
||
| Chain strategy | stacked-to-main |
|
||
|
||
## Slice 1: Backend — health endpoints + widget extensions
|
||
|
||
**Goal:** Surface Grafana/Prometheus health and extend widget kinds.
|
||
|
||
- [ ] **1.1 Add Grafana status endpoint**
|
||
- Files: `backend/src/media_library_viewer_api/routers/monitoring.py`
|
||
- Lines: ~35
|
||
- Details: `GET /api/monitoring/grafana-status` discovers the first enabled `grafana` service, probes `/api/health`, returns `{ up, version, service_id, name, error? }`.
|
||
|
||
- [ ] **1.2 Add Prometheus status endpoint**
|
||
- Files: `backend/src/media_library_viewer_api/routers/monitoring.py`
|
||
- Lines: ~35
|
||
- Details: `GET /api/monitoring/prometheus-status` discovers the first enabled `prometheus` service, probes `/-/healthy` and `/api/v1/status/buildinfo` for version, returns `{ up, version, service_id, name, error? }`.
|
||
|
||
- [ ] **1.3 Add `explore_link` widget kind to Grafana integration**
|
||
- Files: `backend/src/media_library_viewer_api/integrations/grafana.py`, `backend/src/media_library_viewer_api/widgets/sources.py`
|
||
- Lines: ~30
|
||
- Details: New `GrafanaExploreWidgetConfig` with `query` and `datasource`; `GrafanaWidgetSource.fetch` builds an `/explore` deep-link.
|
||
|
||
- [ ] **1.4 Add `range_chart` widget kind to Prometheus integration**
|
||
- Files: `backend/src/media_library_viewer_api/integrations/prometheus.py`, `backend/src/media_library_viewer_api/widgets/sources.py`
|
||
- Lines: ~60
|
||
- Details: New `PrometheusRangeChartWidgetConfig` with `promql`, `range_seconds`, `step`; adapter calls `/api/v1/query_range`, caps `range_seconds` at 86400, reshapes to `{ series: [{ timestamp, value }] }`.
|
||
|
||
- [ ] **1.5 Update backend tests**
|
||
- Files: `backend/tests/test_api.py`, `backend/tests/test_widgets.py`
|
||
- Lines: ~40
|
||
- Details: Test status endpoints with mocked HTTP; test new widget kinds.
|
||
|
||
- [ ] **1.6 Verify backend**
|
||
- Run: `cd backend && .venv/bin/ruff check . && PYTHONPATH=src .venv/bin/python -m pytest`
|
||
|
||
**Slice 1 total:** ~200 changed lines.
|
||
|
||
## Slice 2: Frontend — Observability page + widget registry
|
||
|
||
**Goal:** Remove hard-coded Grafana URL and surface new widgets.
|
||
|
||
- [ ] **2.1 Add status hooks**
|
||
- Files: `frontend/src/hooks/useObservability.ts`, `frontend/src/api/client.ts`
|
||
- Lines: ~30
|
||
- Details: `fetchGrafanaStatus`, `fetchPrometheusStatus`, `useGrafanaStatus()`, `usePrometheusStatus()`.
|
||
|
||
- [ ] **2.2 Update Observability page**
|
||
- Files: `frontend/src/components/ObservabilityPage.tsx`
|
||
- Lines: ~80
|
||
- Details: Discover Grafana/Prometheus services; replace `GRAFANA_BASE_URL`; add health cards; use discovered URLs for links.
|
||
|
||
- [ ] **2.3 Extend widget registry**
|
||
- Files: `frontend/src/integrations/registry.ts`, `frontend/src/widgets/*`
|
||
- Lines: ~80
|
||
- Details: Add `GrafanaExploreLinkWidget` and `PrometheusRangeChartWidget` (or extend existing); register new kinds; update `registry.test.ts`.
|
||
|
||
- [ ] **2.4 Update types**
|
||
- Files: `frontend/src/types/index.ts`
|
||
- Lines: ~20
|
||
- Details: Add `GrafanaStatus`, `PrometheusStatus`, and widget config types.
|
||
|
||
- [ ] **2.5 Update frontend tests**
|
||
- Files: `frontend/src/components/__tests__/ObservabilityPage.test.tsx` if it exists, or relevant widget tests
|
||
- Lines: ~30
|
||
- Details: Mock new hooks/services; assert health cards render.
|
||
|
||
- [ ] **2.6 Verify frontend**
|
||
- Run: `cd frontend && npm run lint && npm run build && npm run test`
|
||
|
||
**Slice 2 total:** ~240 changed lines.
|
||
|
||
## Slice 3: Docs + changelog
|
||
|
||
**Goal:** Document the polished integration.
|
||
|
||
- [ ] **3.1 Update REQUIREMENTS.md**
|
||
- Files: `docs/REQUIREMENTS.md`
|
||
- Lines: ~20
|
||
- Details: Observability section describes service-instance-driven Grafana/Prometheus status cards and new widget kinds.
|
||
|
||
- [ ] **3.2 Update CHANGELOG.md**
|
||
- Files: `CHANGELOG.md`
|
||
- Lines: ~15
|
||
- Details: Added status endpoints, removed hard-coded `VITE_GRAFANA_URL` dependency, new widget kinds.
|
||
|
||
- [ ] **3.3 Commit**
|
||
- Commit message: `feat(observability): polish Grafana/Prometheus integration`
|
||
|
||
## Acceptance
|
||
|
||
- `/api/monitoring/grafana-status` and `/api/monitoring/prometheus-status` return sensible JSON for configured/missing/unreachable services.
|
||
- Observability page no longer references `VITE_GRAFANA_URL`.
|
||
- New widget kinds appear in the "Add widget" flow and render data.
|
||
- Backend and frontend test suites pass.
|
||
- Docs and changelog updated.
|