refine docs, shell, and makefile

Signed-off-by: JaredforReal <[email protected]>

Author: JaredforReal

tools/make/observability.mk

@@ -7,7 +7,6 @@ OBS_CONFIG_DIR = tools/observability
 OBS_SCRIPTS_DIR = tools/observability/scripts
 
 .PHONY: run-observability stop-observability \
-	obs-local obs-compose obs-logs obs-status obs-clean \
 	o11y-local o11y-compose o11y-logs o11y-status o11y-clean open-observability
 
 ## run-observability: Start observability stack (alias for o11y-local)
@@ -18,21 +17,11 @@ o11y-local:
 	@$(call log, Starting observability in LOCAL mode...)
 	@$(OBS_SCRIPTS_DIR)/start-observability.sh local
 
-## obs-local: Alias for o11y-local (deprecated name)
-obs-local:
-	@echo "Note: 'obs-local' is deprecated, use 'o11y-local' instead" 
-	@$(MAKE) o11y-local
-
 ## o11y-compose: Start observability in COMPOSE mode (all services in Docker)
 o11y-compose:
 	@$(call log, Starting observability in COMPOSE mode...)
 	@$(OBS_SCRIPTS_DIR)/start-observability.sh compose
 
-## obs-compose: Alias for o11y-compose (deprecated name)
-obs-compose:
-	@echo "Note: 'obs-compose' is deprecated, use 'o11y-compose' instead" 
-	@$(MAKE) o11y-compose
-
 ## stop-observability: Stop and remove observability containers
 stop-observability:
 	@$(call log, Stopping observability stack...)
@@ -46,33 +35,18 @@ open-observability:
 
 ## o11y-logs: Show logs from observability containers
 o11y-logs:
-	@docker compose -f $(PWD)/docker-compose.obs.yml logs -f 2>/dev/null || docker compose logs prometheus grafana -f
-
-## obs-logs: Alias for o11y-logs (deprecated name)
-obs-logs:
-	@echo "Note: 'obs-logs' is deprecated, use 'o11y-logs' instead" 
-	@$(MAKE) o11y-logs
+	@docker compose -f docker-compose.obs.yml logs -f 2>/dev/null || docker compose logs prometheus grafana -f
 
 ## o11y-status: Check status of observability containers
 o11y-status:
 	@echo "==> Local mode:"
-	@docker compose -f $(PWD)/docker-compose.obs.yml ps 2>/dev/null || echo "  Not running"
+	@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-status: Alias for o11y-status (deprecated name)
-obs-status:
-	@echo "Note: 'obs-status' is deprecated, use 'o11y-status' instead" 
-	@$(MAKE) o11y-status
-
 ## o11y-clean: Remove observability data volumes
 o11y-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"
-
-## obs-clean: Alias for o11y-clean (deprecated name)
-obs-clean:
-	@echo "Note: 'obs-clean' is deprecated, use 'o11y-clean' instead" 
-	@$(MAKE) o11y-clean

tools/observability/scripts/start-observability.sh

@@ -48,11 +48,11 @@ MODE="${1:-local}"
 case "${MODE}" in
     local)
         log_info "Starting observability in LOCAL mode (router on host, observability in Docker)"
-        COMPOSE_CMD="docker compose -f ${PROJECT_ROOT}/docker-compose.obs.yml"
+        COMPOSE_FILE="${PROJECT_ROOT}/docker-compose.obs.yml"
         ;;
     compose)
         log_info "Starting observability in COMPOSE mode (all services in Docker)"
-        COMPOSE_CMD="docker compose -f ${PROJECT_ROOT}/docker-compose.yml"
+        COMPOSE_FILE="${PROJECT_ROOT}/docker-compose.yml"
         ;;
     *)
         log_error "Invalid mode: ${MODE}"
@@ -78,9 +78,9 @@ if ! docker info &> /dev/null; then
 fi
 
 log_info "Starting services..."
-log_debug "Command: ${COMPOSE_CMD} up -d"
+log_debug "Command: docker compose -f \"${COMPOSE_FILE}\" up -d"
 
-${COMPOSE_CMD} up -d
+docker compose -f "${COMPOSE_FILE}" up -d
 
 # Wait for services to become healthy
 log_info "Waiting for services to become healthy..."

tools/observability/scripts/stop-observability.sh

@@ -34,17 +34,48 @@ echo -e "${BLUE}  Stopping Observability Stack${NC}"
 echo -e "${BLUE}==================================================================${NC}"
 echo ""
 
+# Helpers
+container_exists() {
+    # Returns 0 if a container with the given name exists (in any state)
+    docker ps -a --format '{{.Names}}' | grep -Fxq "$1"
+}
+
+any_container_exists() {
+    # Returns 0 if any of the provided container names exist
+    local name
+    for name in "$@"; do
+        if container_exists "$name"; then
+            return 0
+        fi
+    done
+    return 1
+}
+
 # Stop services
 log_info "Stopping observability services..."
 
 # Try stopping local mode containers first
-if docker ps -a --format '{{.Names}}' | grep -qE '^(prometheus-local|grafana-local)$'; then
+LOCAL_MODE_RUNNING=false
+if any_container_exists "prometheus-local" "grafana-local"; then
+    LOCAL_MODE_RUNNING=true
+fi
+if [ "${LOCAL_MODE_RUNNING}" = true ]; then
     log_info "Stopping local mode containers..."
     docker compose -f "${PROJECT_ROOT}/docker-compose.obs.yml" down
 fi
 
 # Also stop compose mode if running as part of main stack
-if docker ps -a --format '{{.Names}}' | grep -qE '^(prometheus|grafana)$' && ! docker ps -a --format '{{.Names}}' | grep -q 'semantic-router'; then
+COMPOSE_O11Y_RUNNING=false
+if any_container_exists "prometheus" "grafana"; then
+    COMPOSE_O11Y_RUNNING=true
+fi
+
+ROUTER_RUNNING=false
+if container_exists "semantic-router"; then
+    ROUTER_RUNNING=true
+fi
+
+if [ "${COMPOSE_O11Y_RUNNING}" = true ] && [ "${ROUTER_RUNNING}" = false ]; then
     log_warn "Observability containers from main stack are running"
     log_info "Use 'docker compose down' to stop the full stack"
 fi

website/docs/tutorials/observability/observability.md

@@ -53,7 +53,7 @@ make stop-observability
 
 All configs in `tools/observability/`:
 
-- `prometheus.yaml` - Scrapes `localhost:9190` when `ROUTER_TARGET=localhost:9190`
+- `prometheus.yaml` - Scrapes the target from the `ROUTER_TARGET` env var (default: `localhost:9190`)
 - `grafana-datasource.yaml` - Points to `localhost:9090`
 - `grafana-dashboard.yaml` - Dashboard provisioning
 - `llm-router-dashboard.json` - Dashboard definition