goCollector: Added rule support for granular metric configuration.

Fixes: #1089

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

Author: bwplotka

prometheus/collectors/go_collector_latest.go

@@ -16,77 +16,102 @@
 
 package collectors
 
-import "github.com/prometheus/client_golang/prometheus"
+import (
+	"regexp"
 
-//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
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/internal"
 )
 
-// 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.
+// WithGoCollectorMemStatsMetricsDisabled metrics that where representing 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,
+//
+// NOTE(bwplotka): The above represents runtime.MemStats statistics, but they are
+// actually implemented using new runtime/metrics package. (except skipped go_memstats_gc_cpu_fraction
+// -- see  https://github.com/prometheus/client_golang/issues/842#issuecomment-861812034 for explanation).
 //
-// 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.
+// Some users might want to disable this on collector level (although you can use scrape relabelling on Prometheus),
+// because similar metrics can be now obtained using WithGoCollectorRuntimeMetrics. Note that the semantics of new
+// metrics might be different, plus the names can be change over time with different Go version.
 //
-// The current default is GoRuntimeMemStatsCollection, so the compatibility mode with
-// client_golang pre v1.12 (move to runtime/metrics).
-//nolint:staticcheck // Ignore SA1019 until v2.
-func WithGoCollections(flags GoCollectionOption) func(options *prometheus.GoCollectorOptions) {
-	return func(o *goOptions) {
-		o.EnabledCollections = uint32(flags)
+// NOTE(bwplotka): Changing metric names can be tedious at times as the alerts, recording rules and dashboards have to be adjusted.
+// The old metrics are also very useful, with many guides and books written about how to interpret them.
+//
+// As a result our recommendation would be to stick with MemStats like metrics and enable other runtime/metrics if you are interested
+// in advanced insights Go provides. See ExampleGoCollector_WithAdvancedGoMetrics.
+func WithGoCollectorMemStatsMetricsDisabled() func(options *internal.GoCollectorOptions) {
+	return func(o *internal.GoCollectorOptions) {
+		o.DisableMemStatsLikeMetrics = true
 	}
 }
 
-// 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
+// GoRuntimeMetricsRule allow enabling and configuring particular group of runtime/metrics.
+type GoRuntimeMetricsRule struct {
+	// Matcher represents RE2 expression will match the runtime/metrics from https://golang.bg/src/runtime/metrics/description.go
+	// Use `regexp.MustCompile` or `regexp.Compile` to create this field.
+	Matcher *regexp.Regexp
+}
+
+// WithGoCollectorRuntimeMetrics allows enabling and configuring particular group of runtime/metrics.
+// See the list of metrics https://golang.bg/src/runtime/metrics/description.go (pick the Go version you use there!).
+// You can use this option in repeated manner, which will add new rules. The order of rules is important, the last rule
+// that matches particular metrics is applied.
+func WithGoCollectorRuntimeMetrics(rules ...GoRuntimeMetricsRule) func(options *internal.GoCollectorOptions) {
+	rs := make([]internal.GoCollectorRule, len(rules))
+	for i, r := range rules {
+		rs[i] = internal.GoCollectorRule{
+			Matcher: r.Matcher,
+		}
 	}
+
+	return func(o *internal.GoCollectorOptions) {
+		o.DisableMemStatsLikeMetrics = true
+	}
+}
+
+// WithoutGoCollectorRuntimeMetrics allows disabling group of runtime/metrics that you might have added in WithGoCollectorRuntimeMetrics.
+// It behaves similarly to WithGoCollectorRuntimeMetrics just with deny-list semantics.
+func WithoutGoCollectorRuntimeMetrics(matchers ...*regexp.Regexp) func(options *internal.GoCollectorOptions) {
+	rs := make([]internal.GoCollectorRule, len(matchers))
+	for i, m := range matchers {
+		rs[i] = internal.GoCollectorRule{
+			Matcher: m,
+			Deny:    true,
+		}
+	}
+
+	return func(o *internal.GoCollectorOptions) {
+		o.RuntimeMetricRules = append(o.RuntimeMetricRules, rs...)
+	}
+}
+
+// NewGoCollector returns a collector that exports metrics about the current Go
+// process using debug.GCStats and runtime/metrics.
+func NewGoCollector(opts ...func(o *internal.GoCollectorOptions)) prometheus.Collector {
 	//nolint:staticcheck // Ignore SA1019 until v2.
-	return prometheus.NewGoCollector(promPkgOpts...)
+	return prometheus.NewGoCollector(opts...)
 }

prometheus/collectors/go_collector_latest_test.go

@@ -18,6 +18,7 @@ package collectors
 
 import (
 	"encoding/json"
+	"regexp"
 	"testing"
 
 	"github.com/prometheus/client_golang/prometheus"
@@ -26,7 +27,9 @@ import (
 func TestGoCollectorMarshalling(t *testing.T) {
 	reg := prometheus.NewRegistry()
 	reg.MustRegister(NewGoCollector(
-		WithGoCollections(GoRuntimeMemStatsCollection | GoRuntimeMetricsCollection),
+		WithGoCollectorRuntimeMetrics(GoRuntimeMetricsRule{
+			Matcher: regexp.MustCompile("/.*"),
+		}),
 	))
 	result, err := reg.Gather()
 	if err != nil {
@@ -37,3 +40,9 @@ func TestGoCollectorMarshalling(t *testing.T) {
 		t.Errorf("json marshalling shoud not fail, %v", err)
 	}
 }
+
+func ExampleGoCollector() {
+}
+
+func ExampleGoCollector_WithAdvancedGoMetrics() {
+}

prometheus/go_collector.go

@@ -19,6 +19,10 @@ import (
 	"time"
 )
 
+// goRuntimeMemStats provides the metrics initially provided by runtime.ReadMemStats.
+// From Go 1.17 those similar (and better) statistics are provided by runtime/metrics, so
+// while eval closure works on runtime.MemStats, the struct from Go 1.17+ is
+// populated using runtime/metrics.
 func goRuntimeMemStats() memStatsMetrics {
 	return memStatsMetrics{
 		{
@@ -224,7 +228,7 @@ func newBaseGoCollector() baseGoCollector {
 			"A summary of the pause duration of garbage collection cycles.",
 			nil, nil),
 		gcLastTimeDesc: NewDesc(
-			memstatNamespace("last_gc_time_seconds"),
+			"go_memstats_last_gc_time_seconds",
 			"Number of seconds since 1970 of last garbage collection.",
 			nil, nil),
 		goInfoDesc: NewDesc(
@@ -269,7 +273,6 @@ 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