gocollector: Added options to Go Collector for changing the (#1031)

* Renamed files.

Signed-off-by: Bartlomiej Plotka <bwplotka@gmail.com>

* gocollector: Added options to Go Collector for diffetent collections.

Fixes #983

Also:

* fixed TestMemStatsEquivalence, it was noop before (:
* Removed gc_cpu_fraction metric completely, since it's not working completely for Go1.17+

Signed-off-by: Bartlomiej Plotka <bwplotka@gmail.com>

prometheus/collectors/collectors.go

@@ -14,3 +14,27 @@
 // Package collectors provides implementations of prometheus.Collector to
 // conveniently collect process and Go-related metrics.
 package collectors
+
+import "github.com/prometheus/client_golang/prometheus"
+
+// NewBuildInfoCollector returns a collector collecting a single metric
+// "go_build_info" with the constant value 1 and three labels "path", "version",
+// and "checksum". Their label values contain the main module path, version, and
+// checksum, respectively. The labels will only have meaningful values if the
+// binary is built with Go module support and from source code retrieved from
+// the source repository (rather than the local file system). This is usually
+// accomplished by building from outside of GOPATH, specifying the full address
+// of the main package, e.g. "GO111MODULE=on go run
+// github.com/prometheus/client_golang/examples/random". If built without Go
+// module support, all label values will be "unknown". If built with Go module
+// support but using the source code from the local file system, the "path" will
+// be set appropriately, but "checksum" will be empty and "version" will be
+// "(devel)".
+//
+// This collector uses only the build information for the main module. See
+// https://github.com/povilasv/prommod for an example of a collector for the
+// module dependencies.
+func NewBuildInfoCollector() prometheus.Collector {
+	//nolint:staticcheck // Ignore SA1019 until v2.
+	return prometheus.NewBuildInfoCollector()
+}

prometheus/collectors/go_collector.go → prometheus/collectors/go_collector_go116.go

@@ -11,6 +11,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//go:build !go1.17
+// +build !go1.17
+
 package collectors
 
 import "github.com/prometheus/client_golang/prometheus"
@@ -42,28 +45,5 @@ import "github.com/prometheus/client_golang/prometheus"
 // NOTE: The problem is solved in Go 1.15, see
 // https://github.com/golang/go/issues/19812 for the related Go issue.
 func NewGoCollector() prometheus.Collector {
-	//nolint:staticcheck // Ignore SA1019 until v2.
 	return prometheus.NewGoCollector()
 }
-
-// NewBuildInfoCollector returns a collector collecting a single metric
-// "go_build_info" with the constant value 1 and three labels "path", "version",
-// and "checksum". Their label values contain the main module path, version, and
-// checksum, respectively. The labels will only have meaningful values if the
-// binary is built with Go module support and from source code retrieved from
-// the source repository (rather than the local file system). This is usually
-// accomplished by building from outside of GOPATH, specifying the full address
-// of the main package, e.g. "GO111MODULE=on go run
-// github.com/prometheus/client_golang/examples/random". If built without Go
-// module support, all label values will be "unknown". If built with Go module
-// support but using the source code from the local file system, the "path" will
-// be set appropriately, but "checksum" will be empty and "version" will be
-// "(devel)".
-//
-// This collector uses only the build information for the main module. See
-// https://github.com/povilasv/prommod for an example of a collector for the
-// module dependencies.
-func NewBuildInfoCollector() prometheus.Collector {
-	//nolint:staticcheck // Ignore SA1019 until v2.
-	return prometheus.NewBuildInfoCollector()
-}

prometheus/collectors/go_collector_latest.go

@@ -0,0 +1,91 @@
+// Copyright 2021 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.
+
+//go:build go1.17
+// +build go1.17
+
+package collectors
+
+import "github.com/prometheus/client_golang/prometheus"
+
+//nolint:staticcheck // Ignore SA1019 until v2.
+type goOptions = prometheus.GoCollectorOptions
+type goOption func(o *goOptions)
+
+type GoCollectionOption uint32
+
+const (
+	// GoRuntimeMemStatsCollection represents the metrics represented by runtime.MemStats structure such as
+	// go_memstats_alloc_bytes
+	// go_memstats_alloc_bytes_total
+	// go_memstats_sys_bytes
+	// go_memstats_lookups_total
+	// go_memstats_mallocs_total
+	// go_memstats_frees_total
+	// go_memstats_heap_alloc_bytes
+	// go_memstats_heap_sys_bytes
+	// go_memstats_heap_idle_bytes
+	// go_memstats_heap_inuse_bytes
+	// go_memstats_heap_released_bytes
+	// go_memstats_heap_objects
+	// go_memstats_stack_inuse_bytes
+	// go_memstats_stack_sys_bytes
+	// go_memstats_mspan_inuse_bytes
+	// go_memstats_mspan_sys_bytes
+	// go_memstats_mcache_inuse_bytes
+	// go_memstats_mcache_sys_bytes
+	// go_memstats_buck_hash_sys_bytes
+	// go_memstats_gc_sys_bytes
+	// go_memstats_other_sys_bytes
+	// go_memstats_next_gc_bytes
+	// so the metrics known from pre client_golang v1.12.0, except skipped go_memstats_gc_cpu_fraction (see
+	// https://github.com/prometheus/client_golang/issues/842#issuecomment-861812034 for explanation.
+	//
+	// NOTE that this mode represents runtime.MemStats statistics, but they are
+	// actually implemented using new runtime/metrics package.
+	// Deprecated: Use GoRuntimeMetricsCollection instead going forward.
+	GoRuntimeMemStatsCollection GoCollectionOption = 1 << iota
+	// GoRuntimeMetricsCollection is the new set of metrics represented by runtime/metrics package and follows
+	// consistent naming. The exposed metric set depends on Go version, but it is controlled against
+	// unexpected cardinality. This set has overlapping information with GoRuntimeMemStatsCollection, just with
+	// new names. GoRuntimeMetricsCollection is what is recommended for using going forward.
+	GoRuntimeMetricsCollection
+)
+
+// WithGoCollections allows enabling different collections for Go collector on top of base metrics
+// like go_goroutines, go_threads, go_gc_duration_seconds, go_memstats_last_gc_time_seconds, go_info.
+//
+// Check GoRuntimeMemStatsCollection and GoRuntimeMetricsCollection for more details. You can use none,
+// one or more collections at once. For example:
+// WithGoCollections(GoRuntimeMemStatsCollection | GoRuntimeMetricsCollection) means both GoRuntimeMemStatsCollection
+// metrics and GoRuntimeMetricsCollection will be exposed.
+//
+// Use WithGoCollections(GoRuntimeMemStatsCollection) to have Go collector working in
+// the compatibility mode with client_golang pre v1.12 (move to runtime/metrics).
+func WithGoCollections(flags uint32) goOption {
+	return func(o *goOptions) {
+		o.EnabledCollections = flags
+	}
+}
+
+// NewGoCollector returns a collector that exports metrics about the current Go
+// process using debug.GCStats using runtime/metrics.
+func NewGoCollector(opts ...goOption) prometheus.Collector {
+	//nolint:staticcheck // Ignore SA1019 until v2.
+	promPkgOpts := make([]func(o *prometheus.GoCollectorOptions), len(opts))
+	for i, opt := range opts {
+		promPkgOpts[i] = opt
+	}
+	//nolint:staticcheck // Ignore SA1019 until v2.
+	return prometheus.NewGoCollector(promPkgOpts...)
+}

prometheus/go_collector.go

@@ -197,14 +197,6 @@ func goRuntimeMemStats() memStatsMetrics {
 			),
 			eval:    func(ms *runtime.MemStats) float64 { return float64(ms.NextGC) },
 			valType: GaugeValue,
-		}, {
-			desc: NewDesc(
-				memstatNamespace("gc_cpu_fraction"),
-				"The fraction of this program's available CPU time used by the GC since the program started.",
-				nil, nil,
-			),
-			eval:    func(ms *runtime.MemStats) float64 { return ms.GCCPUFraction },
-			valType: GaugeValue,
 		},
 	}
 }
