feat(metrics): cache write cost accounting in /metrics (#57)

Closes #52

Add 9 Prometheus metrics for Anthropic prompt cache token usage and
cache boundary state. RecordCacheUsage accepts the Anthropic usage
block directly; RecordCacheBoundary is called by the session boundary
manager after each evaluation.

Co-authored-by: Ona <no-reply@ona.com>

Author: Siddhant-K-code

README.md

@@ -560,6 +560,8 @@ Distill exposes a Prometheus-compatible `/metrics` endpoint on both `api` and `s
 
 ### Metrics
 
+**Pipeline metrics**
+
 | Metric | Type | Description |
 |--------|------|-------------|
 | `distill_requests_total` | Counter | Total requests by endpoint and status code |
@@ -569,6 +571,27 @@ Distill exposes a Prometheus-compatible `/metrics` endpoint on both `api` and `s
 | `distill_active_requests` | Gauge | Currently processing requests |
 | `distill_clusters_formed_total` | Counter | Clusters formed during deduplication |
 
+**Cache cost metrics**
+
+Record Anthropic API usage with `metrics.RecordCacheUsage(UsageRecord{...})` after each API call to track prompt cache efficiency:
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `distill_cache_creation_tokens_total` | Counter | Tokens written to Anthropic cache (charged at 1.25× input price) |
+| `distill_cache_read_tokens_total` | Counter | Tokens read from Anthropic cache (charged at 0.10× input price) |
+| `distill_uncached_input_tokens_total` | Counter | Uncached input tokens (charged at 1.00×) |
+| `distill_cache_hit_rate` | Gauge | Rolling hit rate: `cache_read / (cache_read + cache_creation + input)` |
+| `distill_cache_write_efficiency` | Gauge | Reads/writes ratio — values < 1.0 mean cache writes that expire before being read |
+
+**Cache boundary metrics** (populated by the session boundary manager)
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `distill_cache_boundary_position_tokens` | Gauge | Current boundary position in tokens per session |
+| `distill_cache_boundary_advances_total` | Counter | Times the boundary moved forward (more content became stable) |
+| `distill_cache_boundary_retreats_total` | Counter | Times the boundary retreated (content changed or was evicted) |
+| `distill_cache_estimated_savings_tokens_total` | Counter | Estimated tokens saved by prompt caching |
+
 ### Prometheus Scrape Config
 
 ```yaml
@@ -763,6 +786,7 @@ Distill is evolving from a dedup utility into a context intelligence layer. Here
 | **Session Management** | [#31](https://github.com/Siddhant-K-code/distill/issues/31) | Shipped | Stateful context windows with token budgets, hierarchical compression, and importance-based eviction. See [Session Management](#session-management). |
 | **PatternDetector cache_control annotations** | [#53](https://github.com/Siddhant-K-code/distill/issues/53) | Shipped | `PatternDetector` emits `CacheAnnotation` per chunk and `AnnotateChunksForCache` produces a `CacheControlPlan` with up to 4 Anthropic-compatible markers. |
 | **Session-aware cache boundary manager** | [#51](https://github.com/Siddhant-K-code/distill/issues/51) | Shipped | Auto-advances `cache_control` placement as sessions grow. Stable entries (present ≥ 2 turns unmodified) are included in the cached prefix; boundary retreats when content changes. |
+| **Cache write cost accounting** | [#52](https://github.com/Siddhant-K-code/distill/issues/52) | Shipped | 9 new Prometheus metrics covering Anthropic prompt cache token usage, hit rate, write efficiency, and boundary position. Feed API response usage via `RecordCacheUsage`. |
 
 ### Code Intelligence
 

pkg/metrics/metrics.go

@@ -20,6 +20,20 @@ type Metrics struct {
 	ActiveRequests   prometheus.Gauge
 	ClustersFormed   *prometheus.CounterVec
 
+	// Cache cost accounting (issue #52).
+	// These track Anthropic API usage fields returned in every response.
+	CacheCreationTokens *prometheus.CounterVec
+	CacheReadTokens     *prometheus.CounterVec
+	UncachedInputTokens *prometheus.CounterVec
+	CacheHitRate        prometheus.Gauge
+	CacheWriteEfficiency prometheus.Gauge
+
+	// Cache boundary metrics (issue #51).
+	CacheBoundaryPosition  *prometheus.GaugeVec
+	CacheBoundaryAdvances  *prometheus.CounterVec
+	CacheBoundaryRetreats  *prometheus.CounterVec
+	CacheEstimatedSavings  *prometheus.CounterVec
+
 	registry *prometheus.Registry
 }
 
@@ -75,6 +89,72 @@ func New() *Metrics {
 			},
 			[]string{"endpoint"},
 		),
+
+		// Cache cost accounting.
+		CacheCreationTokens: prometheus.NewCounterVec(
+			prometheus.CounterOpts{
+				Name: "distill_cache_creation_tokens_total",
+				Help: "Tokens written to Anthropic prompt cache (charged at 1.25x input price).",
+			},
+			[]string{"session_id"},
+		),
+		CacheReadTokens: prometheus.NewCounterVec(
+			prometheus.CounterOpts{
+				Name: "distill_cache_read_tokens_total",
+				Help: "Tokens read from Anthropic prompt cache (charged at 0.10x input price).",
+			},
+			[]string{"session_id"},
+		),
+		UncachedInputTokens: prometheus.NewCounterVec(
+			prometheus.CounterOpts{
+				Name: "distill_uncached_input_tokens_total",
+				Help: "Input tokens not served from cache (charged at 1.00x input price).",
+			},
+			[]string{"session_id"},
+		),
+		CacheHitRate: prometheus.NewGauge(
+			prometheus.GaugeOpts{
+				Name: "distill_cache_hit_rate",
+				Help: "Rolling cache hit rate: cache_read / (cache_read + cache_creation + input).",
+			},
+		),
+		CacheWriteEfficiency: prometheus.NewGauge(
+			prometheus.GaugeOpts{
+				Name: "distill_cache_write_efficiency",
+				Help: "Cache read/write ratio. Values < 1.0 indicate writes that expire before being read.",
+			},
+		),
+
+		// Cache boundary metrics.
+		CacheBoundaryPosition: prometheus.NewGaugeVec(
+			prometheus.GaugeOpts{
+				Name: "distill_cache_boundary_position_tokens",
+				Help: "Current cache boundary position in tokens for a session.",
+			},
+			[]string{"session_id"},
+		),
+		CacheBoundaryAdvances: prometheus.NewCounterVec(
+			prometheus.CounterOpts{
+				Name: "distill_cache_boundary_advances_total",
+				Help: "Number of times the cache boundary advanced (more content became stable).",
+			},
+			[]string{"session_id"},
+		),
+		CacheBoundaryRetreats: prometheus.NewCounterVec(
+			prometheus.CounterOpts{
+				Name: "distill_cache_boundary_retreats_total",
+				Help: "Number of times the cache boundary retreated (content changed or was evicted).",
+			},
+			[]string{"session_id"},
+		),
+		CacheEstimatedSavings: prometheus.NewCounterVec(
+			prometheus.CounterOpts{
+				Name: "distill_cache_estimated_savings_tokens_total",
+				Help: "Estimated tokens saved by prompt caching across all sessions.",
+			},
+			[]string{"session_id"},
+		),
+
 		registry: reg,
 	}
 
@@ -85,6 +165,15 @@ func New() *Metrics {
 		m.ReductionRatio,
 		m.ActiveRequests,
 		m.ClustersFormed,
+		m.CacheCreationTokens,
+		m.CacheReadTokens,
+		m.UncachedInputTokens,
+		m.CacheHitRate,
+		m.CacheWriteEfficiency,
+		m.CacheBoundaryPosition,
+		m.CacheBoundaryAdvances,
+		m.CacheBoundaryRetreats,
+		m.CacheEstimatedSavings,
 	)
 
 	return m
@@ -114,6 +203,64 @@ func (m *Metrics) RecordDedup(endpoint string, inputCount, outputCount, clusterC
 	}
 }
 
+// UsageRecord holds the token counts returned by the Anthropic API in the
+// usage block of every response. Pass this to RecordCacheUsage after each
+// API call to keep the cache cost metrics up to date.
+type UsageRecord struct {
+	// SessionID is optional; use "" for non-session requests.
+	SessionID string
+
+	InputTokens              int
+	CacheCreationInputTokens int
+	CacheReadInputTokens     int
+	OutputTokens             int
+}
+
+// RecordCacheUsage records Anthropic API usage fields and updates the derived
+// cache hit rate and write efficiency gauges.
+func (m *Metrics) RecordCacheUsage(u UsageRecord) {
+	sid := u.SessionID
+	if sid == "" {
+		sid = "default"
+	}
+
+	if u.CacheCreationInputTokens > 0 {
+		m.CacheCreationTokens.WithLabelValues(sid).Add(float64(u.CacheCreationInputTokens))
+	}
+	if u.CacheReadInputTokens > 0 {
+		m.CacheReadTokens.WithLabelValues(sid).Add(float64(u.CacheReadInputTokens))
+	}
+	if u.InputTokens > 0 {
+		m.UncachedInputTokens.WithLabelValues(sid).Add(float64(u.InputTokens))
+	}
+
+	// Update derived gauges using the values from this single request.
+	total := float64(u.InputTokens + u.CacheCreationInputTokens + u.CacheReadInputTokens)
+	if total > 0 {
+		hitRate := float64(u.CacheReadInputTokens) / total
+		m.CacheHitRate.Set(hitRate)
+	}
+
+	if u.CacheCreationInputTokens > 0 {
+		efficiency := float64(u.CacheReadInputTokens) / float64(u.CacheCreationInputTokens)
+		m.CacheWriteEfficiency.Set(efficiency)
+	}
+}
+
+// RecordCacheBoundary records a cache boundary evaluation result for a session.
+func (m *Metrics) RecordCacheBoundary(sessionID string, boundaryTokens int, advanced, retreated bool) {
+	if sessionID == "" {
+		sessionID = "default"
+	}
+	m.CacheBoundaryPosition.WithLabelValues(sessionID).Set(float64(boundaryTokens))
+	if advanced {
+		m.CacheBoundaryAdvances.WithLabelValues(sessionID).Inc()
+	}
+	if retreated {
+		m.CacheBoundaryRetreats.WithLabelValues(sessionID).Inc()
+	}
+}
+
 // Middleware returns an HTTP middleware that instruments requests.
 func (m *Metrics) Middleware(endpoint string, next http.HandlerFunc) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {

pkg/metrics/metrics_test.go

@@ -159,6 +159,121 @@ func TestActiveRequests(t *testing.T) {
 	close(release)
 }
 
+func TestRecordCacheUsage(t *testing.T) {
+	m := New()
+
+	m.RecordCacheUsage(UsageRecord{
+		SessionID:                "sess-1",
+		InputTokens:              100,
+		CacheCreationInputTokens: 8000,
+		CacheReadInputTokens:     0,
+		OutputTokens:             200,
+	})
+
+	creationVal := counterValue(t, m.CacheCreationTokens, "session_id", "sess-1")
+	if creationVal != 8000 {
+		t.Errorf("expected 8000 cache creation tokens, got %f", creationVal)
+	}
+
+	uncachedVal := counterValue(t, m.UncachedInputTokens, "session_id", "sess-1")
+	if uncachedVal != 100 {
+		t.Errorf("expected 100 uncached input tokens, got %f", uncachedVal)
+	}
+
+	// Second call: now we have cache reads.
+	m.RecordCacheUsage(UsageRecord{
+		SessionID:                "sess-1",
+		InputTokens:              0,
+		CacheCreationInputTokens: 0,
+		CacheReadInputTokens:     8000,
+		OutputTokens:             200,
+	})
+
+	readVal := counterValue(t, m.CacheReadTokens, "session_id", "sess-1")
+	if readVal != 8000 {
+		t.Errorf("expected 8000 cache read tokens, got %f", readVal)
+	}
+
+	// Hit rate should be 1.0 (all tokens from cache on second call).
+	var hitRateMetric dto.Metric
+	if err := m.CacheHitRate.Write(&hitRateMetric); err != nil {
+		t.Fatalf("read CacheHitRate: %v", err)
+	}
+	if hitRateMetric.GetGauge().GetValue() != 1.0 {
+		t.Errorf("expected hit rate 1.0, got %f", hitRateMetric.GetGauge().GetValue())
+	}
+}
+
+func TestRecordCacheUsage_DefaultSessionID(t *testing.T) {
+	m := New()
+	// Should not panic with empty session ID.
+	m.RecordCacheUsage(UsageRecord{
+		InputTokens:              50,
+		CacheCreationInputTokens: 1000,
+	})
+	val := counterValue(t, m.CacheCreationTokens, "session_id", "default")
+	if val != 1000 {
+		t.Errorf("expected 1000, got %f", val)
+	}
+}
+
+func TestRecordCacheBoundary(t *testing.T) {
+	m := New()
+
+	m.RecordCacheBoundary("sess-1", 8192, true, false)
+	m.RecordCacheBoundary("sess-1", 16384, true, false)
+	m.RecordCacheBoundary("sess-1", 8192, false, true)
+
+	advVal := counterValue(t, m.CacheBoundaryAdvances, "session_id", "sess-1")
+	if advVal != 2 {
+		t.Errorf("expected 2 advances, got %f", advVal)
+	}
+
+	retVal := counterValue(t, m.CacheBoundaryRetreats, "session_id", "sess-1")
+	if retVal != 1 {
+		t.Errorf("expected 1 retreat, got %f", retVal)
+	}
+
+	var posMetric dto.Metric
+	pos, err := m.CacheBoundaryPosition.GetMetricWithLabelValues("sess-1")
+	if err != nil {
+		t.Fatalf("get boundary position: %v", err)
+	}
+	if err := pos.Write(&posMetric); err != nil {
+		t.Fatalf("read boundary position: %v", err)
+	}
+	if posMetric.GetGauge().GetValue() != 8192 {
+		t.Errorf("expected boundary 8192, got %f", posMetric.GetGauge().GetValue())
+	}
+}
+
+func TestHandler_CacheMetrics(t *testing.T) {
+	m := New()
+	m.RecordCacheUsage(UsageRecord{
+		SessionID:                "sess-1",
+		CacheCreationInputTokens: 4096,
+		CacheReadInputTokens:     4096,
+	})
+	m.RecordCacheBoundary("sess-1", 8192, true, false)
+
+	req := httptest.NewRequest(http.MethodGet, "/metrics", nil)
+	rec := httptest.NewRecorder()
+	m.Handler().ServeHTTP(rec, req)
+
+	body := rec.Body.String()
+	for _, metric := range []string{
+		"distill_cache_creation_tokens_total",
+		"distill_cache_read_tokens_total",
+		"distill_cache_hit_rate",
+		"distill_cache_write_efficiency",
+		"distill_cache_boundary_position_tokens",
+	} {
+		if !strings.Contains(body, metric) {
+			t.Errorf("metrics output missing %s", metric)
+		}
+	}
+}
+
 // counterValue extracts the value of a counter with the given label pairs.
 func counterValue(t *testing.T, cv *prometheus.CounterVec, labelPairs ...string) float64 {
 	t.Helper()