docs(observability): add prometheus scrape config, servicemonitor, grafana dashboard

Author: juicycleff

examples/observability/README.md

@@ -0,0 +1,13 @@
+# Observability: Prometheus + Grafana
+
+Forge serves Prometheus metrics at `/_/metrics`.
+
+## Scrape with Prometheus
+Use `prometheus.yml` (note `metrics_path: /_/metrics`, not the default `/metrics`).
+
+## Kubernetes (Prometheus Operator)
+Apply `servicemonitor.yaml` (adjust the selector to match your Service labels).
+
+## Grafana
+Import `grafana-dashboard.json` and pick your Prometheus data source. It includes
+HTTP RED panels and Go runtime panels (`go_*`, `process_*`).

examples/observability/grafana-dashboard.json

@@ -0,0 +1,57 @@
+{
+  "title": "Forge Overview",
+  "schemaVersion": 39,
+  "version": 1,
+  "time": { "from": "now-1h", "to": "now" },
+  "templating": {
+    "list": [
+      {
+        "name": "datasource",
+        "type": "datasource",
+        "query": "prometheus",
+        "current": {}
+      }
+    ]
+  },
+  "panels": [
+    {
+      "type": "timeseries",
+      "title": "Request rate",
+      "datasource": "${datasource}",
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
+      "targets": [
+        { "expr": "sum(rate(http_requests_total[5m]))", "legendFormat": "rps" }
+      ]
+    },
+    {
+      "type": "timeseries",
+      "title": "Request p95 latency",
+      "datasource": "${datasource}",
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 },
+      "targets": [
+        { "expr": "histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))", "legendFormat": "p95" }
+      ]
+    },
+    {
+      "type": "timeseries",
+      "title": "Goroutines",
+      "datasource": "${datasource}",
+      "gridPos": { "h": 8, "w": 8, "x": 0, "y": 8 },
+      "targets": [ { "expr": "go_goroutines", "legendFormat": "goroutines" } ]
+    },
+    {
+      "type": "timeseries",
+      "title": "Heap in use",
+      "datasource": "${datasource}",
+      "gridPos": { "h": 8, "w": 8, "x": 8, "y": 8 },
+      "targets": [ { "expr": "go_memstats_heap_inuse_bytes", "legendFormat": "heap" } ]
+    },
+    {
+      "type": "timeseries",
+      "title": "Process CPU",
+      "datasource": "${datasource}",
+      "gridPos": { "h": 8, "w": 8, "x": 16, "y": 8 },
+      "targets": [ { "expr": "rate(process_cpu_seconds_total[5m])", "legendFormat": "cpu" } ]
+    }
+  ]
+}

examples/observability/prometheus.yml

@@ -0,0 +1,6 @@
+scrape_configs:
+  - job_name: forge
+    metrics_path: /_/metrics
+    scrape_interval: 15s
+    static_configs:
+      - targets: ['localhost:8080']  # replace with your Forge app host:port

examples/observability/servicemonitor.yaml

@@ -0,0 +1,14 @@
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: forge
+  labels:
+    release: prometheus
+spec:
+  selector:
+    matchLabels:
+      app: forge
+  endpoints:
+    - port: http
+      path: /_/metrics
+      interval: 15s