@@ -268,7 +260,6 @@ func (c *baseGoCollector) Collect(ch chan<- Metric) {
 	quantiles[0.0] = stats.PauseQuantiles[0].Seconds()
 	ch <- MustNewConstSummary(c.gcDesc, uint64(stats.NumGC), stats.PauseTotal.Seconds(), quantiles)
 	ch <- MustNewConstMetric(c.gcLastTimeDesc, GaugeValue, float64(stats.LastGC.UnixNano())/1e9)
-
 	ch <- MustNewConstMetric(c.goInfoDesc, GaugeValue, 1)
 }
 
@@ -278,6 +269,7 @@ func memstatNamespace(s string) string {
 
 // memStatsMetrics provide description, evaluator, runtime/metrics name, and
 // value type for memstat metrics.
+// TODO(bwplotka): Remove with end Go 1.16 EOL and replace with runtime/metrics.Description
 type memStatsMetrics []struct {
 	desc    *Desc
 	eval    func(*runtime.MemStats) float64

prometheus/go_collector_go116.go

@@ -40,13 +40,28 @@ type goCollector struct {
 //
 // Deprecated: Use collectors.NewGoCollector instead.
 func NewGoCollector() Collector {
+	msMetrics := goRuntimeMemStats()
+	msMetrics = append(msMetrics, struct {
+		desc    *Desc
+		eval    func(*runtime.MemStats) float64
+		valType ValueType
+	}{
+		// This metric is omitted in Go1.17+, see https://github.com/prometheus/client_golang/issues/842#issuecomment-861812034
+		desc: NewDesc(
+			memstatNamespace("gc_cpu_fraction"),
+			"The fraction of this program's available CPU time used by the GC since the program started.",
+			nil, nil,
+		),
+		eval:    func(ms *runtime.MemStats) float64 { return ms.GCCPUFraction },
+		valType: GaugeValue,
+	})
 	return &goCollector{
 		base:      newBaseGoCollector(),
 		msLast:    &runtime.MemStats{},
 		msRead:    runtime.ReadMemStats,
 		msMaxWait: time.Second,
 		msMaxAge:  5 * time.Minute,
-		msMetrics: goRuntimeMemStats(),
+		msMetrics: msMetrics,
 	}
 }