fix(metrics): _total counter detection, runtime-metrics flag wiring, dashboard metric names

- Scalars whose fqName ends in _total are now emitted as Prometheus counters
  (new scalarValueType helper); fixes spec deviation where they were typed as gauges.
- EnableGoCollector/EnableProcessCollector now respect Features.RuntimeMetrics
  instead of being hardcoded true; default behaviour is unchanged.
- Grafana dashboard: prefix HTTP panels with forge_ namespace (forge_http_requests_total,
  forge_http_request_duration_bucket); add uid field for idempotent imports.
- README: document forge_ namespace prefix vs standard go_/process_ names.

Author: juicycleff

examples/observability/README.md

@@ -11,3 +11,13 @@ 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_*`).
+
+## Metric naming
+Forge application metrics (HTTP request counts, latencies, etc.) are emitted under
+the `forge_` namespace prefix — e.g. `forge_http_requests_total`,
+`forge_http_request_duration_bucket`. The namespace is configurable via
+`metrics.collection.namespace` in your Forge config.
+
+Go runtime and process metrics (`go_goroutines`, `go_memstats_*`,
+`process_cpu_seconds_total`, etc.) use their standard unprefixed names; they come
+from the Go and Process collectors registered directly with the Prometheus registry.

examples/observability/grafana-dashboard.json

@@ -1,4 +1,5 @@
 {
+  "uid": "forge-overview",
   "title": "Forge Overview",
   "schemaVersion": 39,
   "version": 1,
@@ -20,7 +21,7 @@
       "datasource": "${datasource}",
       "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
       "targets": [
-        { "expr": "sum(rate(http_requests_total[5m]))", "legendFormat": "rps" }
+        { "expr": "sum(rate(forge_http_requests_total[5m]))", "legendFormat": "rps" }
       ]
     },
     {
@@ -29,7 +30,7 @@
       "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" }
+        { "expr": "histogram_quantile(0.95, sum(rate(forge_http_request_duration_bucket[5m])) by (le))", "legendFormat": "p95" }
       ]
     },
     {

internal/metrics/collector.go

@@ -158,8 +158,8 @@ func New(config *CollectorConfig, logger logger.Logger) Metrics {
 	// Prometheus bridge: reads the merged snapshot fresh on each scrape.
 	c.promBridge = exporters.NewPrometheusBridge(c.GetMetrics, exporters.PrometheusConfig{
 		Namespace:              c.config.Collection.Namespace,
-		EnableGoCollector:      true,
-		EnableProcessCollector: true,
+		EnableGoCollector:      c.config.Features.RuntimeMetrics,
+		EnableProcessCollector: c.config.Features.RuntimeMetrics,
 	})
 
 	// Initialize time-series storage for historical metric queries.

internal/metrics/exporters/prometheus.go

@@ -139,16 +139,29 @@ func (c *forgeCollector) emit(ch chan<- prometheus.Metric, fqName string,
 	keys, vals []string, value any) {
 	switch v := value.(type) {
 	case float64:
-		c.emitScalar(ch, fqName, keys, vals, prometheus.GaugeValue, "gauge", v)
+		vt, kind := scalarValueType(fqName)
+		c.emitScalar(ch, fqName, keys, vals, vt, kind, v)
 	case int64:
-		c.emitScalar(ch, fqName, keys, vals, prometheus.GaugeValue, "gauge", float64(v))
+		vt, kind := scalarValueType(fqName)
+		c.emitScalar(ch, fqName, keys, vals, vt, kind, float64(v))
 	case uint64:
-		c.emitScalar(ch, fqName, keys, vals, prometheus.GaugeValue, "gauge", float64(v))
+		vt, kind := scalarValueType(fqName)
+		c.emitScalar(ch, fqName, keys, vals, vt, kind, float64(v))
 	case map[string]any:
 		c.emitComplex(ch, fqName, keys, vals, v)
 	}
 }
 
+// scalarValueType returns the Prometheus value type and kind string for a scalar
+// metric based on its fully-qualified name. Names ending in "_total" are treated
+// as counters per the Prometheus naming convention; all others are gauges.
+func scalarValueType(fqName string) (prometheus.ValueType, string) {
+	if strings.HasSuffix(fqName, "_total") {
+		return prometheus.CounterValue, "counter"
+	}
+	return prometheus.GaugeValue, "gauge"
+}
+
 func (c *forgeCollector) emitScalar(ch chan<- prometheus.Metric, fqName string,
 	keys, vals []string, vt prometheus.ValueType, kind string, value float64) {
 	desc := prometheus.NewDesc(fqName, helpFor(kind, fqName), keys, nil)

internal/metrics/exporters/prometheus_test.go

@@ -150,6 +150,23 @@ func TestBridge_DedupCollision(t *testing.T) {
 	}
 }
 
+func TestBridge_TotalSuffixIsCounter(t *testing.T) {
+	snapshot := func() map[string]any {
+		return map[string]any{"requests_total": float64(7)}
+	}
+	b := NewPrometheusBridge(snapshot, PrometheusConfig{Namespace: ""})
+
+	expected := `
+# HELP requests_total Forge counter requests_total
+# TYPE requests_total counter
+requests_total 7
+`
+	if err := testutil.CollectAndCompare(b.collector, strings.NewReader(expected),
+		"requests_total"); err != nil {
+		t.Fatalf("unexpected exposition: %v", err)
+	}
+}
+
 func TestBridge_LabelUnion(t *testing.T) {
 	snapshot := func() map[string]any {
 		return map[string]any{