Add opt-in Vec TTL via MetricVec and TTLRegistry

prometheus/counter.go

@@ -201,6 +201,12 @@ func NewCounterVec(opts CounterOpts, labelNames []string) *CounterVec {
 
 // NewCounterVec creates a new CounterVec based on the provided CounterVecOpts.
 func (v2) NewCounterVec(opts CounterVecOpts) *CounterVec {
+	return newCounterVecWithTTL(opts, 0)
+}
+
+// newCounterVecWithTTL creates a CounterVec. ttl must be >= 0; ttl == 0 disables
+// TTL behavior (identical to NewMetricVec).
+func newCounterVecWithTTL(opts CounterVecOpts, ttl time.Duration) *CounterVec {
 	desc := V2.NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
@@ -211,16 +217,22 @@ func (v2) NewCounterVec(opts CounterVecOpts) *CounterVec {
 	if opts.now == nil {
 		opts.now = time.Now
 	}
+	newMetric := func(lvs ...string) Metric {
+		if len(lvs) != len(desc.variableLabels.names) {
+			panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels.names, lvs))
+		}
+		result := &counter{desc: desc, labelPairs: MakeLabelPairs(desc, lvs), now: opts.now}
+		result.init(result) // Init self-collection.
+		result.createdTs = timestamppb.New(opts.now())
+		return result
+	}
+	if ttl > 0 {
+		return &CounterVec{
+			MetricVec: NewMetricVecWithTTL(desc, newMetric, ttl),
+		}
+	}
 	return &CounterVec{
-		MetricVec: NewMetricVec(desc, func(lvs ...string) Metric {
-			if len(lvs) != len(desc.variableLabels.names) {
-				panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels.names, lvs))
-			}
-			result := &counter{desc: desc, labelPairs: MakeLabelPairs(desc, lvs), now: opts.now}
-			result.init(result) // Init self-collection.
-			result.createdTs = timestamppb.New(opts.now())
-			return result
-		}),
+		MetricVec: NewMetricVec(desc, newMetric),
 	}
 }
 

prometheus/gauge.go

@@ -159,22 +159,32 @@ func NewGaugeVec(opts GaugeOpts, labelNames []string) *GaugeVec {
 
 // NewGaugeVec creates a new GaugeVec based on the provided GaugeVecOpts.
 func (v2) NewGaugeVec(opts GaugeVecOpts) *GaugeVec {
+	return newGaugeVecWithTTL(opts, 0)
+}
+
+func newGaugeVecWithTTL(opts GaugeVecOpts, ttl time.Duration) *GaugeVec {
 	desc := V2.NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
 		opts.VariableLabels,
 		opts.ConstLabels,
 		WithUnit(opts.Unit),
 	)
+	newMetric := func(lvs ...string) Metric {
+		if len(lvs) != len(desc.variableLabels.names) {
+			panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels.names, lvs))
+		}
+		result := &gauge{desc: desc, labelPairs: MakeLabelPairs(desc, lvs)}
+		result.init(result) // Init self-collection.
+		return result
+	}
+	if ttl > 0 {
+		return &GaugeVec{
+			MetricVec: NewMetricVecWithTTL(desc, newMetric, ttl),
+		}
+	}
 	return &GaugeVec{
-		MetricVec: NewMetricVec(desc, func(lvs ...string) Metric {
-			if len(lvs) != len(desc.variableLabels.names) {
-				panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels.names, lvs))
-			}
-			result := &gauge{desc: desc, labelPairs: MakeLabelPairs(desc, lvs)}
-			result.init(result) // Init self-collection.
-			return result
-		}),
+		MetricVec: NewMetricVec(desc, newMetric),
 	}
 }
 

prometheus/histogram.go

