feat: add Prometheus metrics for render cache observability

Callum Styan · Callum Styan · commit acd9bed98e3c · 2025-12-09T22:21:56.000Z
Adds cache hits, misses, and size metrics to track render cache
performance and enable monitoring of the cache's effectiveness
in reducing expensive terraform parsing operations.

Metrics added:
- coderd_prebuilds_render_cache_hits_total: Counter for cache hits
- coderd_prebuilds_render_cache_misses_total: Counter for cache misses
- coderd_prebuilds_render_cache_size_entries: Gauge for current cache size

The metrics are optional and only created when a Prometheus registerer
is provided to the reconciler.
diff --git a/coderd/dynamicparameters/rendercache.go b/coderd/dynamicparameters/rendercache.go
@@ -7,6 +7,7 @@ import (
 	"sync"
 
 	"github.com/google/uuid"
+	"github.com/prometheus/client_golang/prometheus"
 
 	"github.com/coder/preview"
 )
@@ -16,6 +17,11 @@ import (
 type RenderCache struct {
 	mu      sync.RWMutex
 	entries map[cacheKey]*preview.Output
+
+	// Metrics (optional)
+	cacheHits   prometheus.Counter
+	cacheMisses prometheus.Counter
+	cacheSize   prometheus.Gauge
 }
 
 type cacheKey struct {
@@ -31,6 +37,16 @@ func NewRenderCache() *RenderCache {
 	}
 }
 
+// NewRenderCacheWithMetrics creates a new render cache with Prometheus metrics.
+func NewRenderCacheWithMetrics(cacheHits, cacheMisses prometheus.Counter, cacheSize prometheus.Gauge) *RenderCache {
+	return &RenderCache{
+		entries:     make(map[cacheKey]*preview.Output),
+		cacheHits:   cacheHits,
+		cacheMisses: cacheMisses,
+		cacheSize:   cacheSize,
+	}
+}
+
 // NewRenderCacheForTest creates a new render cache for testing purposes.
 func NewRenderCacheForTest() *RenderCache {
 	return NewRenderCache()
@@ -42,6 +58,18 @@ func (c *RenderCache) get(templateVersionID, ownerID uuid.UUID, parameters map[s
 	defer c.mu.RUnlock()
 
 	output, ok := c.entries[key]
+
+	// Record metrics
+	if ok {
+		if c.cacheHits != nil {
+			c.cacheHits.Inc()
+		}
+	} else {
+		if c.cacheMisses != nil {
+			c.cacheMisses.Inc()
+		}
+	}
+
 	return output, ok
 }
 
@@ -51,6 +79,11 @@ func (c *RenderCache) put(templateVersionID, ownerID uuid.UUID, parameters map[s
 	defer c.mu.Unlock()
 
 	c.entries[key] = output
+
+	// Update cache size metric
+	if c.cacheSize != nil {
+		c.cacheSize.Set(float64(len(c.entries)))
+	}
 }
 
 func (c *RenderCache) makeKey(templateVersionID, ownerID uuid.UUID, parameters map[string]string) cacheKey {
diff --git a/coderd/dynamicparameters/rendercache_test.go b/coderd/dynamicparameters/rendercache_test.go
@@ -4,6 +4,8 @@ import (
 	"testing"
 
 	"github.com/google/uuid"
+	"github.com/prometheus/client_golang/prometheus"
+	dto "github.com/prometheus/client_model/go"
 	"github.com/stretchr/testify/require"
 
 	"github.com/coder/preview"
@@ -147,3 +149,121 @@ func TestRenderCache_PrebuildScenario(t *testing.T) {
 
 	// All three prebuilds shared the same cache entry
 }
+
+func TestRenderCache_Metrics(t *testing.T) {
+	t.Parallel()
+
+	// Create test metrics
+	cacheHits := &testCounter{}
+	cacheMisses := &testCounter{}
+	cacheSize := &testGauge{}
+
+	cache := NewRenderCacheWithMetrics(cacheHits, cacheMisses, cacheSize)
+	templateVersionID := uuid.New()
+	ownerID := uuid.New()
+	params := map[string]string{"region": "us-west-2"}
+
+	// Initially: 0 hits, 0 misses, 0 size
+	require.Equal(t, float64(0), cacheHits.value, "initial hits should be 0")
+	require.Equal(t, float64(0), cacheMisses.value, "initial misses should be 0")
+	require.Equal(t, float64(0), cacheSize.value, "initial size should be 0")
+
+	// First get - should be a miss
+	_, ok := cache.get(templateVersionID, ownerID, params)
+	require.False(t, ok)
+	require.Equal(t, float64(0), cacheHits.value, "hits should still be 0")
+	require.Equal(t, float64(1), cacheMisses.value, "misses should be 1")
+	require.Equal(t, float64(0), cacheSize.value, "size should still be 0")
+
+	// Put an entry
+	output := &preview.Output{}
+	cache.put(templateVersionID, ownerID, params, output)
+	require.Equal(t, float64(1), cacheSize.value, "size should be 1 after put")
+
+	// Second get - should be a hit
+	_, ok = cache.get(templateVersionID, ownerID, params)
+	require.True(t, ok)
+	require.Equal(t, float64(1), cacheHits.value, "hits should be 1")
+	require.Equal(t, float64(1), cacheMisses.value, "misses should still be 1")
+	require.Equal(t, float64(1), cacheSize.value, "size should still be 1")
+
+	// Third get - another hit
+	_, ok = cache.get(templateVersionID, ownerID, params)
+	require.True(t, ok)
+	require.Equal(t, float64(2), cacheHits.value, "hits should be 2")
+	require.Equal(t, float64(1), cacheMisses.value, "misses should still be 1")
+
+	// Put another entry with different params
+	params2 := map[string]string{"region": "us-east-1"}
+	cache.put(templateVersionID, ownerID, params2, output)
+	require.Equal(t, float64(2), cacheSize.value, "size should be 2 after second put")
+
+	// Get with different params - should be a hit
+	_, ok = cache.get(templateVersionID, ownerID, params2)
+	require.True(t, ok)
+	require.Equal(t, float64(3), cacheHits.value, "hits should be 3")
+	require.Equal(t, float64(1), cacheMisses.value, "misses should still be 1")
+}
+
+// Test implementations of prometheus interfaces
+type testCounter struct {
+	value float64
+}
+
+func (c *testCounter) Inc() {
+	c.value++
+}
+
+func (c *testCounter) Add(v float64) {
+	c.value += v
+}
+
+func (c *testCounter) Desc() *prometheus.Desc {
+	return nil
+}
+
+func (c *testCounter) Write(*dto.Metric) error {
+	return nil
+}
+
+func (c *testCounter) Describe(chan<- *prometheus.Desc) {}
+
+func (c *testCounter) Collect(chan<- prometheus.Metric) {}
+
+type testGauge struct {
+	value float64
+}
+
+func (g *testGauge) Set(v float64) {
+	g.value = v
+}
+
+func (g *testGauge) Inc() {
+	g.value++
+}
+
+func (g *testGauge) Dec() {
+	g.value--
+}
+
+func (g *testGauge) Add(v float64) {
+	g.value += v
+}
+
+func (g *testGauge) Sub(v float64) {
+	g.value -= v
+}
+
+func (g *testGauge) SetToCurrentTime() {}
+
+func (g *testGauge) Desc() *prometheus.Desc {
+	return nil
+}
+
+func (g *testGauge) Write(*dto.Metric) error {
+	return nil
+}
+
+func (g *testGauge) Describe(chan<- *prometheus.Desc) {}
+
+func (g *testGauge) Collect(chan<- prometheus.Metric) {}
diff --git a/enterprise/coderd/prebuilds/reconcile.go b/enterprise/coderd/prebuilds/reconcile.go
@@ -106,7 +106,6 @@ func NewStoreReconciler(store database.Store,
 		buildUsageChecker: buildUsageChecker,
 		done:              make(chan struct{}, 1),
 		provisionNotifyCh: make(chan database.ProvisionerJob, 10),
-		renderCache:       dynamicparameters.NewRenderCache(),
 	}
 
 	if registerer != nil {
@@ -124,6 +123,30 @@ func NewStoreReconciler(store database.Store,
 			Help:      "Duration of each prebuilds reconciliation cycle.",
 			Buckets:   prometheus.DefBuckets,
 		})
+
+		// Create metrics for the render cache
+		renderCacheHits := factory.NewCounter(prometheus.CounterOpts{
+			Namespace: "coderd",
+			Subsystem: "prebuilds",
+			Name:      "render_cache_hits_total",
+			Help:      "Total number of render cache hits.",
+		})
+		renderCacheMisses := factory.NewCounter(prometheus.CounterOpts{
+			Namespace: "coderd",
+			Subsystem: "prebuilds",
+			Name:      "render_cache_misses_total",
+			Help:      "Total number of render cache misses.",
+		})
+		renderCacheSize := factory.NewGauge(prometheus.GaugeOpts{
+			Namespace: "coderd",
+			Subsystem: "prebuilds",
+			Name:      "render_cache_size_entries",
+			Help:      "Current number of entries in the render cache.",
+		})
+
+		reconciler.renderCache = dynamicparameters.NewRenderCacheWithMetrics(renderCacheHits, renderCacheMisses, renderCacheSize)
+	} else {
+		reconciler.renderCache = dynamicparameters.NewRenderCache()
 	}
 
 	return reconciler
