Add lifecycle endpoint to clear metrics

CHANGELOG.md

@@ -1,3 +1,7 @@
+## unreleased
+
+* [FEATURE] Add a lifecycle `/-/clear` endpoint to clear registered StatsD time series without restarting the exporter ([#714](https://github.com/prometheus/statsd_exporter/pull/714))
+
 ## 0.30.0 / 2026-05-28
 * [CHANGE] Remove the Dockerfile `HEALTHCHECK` from published container images ([#671](https://github.com/prometheus/statsd_exporter/pull/671))
 * [ENHANCEMENT] Add a distroless container image variant ([#703](https://github.com/prometheus/statsd_exporter/pull/703))

README.md

@@ -113,8 +113,8 @@ NOTE: Version 0.7.0 switched to the [kingpin](https://github.com/alecthomas/king
 
 ## Lifecycle API
 
-The `statsd_exporter` has an optional lifecycle API (disabled by default) that can be used to reload or quit the exporter 
-by sending a `PUT` or `POST` request to the `/-/reload` or `/-/quit` endpoints.
+The `statsd_exporter` has an optional lifecycle API (disabled by default) that can be used to reload, quit, or clear the exporter
+by sending a `PUT` or `POST` request to the `/-/reload`, `/-/quit`, or `/-/clear` endpoints.
 
 ## Relay
 

main.go

@@ -205,6 +205,20 @@ func reloadConfig(fileName string, mapper *mapper.MetricMapper, logger *slog.Log
 	}
 }
 
+type metricsClearer interface {
+	ClearMetrics() int
+}
+
+func clearMetricsHandler(clearer metricsClearer, logger *slog.Logger) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodPut || r.Method == http.MethodPost {
+			cleared := clearer.ClearMetrics()
+			logger.Info("Received lifecycle api clear", "metrics", cleared)
+			fmt.Fprintf(w, "Cleared %d metric series", cleared)
+		}
+	}
+}
+
 func dumpFSM(mapper *mapper.MetricMapper, dumpFilename string, logger *slog.Logger) error {
 	f, err := os.Create(dumpFilename)
 	if err != nil {
@@ -528,6 +542,7 @@ func main() {
 				quitChan <- struct{}{}
 			}
 		})
+		mux.HandleFunc("/-/clear", clearMetricsHandler(exporter, logger))
 	}
 
 	mux.HandleFunc("/-/healthy", func(w http.ResponseWriter, r *http.Request) {

main_test.go

@@ -0,0 +1,50 @@
+// Copyright 2026 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 main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/prometheus/common/promslog"
+)
+
+type fakeMetricsClearer struct {
+	cleared int
+	called  int
+}
+
+func (f *fakeMetricsClearer) ClearMetrics() int {
+	f.called++
+	return f.cleared
+}
+
+func TestClearMetricsHandler(t *testing.T) {
+	clearer := &fakeMetricsClearer{cleared: 3}
+	handler := clearMetricsHandler(clearer, promslog.NewNopLogger())
+
+	request := httptest.NewRequest(http.MethodPost, "/-/clear", nil)
+	response := httptest.NewRecorder()
+
+	handler.ServeHTTP(response, request)
+
+	if clearer.called != 1 {
+		t.Fatalf("expected clearer to be called once, got %d", clearer.called)
+	}
+	if body := response.Body.String(); !strings.Contains(body, "Cleared 3 metric series") {
+		t.Fatalf("unexpected response body: %q", body)
+	}
+}

pkg/exporter/exporter.go

@@ -37,6 +37,7 @@ type Registry interface {
 	GetHistogram(metricName string, labels prometheus.Labels, help string, mapping *mapper.MetricMapping, metricsCount *prometheus.GaugeVec) (prometheus.Observer, error)
 	GetSummary(metricName string, labels prometheus.Labels, help string, mapping *mapper.MetricMapping, metricsCount *prometheus.GaugeVec) (prometheus.Observer, error)
 	RemoveStaleMetrics()
+	ClearMetrics() int
 }
 
 type Exporter struct {
@@ -49,6 +50,7 @@ type Exporter struct {
 	EventStats            *prometheus.CounterVec
 	ConflictingEventStats *prometheus.CounterVec
 	MetricsCount          *prometheus.GaugeVec
+	clearMetrics          chan chan int
 }
 
 // Listen handles all events sent to the given channel sequentially. It
@@ -60,6 +62,8 @@ func (b *Exporter) Listen(e <-chan event.Events) {
 		select {
 		case <-removeStaleMetricsTicker.C:
 			b.Registry.RemoveStaleMetrics()
+		case cleared := <-b.clearMetrics:
+			cleared <- b.Registry.ClearMetrics()
 		case events, ok := <-e:
 			if !ok {
 				b.Logger.Debug("Channel is closed. Break out of Exporter.Listener.")
@@ -73,6 +77,13 @@ func (b *Exporter) Listen(e <-chan event.Events) {
 	}
 }
 
+// ClearMetrics clears all dynamically registered StatsD time series.
+func (b *Exporter) ClearMetrics() int {
+	cleared := make(chan int)
+	b.clearMetrics <- cleared
+	return <-cleared
+}
+
 // handleEvent processes a single Event according to the configured mapping.
 func (b *Exporter) handleEvent(thisEvent event.Event) {
 	mapping, labels, present := b.Mapper.GetMapping(thisEvent.MetricName(), thisEvent.MetricType())
@@ -207,5 +218,6 @@ func NewExporter(reg prometheus.Registerer, mapper *mapper.MetricMapper, logger
 		EventStats:            eventStats,
 		ConflictingEventStats: conflictingEventStats,
 		MetricsCount:          metricsCount,
+		clearMetrics:          make(chan chan int),
 	}
 }

pkg/exporter/exporter_test.go

@@ -1168,6 +1168,74 @@ mappings:
 	}
 }
 
+func TestClearMetrics(t *testing.T) {
+	clockInstance := clock.ClockInstance
+	clock.ClockInstance = nil
+	defer func() {
+		clock.ClockInstance = clockInstance
+	}()
+
+	reg := prometheus.NewRegistry()
+	testMapper := mapper.MetricMapper{}
+	ex := NewExporter(reg, &testMapper, promslog.NewNopLogger(), eventsActions, eventsUnmapped, errorEventStats, eventStats, conflictingEventStats, metricsCount)
+	events := make(chan event.Events)
+	done := make(chan struct{})
+	go func() {
+		ex.Listen(events)
+		close(done)
+	}()
+	defer func() {
+		close(events)
+		<-done
+	}()
+
+	events <- event.Events{
+		&event.GaugeEvent{
+			GMetricName: "clearable_gauge",
+			GValue:      200,
+		},
+	}
+	events <- event.Events{}
+
+	metrics, err := reg.Gather()
+	if err != nil {
+		t.Fatal("Gather should not fail")
+	}
+	gaugeValue := getFloat64(metrics, "clearable_gauge", prometheus.Labels{})
+	if gaugeValue == nil || *gaugeValue != 200 {
+		t.Fatalf("Gauge `clearable_gauge` should be gathered with value 200, got %v", gaugeValue)
+	}
+
+	if cleared := ex.ClearMetrics(); cleared != 1 {
+		t.Fatalf("Expected to clear 1 metric series, cleared %d", cleared)
+	}
+
+	metrics, err = reg.Gather()
+	if err != nil {
+		t.Fatal("Gather should not fail")
+	}
+	if gaugeValue = getFloat64(metrics, "clearable_gauge", prometheus.Labels{}); gaugeValue != nil {
+		t.Fatalf("Gauge `clearable_gauge` should be cleared, got %v", *gaugeValue)
+	}
+
+	events <- event.Events{
+		&event.GaugeEvent{
+			GMetricName: "clearable_gauge",
+			GValue:      42,
+		},
+	}
+	events <- event.Events{}
+
+	metrics, err = reg.Gather()
+	if err != nil {
+		t.Fatal("Gather should not fail")
+	}
+	gaugeValue = getFloat64(metrics, "clearable_gauge", prometheus.Labels{})
+	if gaugeValue == nil || *gaugeValue != 42 {
+		t.Fatalf("Gauge `clearable_gauge` should be gathered again with value 42, got %v", gaugeValue)
+	}
+}
+
 func TestHashLabelNames(t *testing.T) {
 	r := registry.NewRegistry(prometheus.DefaultRegisterer, nil)
 	// Validate value hash changes and name has doesn't when just the value changes.

pkg/registry/registry.go

@@ -387,14 +387,33 @@ func (r *Registry) RemoveStaleMetrics() {
 				continue
 			}
 			if rm.LastRegisteredAt.Add(rm.TTL).Before(now) {
-				metric.Vectors[rm.VecKey].Holder.Delete(rm.Labels)
-				metric.Vectors[rm.VecKey].RefCount--
-				delete(metric.Metrics, hash)
+				r.removeMetric(metric, hash, rm)
 			}
 		}
 	}
 }
 
+// ClearMetrics deletes all registered time series from the registry.
+func (r *Registry) ClearMetrics() int {
+	removed := 0
+	for _, metric := range r.Metrics {
+		for hash, rm := range metric.Metrics {
+			r.removeMetric(metric, hash, rm)
+			removed++
+		}
+	}
+	return removed
+}
+
+func (r *Registry) removeMetric(metric metrics.Metric, hash metrics.ValueHash, rm *metrics.RegisteredMetric) {
+	vector := metric.Vectors[rm.VecKey]
+	vector.Holder.Delete(rm.Labels)
+	if vector.RefCount > 0 {
+		vector.RefCount--
+	}
+	delete(metric.Metrics, hash)
+}
+
 // Calculates a hash of both the label names and values.
 func (r *Registry) HashLabels(labels prometheus.Labels) (metrics.LabelHash, []string) {
 	r.Hasher.Reset()