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()
+	}
+}

internal/scrapecache/scrapecache_test.go

@@ -0,0 +1,75 @@
+// 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_test
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+
+	"github.com/prometheus-community/windows_exporter/internal/scrapecache"
+	"github.com/stretchr/testify/require"
+)
+
+type cache struct {
+	name   string
+	events *[]string
+}
+
+func (c cache) BeginScrape() {
+	*c.events = append(*c.events, c.name+" begin")
+}
+
+func (c cache) EndScrape(err error) {
+	*c.events = append(*c.events, fmt.Sprintf("%s end %v", c.name, err))
+}
+
+func (c cache) Reset() {
+	*c.events = append(*c.events, c.name+" reset")
+}
+
+type owner struct {
+	events []string
+	calls  int
+}
+
+func (o *owner) ScrapeCaches() []scrapecache.Cache {
+	o.calls++
+
+	return []scrapecache.Cache{cache{name: "a", events: &o.events}, cache{name: "b", events: &o.events}}
+}
+
+func TestOwner(t *testing.T) {
+	t.Parallel()
+
+	o := &owner{}
+
+	scrapecache.Reset(o)
+
+	cacheScrape := scrapecache.Begin(o)
+	require.Equal(t, []string{"a reset", "b reset", "a begin", "b begin"}, o.events)
+
+	cacheScrape.End(errors.New("failed"))
+	require.Equal(t, []string{"a end failed", "b end failed"}, o.events[4:])
+	require.Equal(t, 2, o.calls, "Begin asks for the caches once per scrape")
+}
+
+func TestNotAnOwner(t *testing.T) {
+	t.Parallel()
+
+	scrapecache.Reset(struct{}{})
+	scrapecache.Begin(struct{}{}).End(errors.New("ignored"))
+}