Document TotalCompactions() running-counter semantics

internal/parser/ltf.go

@@ -67,7 +67,7 @@ type ltfContext struct {
 	WindowUsed  int     `json:"window_used"`
 	WindowMax   int     `json:"window_max"`
 	FillPct     float64 `json:"fill_pct"`
-	Compactions int     `json:"compactions"`
+	Compactions int     `json:"compactions"` // running counter: compactions so far in the loop
 	CacheHitPct float64 `json:"cache_hit_pct"`
 }
 

internal/trace/metrics.go

@@ -44,6 +44,11 @@ func (t *Trace) MaxContextFill() float64 {
 	return max
 }
 
+// TotalCompactions returns the total number of context compactions in the
+// loop. ContextState.Compactions is a running counter (compactions so far,
+// not per-iteration), so the max across iterations is the total. Max is used
+// instead of the last iteration's value to be robust to out-of-order
+// iterations.
 func (t *Trace) TotalCompactions() int {
 	var max int
 	for _, it := range t.Iterations {

internal/trace/metrics_test.go

@@ -0,0 +1,16 @@
+package trace
+
+import "testing"
+
+// Compactions is a running counter, so the total is the max across
+// iterations (4 here), not the sum (5).
+func TestTotalCompactionsIsMaxOfRunningCounter(t *testing.T) {
+	tr := &Trace{Iterations: []Iteration{
+		{Number: 1, Context: ContextState{Compactions: 0}},
+		{Number: 2, Context: ContextState{Compactions: 1}},
+		{Number: 3, Context: ContextState{Compactions: 4}},
+	}}
+	if got := tr.TotalCompactions(); got != 4 {
+		t.Errorf("TotalCompactions() = %d, want 4", got)
+	}
+}

internal/trace/types.go

@@ -54,7 +54,7 @@ type ContextState struct {
 	WindowUsed  int
 	WindowMax   int
 	FillPct     float64
-	Compactions int
+	Compactions int // running counter: compactions so far in the loop, not per-iteration
 	CacheHitPct float64
 }