Move OpenMetrics options to a separate struct

Signed-off-by: Arthur Silva Sens <arthur.sens@coralogix.com>

examples/createdtimestamps/main.go

@@ -51,8 +51,10 @@ func main() {
 		"/metrics", promhttp.HandlerFor(
 			registry,
 			promhttp.HandlerOpts{
-				EnableOpenMetrics:               true,
-				EnableOpenMetricsCreatedMetrics: true,
+				OpenMetricsOptions: promhttp.OpenMetricsOptions{
+					Enable:                  true,
+					EnableCreatedTimestamps: true,
+				},
 			}),
 	)
 	// To test: curl -H 'Accept: application/openmetrics-text' localhost:8080/metrics

examples/exemplars/main.go

@@ -61,7 +61,9 @@ func main() {
 		"/metrics", promhttp.HandlerFor(
 			registry,
 			promhttp.HandlerOpts{
-				EnableOpenMetrics: true,
+				OpenMetricsOptions: promhttp.OpenMetricsOptions{
+					Enable: true,
+				},
 			}),
 	)
 	// To test: curl -H 'Accept: application/openmetrics-text' localhost:8080/metrics

examples/gocollector/main.go

@@ -47,8 +47,10 @@ func main() {
 	http.Handle("/metrics", promhttp.HandlerFor(
 		reg,
 		promhttp.HandlerOpts{
-			// Opt into OpenMetrics to support exemplars.
-			EnableOpenMetrics: true,
+			OpenMetricsOptions: promhttp.OpenMetricsOptions{
+				// Opt into OpenMetrics to support exemplars.
+				Enable: true,
+			},
 		},
 	))
 	fmt.Println("Hello world from new Go Collector!")

examples/random/main.go

@@ -134,8 +134,10 @@ func main() {
 	http.Handle("/metrics", promhttp.HandlerFor(
 		reg,
 		promhttp.HandlerOpts{
-			// Opt into OpenMetrics to support exemplars.
-			EnableOpenMetrics: true,
+			OpenMetricsOptions: promhttp.OpenMetricsOptions{
+				// Opt into OpenMetrics to support exemplars.
+				Enable: true,
+			},
 			// Pass custom registry
 			Registry: reg,
 		},

go.mod

@@ -1,14 +1,14 @@
 module github.com/prometheus/client_golang
 
-go 1.20
+go 1.21
 
 require (
 	github.com/beorn7/perks v1.0.1
 	github.com/cespare/xxhash/v2 v2.2.0
 	github.com/davecgh/go-spew v1.1.1
 	github.com/json-iterator/go v1.1.12
 	github.com/prometheus/client_model v0.6.0
-	github.com/prometheus/common v0.48.0
+	github.com/prometheus/common v0.49.0
 	github.com/prometheus/procfs v0.12.0
 	golang.org/x/sys v0.17.0
 	google.golang.org/protobuf v1.33.0
@@ -21,13 +21,11 @@ require (
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/mwitkow/go-conntrack v0.0.0-20190716064945-2f068394615f // indirect
-	golang.org/x/net v0.20.0 // indirect
-	golang.org/x/oauth2 v0.16.0 // indirect
+	golang.org/x/net v0.21.0 // indirect
+	golang.org/x/oauth2 v0.17.0 // indirect
 	golang.org/x/text v0.14.0 // indirect
 	google.golang.org/appengine v1.6.7 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 )
 
 exclude github.com/prometheus/client_golang v1.12.1
-
-replace github.com/prometheus/common => github.com/ArthurSens/common v0.0.0-20240202142709-6a6b93b6b111

go.sum

@@ -1,5 +1,3 @@
-github.com/ArthurSens/common v0.0.0-20240202142709-6a6b93b6b111 h1:W9c8LaygwdqrtdNxx7rtjuMjZVolfG3bV12TVpW7ob8=
-github.com/ArthurSens/common v0.0.0-20240202142709-6a6b93b6b111/go.mod h1:Tp0qkxpb9Jsg54QMe+EAmqXkSV7Evdy1BTn+g2pa/hQ=
 github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
 github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
 github.com/cespare/xxhash/v2 v2.2.0 h1:DC2CZ1Ep5Y4k3ZQ899DldepgrayRUGE6BBZ/cd9Cj44=
@@ -13,7 +11,8 @@ github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaS
 github.com/golang/protobuf v1.5.3 h1:KhyjKVUg7Usr/dYsdSqoFveMYd5ko72D+zANwlG1mmg=
 github.com/golang/protobuf v1.5.3/go.mod h1:XVQd3VNwM+JqD3oG2Ue2ip4fOMUkwXdXDdiuN0vRsmY=
 github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
-github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
 github.com/jpillora/backoff v1.0.0 h1:uvFg412JmmHBHw7iwprIxkPMI+sGQ4kzOWsMeHnm2EA=
 github.com/jpillora/backoff v1.0.0/go.mod h1:J/6gKK9jxlEcS3zixgDgUAsiuZ7yrSoa/FX5e0EB2j4=
@@ -35,19 +34,22 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/prometheus/client_model v0.6.0 h1:k1v3CzpSRUTrKMppY35TLwPvxHqBu0bYgxZzqGIgaos=
 github.com/prometheus/client_model v0.6.0/go.mod h1:NTQHnmxFpouOD0DpvP4XujX3CdOAGQPoaGhyTchlyt8=
+github.com/prometheus/common v0.49.0 h1:ToNTdK4zSnPVJmh698mGFkDor9wBI/iGaJy5dbH1EgI=
+github.com/prometheus/common v0.49.0/go.mod h1:Kxm+EULxRbUkjGU6WFsQqo3ORzB4tyKvlWFOE9mB2sE=
 github.com/prometheus/procfs v0.12.0 h1:jluTpSng7V9hY0O2R9DzzJHYb2xULk9VTR1V1R/k6Bo=
 github.com/prometheus/procfs v0.12.0/go.mod h1:pcuDEFsWDnvcgNzo4EEweacyhjeA9Zk3cnaOZAZEfOo=
 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 h1:TivCn/peBQ7UY8ooIcPgZFpTNSz0Q2U6UrFlUfqbe0Q=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/net v0.0.0-20190603091049-60506f45cf65/go.mod h1:HSz+uSET+XFnRR8LxR5pz3Of3rY3CfYBVs4xY44aLks=
-golang.org/x/net v0.20.0 h1:aCL9BSgETF1k+blQaYUBx9hJ9LOGP3gAVemcZlf1Kpo=
-golang.org/x/net v0.20.0/go.mod h1:z8BVo6PvndSri0LbOE3hAn0apkU+1YvI6E70E9jsnvY=
-golang.org/x/oauth2 v0.16.0 h1:aDkGMBSYxElaoP81NpoUoz2oo2R2wHdZpGToUxfyQrQ=
-golang.org/x/oauth2 v0.16.0/go.mod h1:hqZ+0LWXsiVoZpeld6jVt06P3adbS2Uu911W1SsJv2o=
+golang.org/x/net v0.21.0 h1:AQyQV4dYCvJ7vGmJyKki9+PBdyvhkSd8EIx/qb0AYv4=
+golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
+golang.org/x/oauth2 v0.17.0 h1:6m3ZPmLEFdVxKKWnKq4VqZ60gutO35zm+zrAHVmHyDQ=
+golang.org/x/oauth2 v0.17.0/go.mod h1:OzPDGQiuQMguemayvdylqddI7qcD9lnSDb+1FiwQ5HA=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.17.0 h1:25cE3gD+tdBA7lp7QfhuV+rJiE9YXTcS3VG1SqssI/Y=
 golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
@@ -65,5 +67,6 @@ google.golang.org/protobuf v1.33.0 h1:uNO2rsAINq/JlFpSdYEKIZ0uKD/R9cpdv0T+yoGwGm
 google.golang.org/protobuf v1.33.0/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
 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=

prometheus/promhttp/http.go

@@ -160,7 +160,7 @@ func HandlerForTransactional(reg prometheus.TransactionalGatherer, opts HandlerO
 		}
 
 		var contentType expfmt.Format
-		if opts.EnableOpenMetrics {
+		if opts.EnableOpenMetrics || opts.OpenMetricsOptions.Enable {
 			contentType = expfmt.NegotiateIncludingOpenMetrics(req.Header)
 		} else {
 			contentType = expfmt.Negotiate(req.Header)
@@ -181,7 +181,7 @@ func HandlerForTransactional(reg prometheus.TransactionalGatherer, opts HandlerO
 		}
 
 		var enc expfmt.Encoder
-		if opts.EnableOpenMetricsCreatedMetrics {
+		if opts.OpenMetricsOptions.EnableCreatedTimestamps {
 			enc = expfmt.NewEncoder(w, contentType, expfmt.WithCreatedLines())
 		} else {
 			enc = expfmt.NewEncoder(w, contentType)
@@ -366,31 +366,11 @@ type HandlerOpts struct {
 	// away). Until the implementation is improved, it is recommended to
 	// implement a separate timeout in potentially slow Collectors.
 	Timeout time.Duration
-	// If true, the experimental OpenMetrics encoding is added to the
-	// possible options during content negotiation. Note that Prometheus
-	// 2.5.0+ will negotiate OpenMetrics as first priority. OpenMetrics is
-	// the only way to transmit exemplars. However, the move to OpenMetrics
-	// is not completely transparent. Most notably, the values of "quantile"
-	// labels of Summaries and "le" labels of Histograms are formatted with
-	// a trailing ".0" if they would otherwise look like integer numbers
-	// (which changes the identity of the resulting series on the Prometheus
-	// server).
+	// Deprecated: Use OpenMetricsOptions.Enable instead.
 	EnableOpenMetrics bool
-	// If 'EnableOpenMetrics' is true, 'EnableOpenMetricsCreatedMetrics' allows
-	// to add extra '_created' lines for counters, histograms and summaries,
-	// as defined in the OpenMetrics specification (see
-	// https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#counter-1).
-	// Created timestamps are used to improve the accuracy of reset detection,
-	// but be aware that it also increases the size of the payload.
-	//
-	// Prometheus introduced the feature flag 'created-timestamp-zero-ingestion'
-	// in version 2.50.0, but with support limited to the Prometheus protobuf
-	// format. Starting in Prometheus XXXX, the feature flag will be extended
-	// to the OpenMetrics text format. If using Prometheus XXXX or later, it
-	// is recommended to enable the feature flag in Prometheus, otherwise enabling
-	// _created lines will result in increased cardinality and no improvements
-	// in reset detection.
-	EnableOpenMetricsCreatedMetrics bool
+	// OpenMetricsOptions holds settings for the experimental OpenMetrics encoding.
+	// It can be used to enable OpenMetrics encoding and for setting extra options.
+	OpenMetricsOptions OpenMetricsOptions
 	// ProcessStartTime allows setting process start timevalue that will be exposed
 	// with "Process-Start-Time-Unix" response header along with the metrics
 	// payload. This allow callers to have efficient transformations to cumulative
@@ -401,6 +381,43 @@ type HandlerOpts struct {
 	ProcessStartTime time.Time
 }
 
+type OpenMetricsOptions struct {
+	// Enable specifies if the experimental OpenMetrics encoding is added to the
+	// possible options during content negotiation.
+	//
+	// Note that Prometheus 2.5.0+ might negotiate OpenMetrics Text format
+	// as first priority unless user uses custom scrape protocol prioritization or
+	// histograms feature is enabled (then Prometheus proto format is prioritized,
+	// which client_golang supports).
+	//
+	// Keep in mind that the move to OpenMetrics is not completely transparent. Most notably,
+	// the values of "quantile" labels of Summaries and "le" labels of Histograms are
+	// formatted with a trailing ".0" if they would otherwise look like integer numbers
+	// (which changes the identity of the resulting series on the Prometheus
+	// server).
+	//
+	// See other options in OpenMetricsOptions to learn how to enable some special
+	// features e.g. potentially dangerous created timestamp series.
+	Enable bool
+	// EnableCreatedTimestamps specifies if this handler should add, extra, synthetic
+	// Created Timestamps for counters, histograms and summaries, which for the current
+	// version of OpenMetrics are defined as extra series with the same name and "_created"
+	// suffix. See also the OpenMetrics specification for more details
+	// https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#counter-1
+	//
+	// Created timestamps are used to improve the accuracy of reset detection,
+	// but the way it's designed in OpenMetrics 1.0 it also dramatically increases cardinality
+	// if the scraper does not handle those metrics correctly (converting to created timestamp
+	// instead of leaving those series as-is). New OpenMetrics versions might improve
+	// this situation.
+	//
+	// Prometheus introduced the feature flag 'created-timestamp-zero-ingestion'
+	// in version 2.50.0, but only for the Prometheus protobuf format. Starting in
+	// future Prometheus version, the feature flag will be extended to the OpenMetrics
+	// text format, thus safe to be enabled to improve accuracy of counters in Prometheus.
+	EnableCreatedTimestamps bool
+}
+
 // gzipAccepted returns whether the client will accept gzip-encoded content.
 func gzipAccepted(header http.Header) bool {
 	a := header.Get(acceptEncodingHeader)