feat(metrics): map forge histograms to cumulative prometheus buckets

Author: juicycleff

internal/metrics/exporters/prometheus.go

@@ -131,7 +131,51 @@ func (c *forgeCollector) emitComplex(ch chan<- prometheus.Metric, fqName string,
 		}
 		return
 	}
-	// Histogram / timer mapping is added in later tasks.
+
+	if raw, ok := v["buckets"].(map[float64]uint64); ok {
+		c.emitHistogram(ch, fqName, v, raw, labels)
+		return
+	}
+	// Timer / summary mapping is added in the next task.
+}
+
+func (c *forgeCollector) emitHistogram(ch chan<- prometheus.Metric, fqName string,
+	v map[string]any, perBucket map[float64]uint64, labels map[string]string) {
+	bounds := make([]float64, 0, len(perBucket))
+	for b := range perBucket {
+		bounds = append(bounds, b)
+	}
+	sort.Float64s(bounds)
+
+	cumulative := make(map[float64]uint64, len(bounds))
+	var running uint64
+	for _, b := range bounds {
+		running += perBucket[b]
+		cumulative[b] = running
+	}
+
+	count, _ := toUint64(v["count"])
+	sum, _ := toFloat(v["sum"])
+
+	keys, vals := sortedLabels(labels)
+	desc := prometheus.NewDesc(fqName, helpFor("histogram", fqName), keys, nil)
+	ch <- prometheus.MustNewConstHistogram(desc, count, sum, cumulative, vals...)
+}
+
+func toUint64(v any) (uint64, bool) {
+	switch n := v.(type) {
+	case uint64:
+		return n, true
+	case int64:
+		if n >= 0 {
+			return uint64(n), true
+		}
+	case float64:
+		if n >= 0 {
+			return uint64(n), true
+		}
+	}
+	return 0, false
 }
 
 // =============================================================================

internal/metrics/exporters/prometheus_test.go

@@ -48,3 +48,35 @@ func TestBridge_GatherTextHasNoTimestamps(t *testing.T) {
 		}
 	}
 }
+
+func TestBridge_Histogram(t *testing.T) {
+	snapshot := func() map[string]any {
+		return map[string]any{
+			"request_latency_seconds": map[string]any{
+				"count": uint64(6),
+				"sum":   float64(7.5),
+				"buckets": map[float64]uint64{ // per-bucket (non-cumulative)
+					0.1: 1,
+					0.5: 2,
+					1.0: 3,
+				},
+			},
+		}
+	}
+	b := NewPrometheusBridge(snapshot, PrometheusConfig{})
+
+	expected := `
+# HELP request_latency_seconds Forge histogram request_latency_seconds
+# TYPE request_latency_seconds histogram
+request_latency_seconds_bucket{le="0.1"} 1
+request_latency_seconds_bucket{le="0.5"} 3
+request_latency_seconds_bucket{le="1"} 6
+request_latency_seconds_bucket{le="+Inf"} 6
+request_latency_seconds_sum 7.5
+request_latency_seconds_count 6
+`
+	if err := testutil.CollectAndCompare(b.collector, strings.NewReader(expected),
+		"request_latency_seconds"); err != nil {
+		t.Fatalf("unexpected histogram exposition: %v", err)
+	}
+}