@@ -1189,17 +1189,27 @@ func NewHistogramVec(opts HistogramOpts, labelNames []string) *HistogramVec {
 
 // NewHistogramVec creates a new HistogramVec based on the provided HistogramVecOpts.
 func (v2) NewHistogramVec(opts HistogramVecOpts) *HistogramVec {
+	return newHistogramVecWithTTL(opts, 0)
+}
+
+func newHistogramVecWithTTL(opts HistogramVecOpts, ttl time.Duration) *HistogramVec {
 	desc := V2.NewDesc(
 		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
 		opts.Help,
 		opts.VariableLabels,
 		opts.ConstLabels,
 		WithUnit(opts.Unit),
 	)
+	newMetric := func(lvs ...string) Metric {
+		return newHistogram(desc, opts.HistogramOpts, lvs...)
+	}
+	if ttl > 0 {
+		return &HistogramVec{
+			MetricVec: NewMetricVecWithTTL(desc, newMetric, ttl),
+		}
+	}
 	return &HistogramVec{
-		MetricVec: NewMetricVec(desc, func(lvs ...string) Metric {
-			return newHistogram(desc, opts.HistogramOpts, lvs...)
-		}),
+		MetricVec: NewMetricVec(desc, newMetric),
 	}
 }
 

prometheus/ttl_registry.go

@@ -0,0 +1,165 @@
+// Copyright 2014 The Prometheus Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package prometheus
+
+import (
+	"sync"
+	"time"
+
+	dto "github.com/prometheus/client_model/go"
+)
+
+// TTLRegistry is a dedicated Prometheus registry for metrics that need
+// time-to-live behavior on *Vec children. It embeds a plain *Registry and adds:
+//   - Vec constructors that enable per-child TTL (same semantics as MetricVec
+//     built with NewMetricVecWithTTL).
+//   - Automatic CleanupExpired on all Vecs created through this registry before
+//     each Gather, so memory can be reclaimed even when scrapes are infrequent
+//     (see discussion in https://github.com/prometheus/client_golang/issues/1983).
+//
+// Default prometheus.NewRegistry, NewCounterVec, and Opts are unchanged; use
+// TTLRegistry only when you explicitly opt in to Vec TTL.
+type TTLRegistry struct {
+	*Registry
+
+	ttl time.Duration
+
+	mu   sync.Mutex
+	vecs []*MetricVec
+}
+
+// NewTTLRegistry returns a registry backed by a new empty *Registry. ttl must
+// be greater than zero; it applies to every Vec created via this registry's
+// constructor methods.
+func NewTTLRegistry(ttl time.Duration) *TTLRegistry {
+	if ttl <= 0 {
+		panic("NewTTLRegistry: ttl must be > 0")
+	}
+	return &TTLRegistry{
+		Registry: NewRegistry(),
+		ttl:      ttl,
+	}
+}
+
+func (r *TTLRegistry) track(mv *MetricVec) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.vecs = append(r.vecs, mv)
+}
+
+func (r *TTLRegistry) untrack(mv *MetricVec) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for i, v := range r.vecs {
+		if v == mv {
+			last := len(r.vecs) - 1
+			r.vecs[i] = r.vecs[last]
+			r.vecs[last] = nil
+			r.vecs = r.vecs[:last]
+			return
+		}
+	}
+}
+
+func metricVecFromCollector(c Collector) *MetricVec {
+	switch v := c.(type) {
+	case *CounterVec:
+		return v.MetricVec
+	case *GaugeVec:
+		return v.MetricVec
+	case *HistogramVec:
+		return v.MetricVec
+	case *MetricVec:
+		return v
+	default:
+		return nil
+	}
+}
+
+// Unregister implements Registerer. It untracks Vecs created through this
+// registry so they are no longer retained or cleaned up on Gather.
+func (r *TTLRegistry) Unregister(c Collector) bool {
+	ok := r.Registry.Unregister(c)
+	if ok {
+		if mv := metricVecFromCollector(c); mv != nil {
+			r.untrack(mv)
+		}
+	}
+	return ok
+}
+
+func (r *TTLRegistry) runCleanup() {
+	r.mu.Lock()
+	vecs := append([]*MetricVec(nil), r.vecs...)
+	r.mu.Unlock()
+	for _, mv := range vecs {
+		mv.CleanupExpired()
+	}
+}
+
+// Gather implements Gatherer. It runs CleanupExpired on all Vecs created
+// through this TTLRegistry, then delegates to the embedded Registry.
+func (r *TTLRegistry) Gather() ([]*dto.MetricFamily, error) {
+	r.runCleanup()
+	return r.Registry.Gather()
+}
+
+// NewCounterVec is like prometheus.NewCounterVec but enables Vec TTL using this
+// registry's ttl, registers the Vec, and tracks it for Gather-time cleanup.
+func (r *TTLRegistry) NewCounterVec(opts CounterOpts, labelNames []string) *CounterVec {
+	return r.NewCounterVecOpts(CounterVecOpts{
+		CounterOpts:    opts,
+		VariableLabels: UnconstrainedLabels(labelNames),
+	})
+}
+
+// NewCounterVecOpts is like V2.NewCounterVec with TTL and automatic registration.
+func (r *TTLRegistry) NewCounterVecOpts(opts CounterVecOpts) *CounterVec {
+	cv := newCounterVecWithTTL(opts, r.ttl)
+	r.MustRegister(cv)
+	r.track(cv.MetricVec)
+	return cv
+}
+
+// NewGaugeVec is like prometheus.NewGaugeVec with TTL, registration, and tracking.
+func (r *TTLRegistry) NewGaugeVec(opts GaugeOpts, labelNames []string) *GaugeVec {
+	return r.NewGaugeVecOpts(GaugeVecOpts{
+		GaugeOpts:      opts,
+		VariableLabels: UnconstrainedLabels(labelNames),
+	})
+}
+
+// NewGaugeVecOpts is like V2.NewGaugeVec with TTL and automatic registration.
+func (r *TTLRegistry) NewGaugeVecOpts(opts GaugeVecOpts) *GaugeVec {
+	gv := newGaugeVecWithTTL(opts, r.ttl)
+	r.MustRegister(gv)
+	r.track(gv.MetricVec)
+	return gv
+}
+
+// NewHistogramVec is like prometheus.NewHistogramVec with TTL, registration, and tracking.
+func (r *TTLRegistry) NewHistogramVec(opts HistogramOpts, labelNames []string) *HistogramVec {
+	return r.NewHistogramVecOpts(HistogramVecOpts{
+		HistogramOpts:  opts,
+		VariableLabels: UnconstrainedLabels(labelNames),
+	})
+}
+
+// NewHistogramVecOpts is like V2.NewHistogramVec with TTL and automatic registration.
+func (r *TTLRegistry) NewHistogramVecOpts(opts HistogramVecOpts) *HistogramVec {
+	hv := newHistogramVecWithTTL(opts, r.ttl)
+	r.MustRegister(hv)
+	r.track(hv.MetricVec)
+	return hv
+}

