feat: refactor observability configs for Compose and add for Local

Makefile

@@ -16,6 +16,7 @@ _run:
 		-f tools/make/pre-commit.mk \
 		-f tools/make/docker.mk \
 		-f tools/make/kube.mk \
+		-f tools/make/observability.mk \
 		$(MAKECMDGOALS)
 
 .PHONY: _run

docker-compose.obs.yml

@@ -0,0 +1,42 @@
+# Local observability stack for monitoring semantic-router running on host
+#
+# Usage: make obs-local
+# Or: docker compose -f docker-compose.obs.yml up
+#
+# This provides Prometheus and Grafana in Docker with network_mode: host
+# to scrape metrics from router running natively on localhost:9190
+
+version: '3.8'
+
+services:
+  prometheus:
+    image: prom/prometheus:v2.53.0
+    container_name: prometheus-local
+    network_mode: host
+    volumes:
+      - ./tools/observability/prometheus.yaml:/etc/prometheus/prometheus.yaml:ro
+      - prometheus-local-data:/prometheus
+    command:
+      - '--config.file=/etc/prometheus/prometheus.yaml'
+      - '--storage.tsdb.path=/prometheus'
+      - '--storage.tsdb.retention.time=15d'
+    environment:
+      - ROUTER_TARGET=localhost:9190
+
+  grafana:
+    image: grafana/grafana:11.5.1
+    container_name: grafana-local
+    network_mode: host
+    volumes:
+      - ./tools/observability/grafana-datasource.yaml:/etc/grafana/provisioning/datasources/datasource.yaml:ro
+      - ./tools/observability/grafana-dashboard.yaml:/etc/grafana/provisioning/dashboards/dashboard.yaml:ro
+      - ./tools/observability/llm-router-dashboard.json:/etc/grafana/provisioning/dashboards/llm-router-dashboard.json:ro
+      - grafana-local-data:/var/lib/grafana
+    environment:
+      - PROMETHEUS_URL=localhost:9090
+      - GF_SECURITY_ADMIN_PASSWORD=admin
+      - GF_USERS_ALLOW_SIGN_UP=false
+
+volumes:
+  prometheus-local-data:
+  grafana-local-data:

docker-compose.yml

@@ -69,10 +69,13 @@ services:
     image: prom/prometheus:v2.53.0
     container_name: prometheus
     volumes:
-      - ./config/prometheus.yaml:/etc/prometheus/prometheus.yaml:ro
+      - ./tools/observability/prometheus.yaml:/etc/prometheus/prometheus.yaml:ro
+      - prometheus-data:/prometheus
     command:
       - --config.file=/etc/prometheus/prometheus.yaml
       - --storage.tsdb.retention.time=15d
+    environment:
+      - ROUTER_TARGET=semantic-router:9190
     ports:
       - "9090:9090"
     networks:
@@ -84,14 +87,18 @@ services:
     environment:
       - GF_SECURITY_ADMIN_USER=admin
       - GF_SECURITY_ADMIN_PASSWORD=admin
+      - PROMETHEUS_URL=prometheus:9090
     ports:
       - "3000:3000"
     volumes:
-      - ./config/grafana/datasource.yaml:/etc/grafana/provisioning/datasources/datasource.yaml:ro
-      - ./config/grafana/dashboards.yaml:/etc/grafana/provisioning/dashboards/dashboards.yaml:ro
-      - ./deploy/llm-router-dashboard.json:/etc/grafana/provisioning/dashboards/llm-router-dashboard.json:ro
+      - ./tools/observability/grafana-datasource.yaml:/etc/grafana/provisioning/datasources/datasource.yaml:ro
+      - ./tools/observability/grafana-dashboard.yaml:/etc/grafana/provisioning/dashboards/dashboard.yaml:ro
+      - ./tools/observability/llm-router-dashboard.json:/etc/grafana/provisioning/dashboards/llm-router-dashboard.json:ro
+      - grafana-data:/var/lib/grafana
     networks:
       - semantic-network
+    depends_on:
+      - prometheus
 
   # LLM Katan service for testing
   llm-katan:
@@ -118,3 +125,5 @@ networks:
 volumes:
   models-cache:
     driver: local
+  prometheus-data:
+  grafana-data:

tools/make/common.mk

@@ -85,6 +85,16 @@ help:
 	@echo "    docs-serve              - Serve built documentation"
 	@echo "    docs-clean              - Clean documentation artifacts"
 	@echo ""
