Add structured logging support to promhttp

In order to better support the standard library `log/slog` add a
new interface to the `promhttp` `HandlerOpts`.

Note, this requires updating the Go minimum version to Go 1.21.

Signed-off-by: SuperQ <[email protected]>

Author: SuperQ

Diff for: .github/workflows/go.yml

@@ -54,7 +54,7 @@ jobs:
 
       - name: Run style and unused
         uses: dagger/dagger-for-github@v6
-        if: ${{ matrix.go_version == '1.20' }}
+        if: ${{ matrix.go_version == '1.21' }}
         with:
           version: "latest"
           verb: call

Diff for: .github/workflows/golangci-lint.yml

@@ -28,7 +28,7 @@ jobs:
       - name: Install Go
         uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32 # v5.0.2
         with:
-          go-version: 1.22.x
+          go-version: 1.23.x
       - name: Install snmp_exporter/generator dependencies
         run: sudo apt-get update && sudo apt-get -y install libsnmp-dev
         if: github.repository == 'prometheus/snmp_exporter'

Diff for: README.md

@@ -10,8 +10,8 @@ This is the [Go](http://golang.org) client library for
 instrumenting application code, and one for creating clients that talk to the
 Prometheus HTTP API.
 
-**This library requires Go1.20 or later.**
-> The library mandates the use of Go1.20 or subsequent versions. While it has demonstrated functionality with versions as old as Go 1.17, our commitment remains to offer support and rectifications for only the most recent three major releases.
+**This library requires Go1.21 or later.**
+> The library mandates the use of Go1.21 or subsequent versions. While it has demonstrated functionality with versions as old as Go 1.17, our commitment remains to offer support and rectifications for only the most recent three major releases.
 
 ## Important note about releases and stability
 

Diff for: go.mod

@@ -1,6 +1,6 @@
 module github.com/prometheus/client_golang
 
-go 1.20
+go 1.21
 
 require (
 	github.com/beorn7/perks v1.0.1

Diff for: go.sum

@@ -41,9 +41,11 @@ github.com/prometheus/procfs v0.15.1 h1:YagwOFzUgYfKKHX6Dr+sHT7km/hxC76UB0leargg
 github.com/prometheus/procfs v0.15.1/go.mod h1:fB45yRUv8NstnjriLhBQLuOUt+WW4BsoGhij/e3PBqk=
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
 github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
+github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 golang.org/x/net v0.26.0 h1:soB7SVo0PWrY4vPW/+ay0jKDNScG2X9wFeYlXIvJsOQ=
 golang.org/x/net v0.26.0/go.mod h1:5YKkiSynbBIh3p6iOc/vibscux0x38BZDkn8sCUPxHE=
 golang.org/x/oauth2 v0.21.0 h1:tsimM75w1tF/uws5rbeHzIWxEqElMehnc+iW793zsZs=
@@ -56,6 +58,8 @@ google.golang.org/protobuf v1.34.2 h1:6xV6lTsCfpGD21XK49h7MhtcApnLqkfYgPcdHftf6h
 google.golang.org/protobuf v1.34.2/go.mod h1:qYOHts0dSfpeUzUFpOMr/WGzszTmLH+DiWniOlNbLDw=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

Diff for: prometheus/promhttp/http.go

@@ -168,6 +168,9 @@ func HandlerForTransactional(reg prometheus.TransactionalGatherer, opts HandlerO
 			if opts.ErrorLog != nil {
 				opts.ErrorLog.Println("error gathering metrics:", err)
 			}
+			if opts.StructuredErrorLog != nil {
+				opts.StructuredErrorLog.Error("error gathering metrics", "error", err)
+			}
 			errCnt.WithLabelValues("gathering").Inc()
 			switch opts.ErrorHandling {
 			case PanicOnError:
@@ -197,6 +200,9 @@ func HandlerForTransactional(reg prometheus.TransactionalGatherer, opts HandlerO
 			if opts.ErrorLog != nil {
 				opts.ErrorLog.Println("error getting writer", err)
 			}
+			if opts.StructuredErrorLog != nil {
+				opts.StructuredErrorLog.Error("error getting writer", "error", err)
+			}
 			w = io.Writer(rsp)
 			encodingHeader = string(Identity)
 		}
@@ -218,6 +224,9 @@ func HandlerForTransactional(reg prometheus.TransactionalGatherer, opts HandlerO
 			if opts.ErrorLog != nil {
 				opts.ErrorLog.Println("error encoding and sending metric family:", err)
 			}
+			if opts.StructuredErrorLog != nil {
+				opts.StructuredErrorLog.Error("error encoding and sending metric family", "error", err)
+			}
 			errCnt.WithLabelValues("encoding").Inc()
 			switch opts.ErrorHandling {
 			case PanicOnError:
@@ -344,6 +353,12 @@ type Logger interface {
 	Println(v ...interface{})
 }
 
+// StructuredLogger is a minimal interface HandlerOpts needs for structured
+// logging. This is implementd by the standard library log/slog.Logger type.
+type StructuredLogger interface {
+	Error(msg string, args ...any)
+}
+
 // HandlerOpts specifies options how to serve metrics via an http.Handler. The
 // zero value of HandlerOpts is a reasonable default.
 type HandlerOpts struct {
@@ -354,6 +369,9 @@ type HandlerOpts struct {
 	// latter, create a Logger implementation that detects a
 	// prometheus.MultiError and formats the contained errors into one line.
 	ErrorLog Logger
+	// StructuredErrorLog StructuredLogger specifies an optional structured log
+	// handler.
+	StructuredErrorLog StructuredLogger
 	// ErrorHandling defines how errors are handled. Note that errors are
 	// logged regardless of the configured ErrorHandling provided ErrorLog
 	// is not nil.

Diff for: prometheus/promhttp/http_test.go

@@ -20,8 +20,10 @@ import (
 	"fmt"
 	"io"
 	"log"
+	"log/slog"
 	"net/http"
 	"net/http/httptest"
+	"os"
 	"strings"
 	"testing"
 	"time"
@@ -130,25 +132,30 @@ func TestHandlerErrorHandling(t *testing.T) {
 	logBuf := &bytes.Buffer{}
 	logger := log.New(logBuf, "", 0)
 
+	slogger := slog.New(slog.NewTextHandler(os.Stderr, nil))
+
 	writer := httptest.NewRecorder()
 	request, _ := http.NewRequest("GET", "/", nil)
 	request.Header.Add("Accept", "test/plain")
 
 	mReg := &mockTransactionGatherer{g: reg}
 	errorHandler := HandlerForTransactional(mReg, HandlerOpts{
-		ErrorLog:      logger,
-		ErrorHandling: HTTPErrorOnError,
-		Registry:      reg,
+		ErrorLog:           logger,
+		StructuredErrorLog: slogger,
+		ErrorHandling:      HTTPErrorOnError,
+		Registry:           reg,
 	})
 	continueHandler := HandlerForTransactional(mReg, HandlerOpts{
-		ErrorLog:      logger,
-		ErrorHandling: ContinueOnError,
-		Registry:      reg,
+		ErrorLog:           logger,
+		StructuredErrorLog: slogger,
+		ErrorHandling:      ContinueOnError,
+		Registry:           reg,
 	})
 	panicHandler := HandlerForTransactional(mReg, HandlerOpts{
-		ErrorLog:      logger,
-		ErrorHandling: PanicOnError,
-		Registry:      reg,
+		ErrorLog:           logger,
+		StructuredErrorLog: slogger,
+		ErrorHandling:      PanicOnError,
+		Registry:           reg,
 	})
 	// Expect gatherer not touched.
 	if got := mReg.gatherInvoked; got != 0 {

Diff for: supported_go_versions.txt

@@ -1,3 +1,3 @@
+1.23
 1.22
 1.21
-1.20