# 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.