+	@echo "  Observability targets:"
+	@echo "    run-observability       - Start observability (alias for obs-local)"
+	@echo "    obs-local               - Start observability in LOCAL mode"
+	@echo "    obs-compose             - Start observability in COMPOSE mode"
+	@echo "    stop-observability      - Stop observability stack"
+	@echo "    open-observability      - Open Prometheus and Grafana in browser"
+	@echo "    obs-status              - Check observability stack status"
+	@echo "    obs-logs                - Show observability logs"
+	@echo "    obs-clean               - Remove observability data volumes"
+	@echo ""
 	@echo "  Environment variables:"
 	@echo "    CONTAINER_RUNTIME       - Container runtime (docker|podman, default: docker)"
 	@echo "    CONFIG_FILE             - Config file path (default: config/config.yaml)"

tools/make/observability.mk

@@ -0,0 +1,51 @@
+# ====================== observability.mk ======================
+# = Observability targets for semantic-router monitoring       =
+# ====================== observability.mk ======================
+
+# Observability directories
+OBS_CONFIG_DIR = tools/observability
+OBS_SCRIPTS_DIR = tools/observability/scripts
+
+.PHONY: run-observability stop-observability obs-local obs-compose open-observability obs-logs obs-status obs-clean
+
+## run-observability: Start observability stack (alias for obs-local)
+run-observability: obs-local
+
+## obs-local: Start observability in LOCAL mode (router on host, obs in Docker)
+obs-local:
+	@$(call log, Starting observability in LOCAL mode...)
+	@$(OBS_SCRIPTS_DIR)/start-observability.sh local
+
+## obs-compose: Start observability in COMPOSE mode (all services in Docker)
+obs-compose:
+	@$(call log, Starting observability in COMPOSE mode...)
+	@$(OBS_SCRIPTS_DIR)/start-observability.sh compose
+
+## stop-observability: Stop and remove observability containers
+stop-observability:
+	@$(call log, Stopping observability stack...)
+	@$(OBS_SCRIPTS_DIR)/stop-observability.sh
+
+## open-observability: Open Prometheus and Grafana in browser
+open-observability:
+	@echo "Opening Prometheus and Grafana..."
+	@open http://localhost:9090 2>/dev/null || xdg-open http://localhost:9090 2>/dev/null || echo "Please open http://localhost:9090"
+	@open http://localhost:3000 2>/dev/null || xdg-open http://localhost:3000 2>/dev/null || echo "Please open http://localhost:3000"
+
+## obs-logs: Show logs from observability containers
+obs-logs:
+	@docker compose -f docker-compose.obs.yml logs -f 2>/dev/null || docker compose logs prometheus grafana -f
+
+## obs-status: Check status of observability containers
+obs-status:
+	@echo "==> Local mode:"
+	@docker compose -f docker-compose.obs.yml ps 2>/dev/null || echo "  Not running"
+	@echo ""
+	@echo "==> Compose mode:"
+	@docker compose ps prometheus grafana 2>/dev/null || echo "  Not running"
+
+## obs-clean: Remove observability data volumes
+obs-clean:
+	@echo "⚠️  Removing all observability data volumes..."
+	@docker volume rm prometheus-local-data grafana-local-data prometheus-data grafana-data 2>/dev/null || true
+	@echo "✓ Done"

tools/observability/README.md

@@ -0,0 +1,30 @@
+# Observability Configuration
+
+Prometheus and Grafana configuration files for monitoring semantic-router.
+
+## Files
+
+- `prometheus.yaml` - Prometheus scrape config (uses `$ROUTER_TARGET` env var)
+- `grafana-datasource.yaml` - Grafana datasource (uses `$PROMETHEUS_URL` env var)
+- `grafana-dashboard.yaml` - Dashboard provisioning config
+- `llm-router-dashboard.json` - LLM Router dashboard
+
+## Usage
+
+**Local mode** (router on host, observability in Docker):
+
+```bash
+make obs-local
+```
+
+**Compose mode** (all services in Docker):
+
+```bash
+make obs-compose
+# or: docker compose up
+```
+
+**Access:**
+
+- Prometheus: http://localhost:9090
+- Grafana: http://localhost:3000 (admin/admin)

tools/observability/grafana-dashboard.yaml

@@ -0,0 +1,15 @@
+# Grafana dashboard provisioning configuration
+# This file tells Grafana where to find dashboard JSON files
+
+apiVersion: 1
+
+providers:
+  - name: "Semantic Router"
+    orgId: 1
+    folder: ""
+    type: file
+    disableDeletion: false
+    updateIntervalSeconds: 10
+    allowUiUpdates: true
+    options:
+      path: /etc/grafana/provisioning/dashboards

tools/observability/grafana-datasource.yaml

@@ -0,0 +1,14 @@
+# Grafana datasource configuration for Prometheus
+# This file is provisioned automatically when Grafana starts
+
+apiVersion: 1
+
+datasources:
+  - name: Prometheus
+    type: prometheus
+    access: proxy
+    url: http://${PROMETHEUS_URL:-localhost:9090}
+    isDefault: true
+    editable: true
+    jsonData:
+      timeInterval: 15s