collector: let the collection own the label and metric caches (#2740)

Signed-off-by: Jan-Otto Kröpke <mail@jkroepke.de>

internal/scrapecache/scrapecache.go

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 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 scrapecache lets the collection own the caches that collectors keep
+// between scrapes, such as internal/labelcache and internal/metriccache.
+//
+// A collector lists its caches with ScrapeCaches. The collection resets them
+// before Build and after Close, and begins a scrape of each cache before
+// Collect and ends it after Collect returned. Collect calls of one collector
+// never overlap, so a scrape always belongs to exactly one Collect call, even
+// one that outlives its scrape budget.
+//
+// Outside of the collection, for example when a test or a library consumer
+// calls Collect directly, the caches have no scrape and every metric is built
+// without them.
+package scrapecache
+
+// Cache is a cache that a collector keeps between scrapes.
+type Cache interface {
+	// BeginScrape begins the scrape of a Collect call.
+	BeginScrape()
+	// EndScrape ends the scrape after Collect returned err.
+	EndScrape(err error)
+	// Reset drops the cached entries. Their descriptors may be stale after
+	// a new Build.
+	Reset()
+}
+
+// Owner is implemented by collectors that keep caches between scrapes.
+type Owner interface {
+	// ScrapeCaches returns the caches of the collector. The collection may
+	// call it before Build.
+	ScrapeCaches() []Cache
+}
+
+// Scrape is a scrape of the caches of a collector.
+type Scrape struct {
+	caches []Cache
+}
+
+// Begin begins a scrape of the caches of collector, if it is an [Owner].
+// Call End with the error of Collect once Collect returned.
+func Begin(collector any) Scrape {
+	owner, ok := collector.(Owner)
+	if !ok {
+		return Scrape{}
+	}
+
+	caches := owner.ScrapeCaches()
+	for _, cache := range caches {
+		cache.BeginScrape()
+	}
+
+	return Scrape{caches: caches}
+}
+
+// End ends the scrape after Collect returned err.
+func (s Scrape) End(err error) {
+	for _, cache := range s.caches {
+		cache.EndScrape(err)
+	}
+}
+
+// Reset resets the caches of collector, if it is an [Owner].
+func Reset(collector any) {
+	owner, ok := collector.(Owner)
+	if !ok {
+		return
+	}
+
+	for _, cache := range owner.ScrapeCaches() {
+		cache.Reset()
+	}
+}