Add metric filtering support to promhttp.HandlerForTransactional

This commit adds support for filtering metrics by name using the
metric[] query parameter in HandlerForTransactional. Multiple metric
names can be specified by providing the parameter multiple times.

Example usage:
  /metrics?metric[]=http_requests_total&metric[]=process_cpu_seconds_total

Implementation details:
- Query parameters are parsed and converted to a map for O(1) lookup
- Filtering happens inline during the encoding loop to avoid allocating
  a new slice
- When no metric[] parameters are provided, all metrics are returned
  (backward compatible)
- When metric[] parameters don't match any metrics, an empty response
  is returned with HTTP 200

Tests include:
- Single and multiple metric filtering
- Backward compatibility (no filter returns all)
- Non-matching filters
- Empty and duplicate values
- Verification that transactional gather lifecycle is maintained

Signed-off-by: Oleg Zaytsev <[email protected]>

Author: colega

prometheus/promhttp/http.go

@@ -112,6 +112,10 @@ func HandlerFor(reg prometheus.Gatherer, opts HandlerOpts) http.Handler {
 // HandlerForTransactional is like HandlerFor, but it uses transactional gather, which
 // can safely change in-place returned *dto.MetricFamily before call to `Gather` and after
 // call to `done` of that `Gather`.
+//
+// The handler supports filtering metrics by name using the `metric[]` query parameter.
+// Multiple metric names can be specified by providing the parameter multiple times.
+// When no metric[] parameters are provided, all metrics are returned.
 func HandlerForTransactional(reg prometheus.TransactionalGatherer, opts HandlerOpts) http.Handler {
 	var (
 		inFlightSem chan struct{}
@@ -245,7 +249,21 @@ func HandlerForTransactional(reg prometheus.TransactionalGatherer, opts HandlerO
 			return false
 		}
 
+		// Build metric name filter set from query params (if any)
+		var metricFilter map[string]struct{}
+		if metricNames := req.URL.Query()["metric[]"]; len(metricNames) > 0 {
+			metricFilter = make(map[string]struct{}, len(metricNames))
+			for _, name := range metricNames {
+				metricFilter[name] = struct{}{}
+			}
+		}
+
 		for _, mf := range mfs {
+			if metricFilter != nil {
+				if _, ok := metricFilter[mf.GetName()]; !ok {
+					continue
+				}
+			}
 			if handleError(enc.Encode(mf)) {
 				return
 			}

prometheus/promhttp/http_test.go

@@ -640,3 +640,125 @@ func BenchmarkCompression(b *testing.B) {
 		}
 	}
 }
+
+func TestHandlerWithMetricFilter(t *testing.T) {
+	reg := prometheus.NewRegistry()
+
+	counter := prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "test_counter",
+		Help: "A test counter.",
+	})
+	gauge := prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "test_gauge",
+		Help: "A test gauge.",
+	})
+	histogram := prometheus.NewHistogram(prometheus.HistogramOpts{
+		Name: "test_histogram",
+		Help: "A test histogram.",
+	})
+
+	reg.MustRegister(counter, gauge, histogram)
+	counter.Inc()
+	gauge.Set(42)
+	histogram.Observe(3.14)
+
+	mReg := &mockTransactionGatherer{g: reg}
+	handler := HandlerForTransactional(mReg, HandlerOpts{})
+
+	testCases := []struct {
+		name             string
+		url              string
+		shouldContain    []string
+		shouldNotContain []string
+	}{
+		{
+			name:             "single metric filter",
+			url:              "/?metric[]=test_counter",
+			shouldContain:    []string{"test_counter"},
+			shouldNotContain: []string{"test_gauge", "test_histogram"},
+		},
+		{
+			name:             "multiple metric filters",
+			url:              "/?metric[]=test_counter&metric[]=test_gauge",
+			shouldContain:    []string{"test_counter", "test_gauge"},
+			shouldNotContain: []string{"test_histogram"},
+		},
+		{
+			name:             "no filter returns all metrics",
+			url:              "/",
+			shouldContain:    []string{"test_counter", "test_gauge", "test_histogram"},
+			shouldNotContain: []string{},
+		},
+		{
+			name:             "non-matching filter returns empty",
+			url:              "/?metric[]=nonexistent_metric",
+			shouldContain:    []string{},
+			shouldNotContain: []string{"test_counter", "test_gauge", "test_histogram"},
+		},
+		{
+			name:             "empty metric[] value",
+			url:              "/?metric[]=",
+			shouldContain:    []string{},
+			shouldNotContain: []string{"test_counter", "test_gauge", "test_histogram"},
+		},
+		{
+			name:             "duplicate metric[] values",
+			url:              "/?metric[]=test_counter&metric[]=test_counter",
+			shouldContain:    []string{"test_counter"},
+			shouldNotContain: []string{"test_gauge", "test_histogram"},
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			writer := httptest.NewRecorder()
+			request, _ := http.NewRequest(http.MethodGet, tc.url, nil)
+			request.Header.Add(acceptHeader, acceptTextPlain)
+
+			handler.ServeHTTP(writer, request)
+
+			if got, want := writer.Code, http.StatusOK; got != want {
+				t.Errorf("got HTTP status code %d, want %d", got, want)
+			}
+
+			body := writer.Body.String()
+			for _, expected := range tc.shouldContain {
+				if !strings.Contains(body, expected) {
+					t.Errorf("expected body to contain %q, got: %s", expected, body)
+				}
+			}
+			for _, notExpected := range tc.shouldNotContain {
+				if strings.Contains(body, notExpected) {
+					t.Errorf("expected body to NOT contain %q, got: %s", notExpected, body)
+				}
+			}
+		})
+	}
+}
+
+func TestHandlerWithMetricFilterTransactionalCalls(t *testing.T) {
+	reg := prometheus.NewRegistry()
+
+	counter := prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "test_counter",
+		Help: "A test counter.",
+	})
+	reg.MustRegister(counter)
+
+	mReg := &mockTransactionGatherer{g: reg}
+	handler := HandlerForTransactional(mReg, HandlerOpts{})
+
+	writer := httptest.NewRecorder()
+	request, _ := http.NewRequest(http.MethodGet, "/?metric[]=test_counter", nil)
+	request.Header.Add(acceptHeader, acceptTextPlain)
+
+	handler.ServeHTTP(writer, request)
+
+	// Verify that Gather and done are called even with filtering
+	if got := mReg.gatherInvoked; got != 1 {
+		t.Errorf("unexpected number of gather invokes, want 1, got %d", got)
+	}
+	if got := mReg.doneInvoked; got != 1 {
+		t.Errorf("unexpected number of done invokes, want 1, got %d", got)
+	}
+}