prometheus/ttl_registry_test.go

@@ -0,0 +1,95 @@
+// Copyright 2014 The Prometheus Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package prometheus
+
+import (
+	"testing"
+	"testing/synctest"
+	"time"
+)
+
+func TestNewTTLRegistryPanicsOnNonPositiveTTL(t *testing.T) {
+	defer func() {
+		if recover() == nil {
+			t.Fatal("expected panic for ttl <= 0")
+		}
+	}()
+	NewTTLRegistry(0)
+}
+
+func TestTTLRegistryUnregisterUntracks(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		ttl := 80 * time.Millisecond
+		reg := NewTTLRegistry(ttl)
+		vec := reg.NewCounterVec(CounterOpts{
+			Name: "ttl_reg_unregister",
+			Help: "test",
+		}, []string{"code"})
+
+		vec.WithLabelValues("200").Add(1)
+		if !reg.Unregister(vec) {
+			t.Fatal("expected Unregister to succeed")
+		}
+
+		time.Sleep(ttl + 40*time.Millisecond)
+
+		if _, err := reg.Gather(); err != nil {
+			t.Fatal(err)
+		}
+
+		// Gather should not have run CleanupExpired on the unregistered vec.
+		if cleaned := vec.CleanupExpired(); cleaned != 1 {
+			t.Fatalf("expected 1 expired child after explicit cleanup, got %d", cleaned)
+		}
+
+		vec2 := reg.NewCounterVec(CounterOpts{
+			Name: "ttl_reg_still_tracked",
+			Help: "test",
+		}, []string{"code"})
+		vec2.WithLabelValues("200").Add(1)
+		time.Sleep(ttl + 40*time.Millisecond)
+		if _, err := reg.Gather(); err != nil {
+			t.Fatal(err)
+		}
+		if cleaned := vec2.CleanupExpired(); cleaned != 0 {
+			t.Fatalf("expected tracked vec cleaned on Gather, got %d remaining", cleaned)
+		}
+	})
+}
+
+func TestTTLRegistryGatherRunsCleanup(t *testing.T) {
+	synctest.Test(t, func(t *testing.T) {
+		ttl := 80 * time.Millisecond
+		reg := NewTTLRegistry(ttl)
+		vec := reg.NewCounterVec(CounterOpts{
+			Name: "ttl_reg_gather",
+			Help: "test",
+		}, []string{"code"})
+
+		vec.WithLabelValues("200").Add(1)
+		if n := collectCount(vec); n != 1 {
+			t.Fatalf("expected 1 metric before sleep, got %d", n)
+		}
+
+		time.Sleep(ttl + 40*time.Millisecond)
+
+		if _, err := reg.Gather(); err != nil {
+			t.Fatal(err)
+		}
+
+		if n := collectCount(vec); n != 0 {
+			t.Fatalf("expected 0 metrics after Gather cleanup, got %d", n)
+		}
+	})
+}