Use the runtime/metrics package for the Go collector for 1.17+ (#955)

This change introduces use of the runtime/metrics package in place of
runtime.MemStats for Go 1.17 or later. The runtime/metrics package was
introduced in Go 1.16, but not all the old metrics were accounted for
until 1.17.

The runtime/metrics package offers several advantages over using
runtime.MemStats:
* The list of metrics and their descriptions are machine-readable,
  allowing new metrics to get added without any additional work.
* Detailed histogram-based metrics are now available, offering much
  deeper insights into the Go runtime.
* The runtime/metrics API is significantly more efficient than
  runtime.MemStats, even with the additional metrics added, because
  it does not require any stop-the-world events.

That being said, integrating the package comes with some caveats, some
of which were discussed in #842. Namely:
* The old MemStats-based metrics need to continue working, so they're
  exported under their old names backed by equivalent runtime/metrics
  metrics.
* Earlier versions of Go need to continue working, so the old code
  remains, but behind a build tag.

Finally, a few notes about the implementation:
* This change includes a whole bunch of refactoring to avoid significant
  code duplication.
* This change adds a new histogram metric type specifically optimized
  for runtime/metrics histograms. This type's methods also include
  additional logic to deal with differences in bounds conventions.
* This change makes a whole bunch of decisions about how runtime/metrics
  names are translated.
* This change adds a `go generate` script to generate a list of expected
  runtime/metrics names for a given Go version for auditing. Users of
  new versions of Go will transparently be allowed to use new metrics,
  however.

Signed-off-by: Michael Anthony Knyszek <[email protected]>

Author: mknyszek

prometheus/build_info_collector.go

@@ -0,0 +1,38 @@
+// 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.
+
+package prometheus
+
+import "runtime/debug"
+
+// NewBuildInfoCollector is the obsolete version of collectors.NewBuildInfoCollector.
+// See there for documentation.
+//
+// Deprecated: Use collectors.NewBuildInfoCollector instead.
+func NewBuildInfoCollector() Collector {
+	path, version, sum := "unknown", "unknown", "unknown"
+	if bi, ok := debug.ReadBuildInfo(); ok {
+		path = bi.Main.Path
+		version = bi.Main.Version
+		sum = bi.Main.Sum
+	}
+	c := &selfCollector{MustNewConstMetric(
+		NewDesc(
+			"go_build_info",
+			"Build information about the main Go module.",
+			nil, Labels{"path": path, "version": version, "checksum": sum},
+		),
+		GaugeValue, 1)}
+	c.init(c.self)
+	return c
+}

prometheus/counter.go

@@ -133,10 +133,14 @@ func (c *counter) Inc() {
 	atomic.AddUint64(&c.valInt, 1)
 }
 
-func (c *counter) Write(out *dto.Metric) error {
+func (c *counter) get() float64 {
 	fval := math.Float64frombits(atomic.LoadUint64(&c.valBits))
 	ival := atomic.LoadUint64(&c.valInt)
-	val := fval + float64(ival)
+	return fval + float64(ival)
+}
+
+func (c *counter) Write(out *dto.Metric) error {
+	val := c.get()
 
 	var exemplar *dto.Exemplar
 	if e := c.exemplar.Load(); e != nil {

prometheus/gen_go_collector_metrics_set.go

@@ -0,0 +1,115 @@
+// 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 ignore
+// +build ignore
+
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"go/format"
+	"log"
+	"os"
+	"runtime/metrics"
+	"strconv"
+	"strings"
+	"text/template"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/internal"
+)
+
+func main() {
+	if len(os.Args) != 2 {
+		log.Fatal("requires Go version (e.g. go1.17) as an argument")
+	}
+	version, err := parseVersion(os.Args[1])
+	if err != nil {
+		log.Fatalf("parsing Go version: %v", err)
+	}
+
+	// Generate code.
+	var buf bytes.Buffer
+	err = testFile.Execute(&buf, struct {
+		Descriptions []metrics.Description
+		GoVersion    goVersion
+	}{
+		Descriptions: metrics.All(),
+		GoVersion:    version,
+	})
+	if err != nil {
+		log.Fatalf("executing template: %v", err)
+	}
+
+	// Format it.
+	result, err := format.Source(buf.Bytes())
+	if err != nil {
+		log.Fatalf("formatting code: %v", err)
+	}
+
+	// Write it to a file.
+	fname := fmt.Sprintf("go_collector_metrics_%s_test.go", version.Abbr())
+	if err := os.WriteFile(fname, result, 0o644); err != nil {
+		log.Fatalf("writing file: %v", err)
+	}
+}
+
+type goVersion int
+
+func (g goVersion) String() string {
+	return fmt.Sprintf("go1.%d", g)
+}
+
+func (g goVersion) Abbr() string {
+	return fmt.Sprintf("go1%d", g)
+}
+
+func parseVersion(s string) (goVersion, error) {
+	i := strings.IndexRune(s, '.')
+	if i < 0 {
+		return goVersion(-1), fmt.Errorf("bad Go version format")
+	}
+	i, err := strconv.Atoi(s[i+1:])
+	return goVersion(i), err
+}
+
+var testFile = template.Must(template.New("testFile").Funcs(map[string]interface{}{
+	"rm2prom": func(d metrics.Description) string {
+		ns, ss, n, ok := internal.RuntimeMetricsToProm(&d)
+		if !ok {
+			return ""
+		}
+		return prometheus.BuildFQName(ns, ss, n)
+	},
+	"nextVersion": func(version goVersion) string {
+		return (version + goVersion(1)).String()
+	},
+}).Parse(`// Code generated by gen_go_collector_metrics_set.go; DO NOT EDIT.
+//go:generate go run gen_go_collector_metrics_set.go {{.GoVersion}}
+
+//go:build {{.GoVersion}} && !{{nextVersion .GoVersion}}
+// +build {{.GoVersion}},!{{nextVersion .GoVersion}}
+
+package prometheus
+
+var expectedRuntimeMetrics = map[string]string{
+{{- range .Descriptions -}}
+	{{- $trans := rm2prom . -}}
+	{{- if ne $trans "" }}
+	{{.Name | printf "%q"}}: {{$trans | printf "%q"}},
+	{{- end -}}
+{{end}}
+}
+`))