Add a collector for pg_buffercache_summary. (#1165)

* Add a collector for pg_buffercache_summary()
* Requires PostgreSQL >= 16.
---------

Signed-off-by: Peter Nuttall <peter.nuttall@snowflake.com>
Co-authored-by: Ben Kochie <superq@gmail.com>

collector/collector.go

@@ -15,6 +15,7 @@ package collector
 
 import (
 	"context"
+	"database/sql"
 	"errors"
 	"fmt"
 	"log/slog"
@@ -228,3 +229,11 @@ var ErrNoData = errors.New("collector returned no data")
 func IsNoDataError(err error) bool {
 	return err == ErrNoData
 }
+
+func Int32(m sql.NullInt32) float64 {
+	mM := 0.0
+	if m.Valid {
+		mM = float64(m.Int32)
+	}
+	return mM
+}

collector/pg_buffercache_summary.go

@@ -0,0 +1,135 @@
+// 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 collector
+
+import (
+	"context"
+	"database/sql"
+	"log/slog"
+
+	"github.com/blang/semver/v4"
+	"github.com/prometheus/client_golang/prometheus"
+)
+
+const buffercacheSummarySubsystem = "buffercache_summary"
+
+func init() {
+	registerCollector(buffercacheSummarySubsystem, defaultDisabled, NewBuffercacheSummaryCollector)
+}
+
+// BuffercacheSummaryCollector collects stats from pg_buffercache: https://www.postgresql.org/docs/current/pgbuffercache.html.
+//
+// It depends on the extension being loaded with
+//
+//	create extension pg_buffercache;
+//
+// It does not take locks, see the PG docs above.
+type BuffercacheSummaryCollector struct {
+	log *slog.Logger
+}
+
+func NewBuffercacheSummaryCollector(config collectorConfig) (Collector, error) {
+	return &BuffercacheSummaryCollector{
+		log: config.logger,
+	}, nil
+}
+
+var (
+	buffersUsedDesc = prometheus.NewDesc(
+		prometheus.BuildFQName(namespace, buffercacheSummarySubsystem, "buffers_used"),
+		"Number of used shared buffers",
+		[]string{},
+		prometheus.Labels{},
+	)
+	buffersUnusedDesc = prometheus.NewDesc(
+		prometheus.BuildFQName(namespace, buffercacheSummarySubsystem, "buffers_unused"),
+		"Number of unused shared buffers",
+		[]string{},
+		prometheus.Labels{},
+	)
+	buffersDirtyDesc = prometheus.NewDesc(
+		prometheus.BuildFQName(namespace, buffercacheSummarySubsystem, "buffers_dirty"),
+		"Number of dirty shared buffers",
+		[]string{},
+		prometheus.Labels{},
+	)
+	buffersPinnedDesc = prometheus.NewDesc(
+		prometheus.BuildFQName(namespace, buffercacheSummarySubsystem, "buffers_pinned"),
+		"Number of pinned shared buffers",
+		[]string{},
+		prometheus.Labels{},
+	)
+	usageCountAvgDesc = prometheus.NewDesc(
+		prometheus.BuildFQName(namespace, buffercacheSummarySubsystem, "usagecount_avg"),
+		"Average usage count of used shared buffers",
+		[]string{},
+		prometheus.Labels{},
+	)
+
+	buffercacheQuery = `
+		SELECT
+		  buffers_used,
+			buffers_unused,
+			buffers_dirty,
+			buffers_pinned,
+			usagecount_avg
+		FROM
+		  pg_buffercache_summary()
+		`
+)
+
+// Update implements Collector
+// It is called by the Prometheus registry when collecting metrics.
+func (c BuffercacheSummaryCollector) Update(ctx context.Context, instance *instance, ch chan<- prometheus.Metric) error {
+	// pg_buffercache_summary is only in v16, and we don't need support for earlier currently.
+	if !instance.version.GE(semver.MustParse("16.0.0")) {
+		return nil
+	}
+	db := instance.getDB()
+	rows, err := db.QueryContext(ctx, buffercacheQuery)
+	if err != nil {
+		return err
+	}
+	defer rows.Close()
+
+	var used, unused, dirty, pinned sql.NullInt32
+	var usagecountAvg sql.NullFloat64
+
+	for rows.Next() {
+		if err := rows.Scan(
+			&used,
+			&unused,
+			&dirty,
+			&pinned,
+			&usagecountAvg,
+		); err != nil {
+			return err
+		}
+
+		usagecountAvgMetric := 0.0
+		if usagecountAvg.Valid {
+			usagecountAvgMetric = usagecountAvg.Float64
+		}
+		ch <- prometheus.MustNewConstMetric(
+			usageCountAvgDesc,
+			prometheus.GaugeValue,
+			usagecountAvgMetric)
+		ch <- prometheus.MustNewConstMetric(buffersUsedDesc, prometheus.GaugeValue, Int32(used))
+		ch <- prometheus.MustNewConstMetric(buffersUnusedDesc, prometheus.GaugeValue, Int32(unused))
+		ch <- prometheus.MustNewConstMetric(buffersDirtyDesc, prometheus.GaugeValue, Int32(dirty))
+		ch <- prometheus.MustNewConstMetric(buffersPinnedDesc, prometheus.GaugeValue, Int32(pinned))
+	}
+
+	return rows.Err()
+}

collector/pg_buffercache_summary_test.go

@@ -0,0 +1,73 @@
+// 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 collector
+
+import (
+	"context"
+	"testing"
+
+	"github.com/DATA-DOG/go-sqlmock"
+	"github.com/blang/semver/v4"
+	"github.com/prometheus/client_golang/prometheus"
+	dto "github.com/prometheus/client_model/go"
+	"github.com/smartystreets/goconvey/convey"
+)
+
+func TestBuffercacheSummaryCollector(t *testing.T) {
+	db, mock, err := sqlmock.New()
+	if err != nil {
+		t.Fatalf("Error opening a stub db connection: %s", err)
+	}
+	defer db.Close()
+
+	inst := &instance{db: db, version: semver.MustParse("16.0.0")}
+
+	columns := []string{
+		"buffers_used",
+		"buffers_unused",
+		"buffers_dirty",
+		"buffers_pinned",
+		"usagecount_avg"}
+
+	rows := sqlmock.NewRows(columns).AddRow(123, 456, 789, 234, 56.6778)
+
+	mock.ExpectQuery(sanitizeQuery(buffercacheQuery)).WillReturnRows(rows)
+
+	ch := make(chan prometheus.Metric)
+	go func() {
+		defer close(ch)
+		c := BuffercacheSummaryCollector{}
+
+		if err := c.Update(context.Background(), inst, ch); err != nil {
+			t.Errorf("Error calling PGStatStatementsCollector.Update: %s", err)
+		}
+	}()
+
+	expected := []MetricResult{
+		{labels: labelMap{}, metricType: dto.MetricType_GAUGE, value: 56.6778},
+		{labels: labelMap{}, metricType: dto.MetricType_GAUGE, value: 123},
+		{labels: labelMap{}, metricType: dto.MetricType_GAUGE, value: 456},
+		{labels: labelMap{}, metricType: dto.MetricType_GAUGE, value: 789},
+		{labels: labelMap{}, metricType: dto.MetricType_GAUGE, value: 234},
+	}
+
+	convey.Convey("Metrics comparison", t, func() {
+		for _, expect := range expected {
+			m := readMetric(<-ch)
+			convey.So(expect, convey.ShouldResemble, m)
+		}
+	})
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Errorf("there were unfulfilled exceptions: %s", err)
+	}
+}