From 533ac1afab0dff145dca1d610d37a0773c7d7700 Mon Sep 17 00:00:00 2001
From: Josh Creek <8179928+jcreek@users.noreply.github.com>
Date: Tue, 1 Sep 2026 17:24:21 +0100
Subject: [PATCH] ops(multiplayer): wire Prometheus service discovery

---
 .../prometheus-service-monitor.yaml           | 20 +++++++++++++++++++
 docs/OBSERVABILITY.md                         |  7 +++++--
 multiplayer-next.md                           |  2 +-
 3 files changed, 26 insertions(+), 3 deletions(-)
 create mode 100644 deploy/observability/prometheus-service-monitor.yaml

diff --git a/deploy/observability/prometheus-service-monitor.yaml b/deploy/observability/prometheus-service-monitor.yaml
new file mode 100644
index 00000000..7457a4a6
--- /dev/null
+++ b/deploy/observability/prometheus-service-monitor.yaml
@@ -0,0 +1,20 @@
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: cosmic-clash-control-plane
+  namespace: cosmic-clash
+  labels:
+    app.kubernetes.io/name: cosmic-clash
+    app.kubernetes.io/component: observability
+spec:
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: control-plane
+  namespaceSelector:
+    matchNames:
+      - cosmic-clash
+  endpoints:
+    - port: http
+      path: /metrics
+      interval: 15s
+      scrapeTimeout: 5s
diff --git a/docs/OBSERVABILITY.md b/docs/OBSERVABILITY.md
index 85672f8a..e43cde9f 100644
--- a/docs/OBSERVABILITY.md
+++ b/docs/OBSERVABILITY.md
@@ -4,10 +4,13 @@ The control plane exposes `/metrics` with bounded operation and status labels.
 The API latency metric is a cumulative histogram, so Prometheus can evaluate
 the documented 250 ms p95 SLO with `histogram_quantile`. The optional
 `deploy/observability/prometheus-rules.yaml` resource provides the API p95 and
-5xx alerts for clusters running the Prometheus Operator.
+5xx alerts for clusters running the Prometheus Operator. The matching optional
+`deploy/observability/prometheus-service-monitor.yaml` discovers the internal
+control-plane Service on its named `http` port and scrapes only `/metrics`.
 
 Install the rule only after confirming that the `PrometheusRule` CRD and the
-`cosmic-clash` namespace exist. The example `runbook_url` values are
+`ServiceMonitor` CRD and the `cosmic-clash` namespace exist. The example
+`runbook_url` values are
 placeholders and must be replaced with the operator's incident documentation
 before production use.
 
diff --git a/multiplayer-next.md b/multiplayer-next.md
index 7a4a8d38..99fed0b0 100644
--- a/multiplayer-next.md
+++ b/multiplayer-next.md
@@ -1453,7 +1453,7 @@ Observability redaction now adds content-aware protection on top of denylisted f
 
 ### Current local completion index (2026-09-01)
 
-The following Phase 8 slices have local implementation and verification evidence in this document: 8.29 dynamic allocated launch flags and endpoint handling; 8.30 allocator claim/reconciliation; 8.31 signed assignment/roster validation; 8.35 initial-connect no-show and casual bot policy; 8.36 controlled drain and shutdown acknowledgment; 8.39–8.43 client state, assignment, profile, recovery, and idempotent action retry; 8.44 structured observability and content-aware redaction; 8.45 bounded API metrics export and optional Prometheus alert rules; 8.46 normal/race/vet/fuzz coverage; and 8.47–8.48 offline testkit coverage. Their remaining acceptance text is infrastructure or production dependent where explicitly noted below the corresponding row.
+The following Phase 8 slices have local implementation and verification evidence in this document: 8.29 dynamic allocated launch flags and endpoint handling; 8.30 allocator claim/reconciliation; 8.31 signed assignment/roster validation; 8.35 initial-connect no-show and casual bot policy; 8.36 controlled drain and shutdown acknowledgment; 8.39–8.43 client state, assignment, profile, recovery, and idempotent action retry; 8.44 structured observability and content-aware redaction; 8.45 bounded API metrics export plus optional Prometheus scrape/alert rules; 8.46 normal/race/vet/fuzz coverage; and 8.47–8.48 offline testkit coverage. Their remaining acceptance text is infrastructure or production dependent where explicitly noted below the corresponding row.
 
 The following are not locally certifiable from this workspace and remain open prerequisites rather than silently “done”: Valve/GodotSteam credentials and hosted SDR (7.1–7.8), live PostgreSQL/Redis execution where Docker is unavailable, live Agones/kind lifecycle (8.30–8.38, 8.49), public-network chaos/load/cost/release gates (8.50–8.53), and real-hardware graphics profiling (0.15b onward). `TODO.md`’s AI-training and presentation tasks remain separate from multiplayer and are not marked by this index.