manage/openspec/changes/grafana-prometheus-polish/tasks.md

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.