test(metrics): Improve test coverage

metrics/metrics_test.go

@@ -0,0 +1,116 @@
+package metrics
+
+import (
+	"bytes"
+	"testing"
+	"time"
+
+	"github.com/TwiN/gatus/v3/core"
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/testutil"
+)
+
+func TestPublishMetricsForEndpoint(t *testing.T) {
+	httpEndpoint := &core.Endpoint{Name: "http-ep-name", Group: "http-ep-group", URL: "https://example.org"}
+	PublishMetricsForEndpoint(httpEndpoint, &core.Result{
+		HTTPStatus: 200,
+		Connected:  true,
+		Duration:   123 * time.Millisecond,
+		ConditionResults: []*core.ConditionResult{
+			{Condition: "[STATUS] == 200", Success: true},
+			{Condition: "[CERTIFICATE_EXPIRATION] > 48h", Success: true},
+		},
+		Success:               true,
+		CertificateExpiration: 49 * time.Hour,
+	})
+	err := testutil.GatherAndCompare(prometheus.Gatherers{prometheus.DefaultGatherer}, bytes.NewBufferString(`
+# HELP gatus_results_certificate_expiration_seconds Number of seconds until the certificate expires
+# TYPE gatus_results_certificate_expiration_seconds gauge
+gatus_results_certificate_expiration_seconds{group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",type="HTTP"} 176400
+# HELP gatus_results_code_total Total number of results by code
+# TYPE gatus_results_code_total counter
+gatus_results_code_total{code="200",group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",type="HTTP"} 1
+# HELP gatus_results_connected_total Total number of results in which a connection was successfully established
+# TYPE gatus_results_connected_total counter
+gatus_results_connected_total{group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",type="HTTP"} 1
+# HELP gatus_results_duration_seconds Duration of the request in seconds
+# TYPE gatus_results_duration_seconds gauge
+gatus_results_duration_seconds{group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",type="HTTP"} 0.123
+# HELP gatus_results_total Number of results per endpoint
+# TYPE gatus_results_total counter
+gatus_results_total{group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",success="true",type="HTTP"} 1
+`), "gatus_results_code_total", "gatus_results_connected_total", "gatus_results_duration_seconds", "gatus_results_total", "gatus_results_certificate_expiration_seconds")
+	if err != nil {
+		t.Errorf("Expected no errors but got: %v", err)
+	}
+	PublishMetricsForEndpoint(httpEndpoint, &core.Result{
+		HTTPStatus: 200,
+		Connected:  true,
+		Duration:   125 * time.Millisecond,
+		ConditionResults: []*core.ConditionResult{
+			{Condition: "[STATUS] == 200", Success: true},
+			{Condition: "[CERTIFICATE_EXPIRATION] > 47h", Success: false},
+		},
+		Success:               false,
+		CertificateExpiration: 47 * time.Hour,
+	})
+	err = testutil.GatherAndCompare(prometheus.Gatherers{prometheus.DefaultGatherer}, bytes.NewBufferString(`
+# HELP gatus_results_certificate_expiration_seconds Number of seconds until the certificate expires
+# TYPE gatus_results_certificate_expiration_seconds gauge
+gatus_results_certificate_expiration_seconds{group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",type="HTTP"} 169200
+# HELP gatus_results_code_total Total number of results by code
+# TYPE gatus_results_code_total counter
+gatus_results_code_total{code="200",group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",type="HTTP"} 2
+# HELP gatus_results_connected_total Total number of results in which a connection was successfully established
+# TYPE gatus_results_connected_total counter
+gatus_results_connected_total{group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",type="HTTP"} 2
+# HELP gatus_results_duration_seconds Duration of the request in seconds
+# TYPE gatus_results_duration_seconds gauge
+gatus_results_duration_seconds{group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",type="HTTP"} 0.125
+# HELP gatus_results_total Number of results per endpoint
+# TYPE gatus_results_total counter
+gatus_results_total{group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",success="false",type="HTTP"} 1
+gatus_results_total{group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",success="true",type="HTTP"} 1
+`), "gatus_results_code_total", "gatus_results_connected_total", "gatus_results_duration_seconds", "gatus_results_total", "gatus_results_certificate_expiration_seconds")
+	if err != nil {
+		t.Errorf("Expected no errors but got: %v", err)
+	}
+	dnsEndpoint := &core.Endpoint{Name: "dns-ep-name", Group: "dns-ep-group", URL: "1.1.1.1", DNS: &core.DNS{
+		QueryType: "A",
+		QueryName: "example.com.",
+	}}
+	PublishMetricsForEndpoint(dnsEndpoint, &core.Result{
+		DNSRCode:  "NOERROR",
+		Connected: true,
+		Duration:  50 * time.Millisecond,
+		ConditionResults: []*core.ConditionResult{
+			{Condition: "[DNS_RCODE] == NOERROR", Success: true},
+		},
+		Success: true,
+	})
+	err = testutil.GatherAndCompare(prometheus.Gatherers{prometheus.DefaultGatherer}, bytes.NewBufferString(`
+# HELP gatus_results_certificate_expiration_seconds Number of seconds until the certificate expires
+# TYPE gatus_results_certificate_expiration_seconds gauge
+gatus_results_certificate_expiration_seconds{group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",type="HTTP"} 169200
+# HELP gatus_results_code_total Total number of results by code
+# TYPE gatus_results_code_total counter
+gatus_results_code_total{code="200",group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",type="HTTP"} 2
+gatus_results_code_total{code="NOERROR",group="dns-ep-group",key="dns-ep-group_dns-ep-name",name="dns-ep-name",type="DNS"} 1
+# HELP gatus_results_connected_total Total number of results in which a connection was successfully established
+# TYPE gatus_results_connected_total counter
+gatus_results_connected_total{group="dns-ep-group",key="dns-ep-group_dns-ep-name",name="dns-ep-name",type="DNS"} 1
+gatus_results_connected_total{group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",type="HTTP"} 2
+# HELP gatus_results_duration_seconds Duration of the request in seconds
+# TYPE gatus_results_duration_seconds gauge
+gatus_results_duration_seconds{group="dns-ep-group",key="dns-ep-group_dns-ep-name",name="dns-ep-name",type="DNS"} 0.05
+gatus_results_duration_seconds{group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",type="HTTP"} 0.125
+# HELP gatus_results_total Number of results per endpoint
+# TYPE gatus_results_total counter
+gatus_results_total{group="dns-ep-group",key="dns-ep-group_dns-ep-name",name="dns-ep-name",success="true",type="DNS"} 1
+gatus_results_total{group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",success="false",type="HTTP"} 1
+gatus_results_total{group="http-ep-group",key="http-ep-group_http-ep-name",name="http-ep-name",success="true",type="HTTP"} 1
+`), "gatus_results_code_total", "gatus_results_connected_total", "gatus_results_duration_seconds", "gatus_results_total", "gatus_results_certificate_expiration_seconds")
+	if err != nil {
+		t.Errorf("Expected no errors but got: %v", err)
+	}
+}

vendor/github.com/prometheus/client_golang/prometheus/testutil/lint.go

@@ -0,0 +1,46 @@
+// Copyright 2020 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 testutil
+
+import (
+	"fmt"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/testutil/promlint"
+)
+
+// CollectAndLint registers the provided Collector with a newly created pedantic
+// Registry. It then calls GatherAndLint with that Registry and with the
+// provided metricNames.
+func CollectAndLint(c prometheus.Collector, metricNames ...string) ([]promlint.Problem, error) {
+	reg := prometheus.NewPedanticRegistry()
+	if err := reg.Register(c); err != nil {
+		return nil, fmt.Errorf("registering collector failed: %s", err)
+	}
+	return GatherAndLint(reg, metricNames...)
+}
+
+// GatherAndLint gathers all metrics from the provided Gatherer and checks them
+// with the linter in the promlint package. If any metricNames are provided,
+// only metrics with those names are checked.
+func GatherAndLint(g prometheus.Gatherer, metricNames ...string) ([]promlint.Problem, error) {
+	got, err := g.Gather()
+	if err != nil {
+		return nil, fmt.Errorf("gathering metrics failed: %s", err)
+	}
+	if metricNames != nil {
+		got = filterMetrics(got, metricNames)
+	}
+	return promlint.NewWithMetricFamilies(got).Lint()
+}

vendor/github.com/prometheus/client_golang/prometheus/testutil/promlint/promlint.go

@@ -0,0 +1,386 @@
+// Copyright 2020 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 promlint provides a linter for Prometheus metrics.
+package promlint
+
+import (
+	"fmt"
+	"io"
+	"regexp"
+	"sort"
+	"strings"
+
+	"github.com/prometheus/common/expfmt"
+
+	dto "github.com/prometheus/client_model/go"
+)
+
+// A Linter is a Prometheus metrics linter.  It identifies issues with metric
+// names, types, and metadata, and reports them to the caller.
+type Linter struct {
+	// The linter will read metrics in the Prometheus text format from r and
+	// then lint it, _and_ it will lint the metrics provided directly as
+	// MetricFamily proto messages in mfs. Note, however, that the current
+	// constructor functions New and NewWithMetricFamilies only ever set one
+	// of them.
+	r   io.Reader
+	mfs []*dto.MetricFamily
+}
+
+// A Problem is an issue detected by a Linter.
+type Problem struct {
+	// The name of the metric indicated by this Problem.
+	Metric string
+
+	// A description of the issue for this Problem.
+	Text string
+}
+
+// newProblem is helper function to create a Problem.
+func newProblem(mf *dto.MetricFamily, text string) Problem {
+	return Problem{
+		Metric: mf.GetName(),
+		Text:   text,
+	}
+}
+
+// New creates a new Linter that reads an input stream of Prometheus metrics in
+// the Prometheus text exposition format.
+func New(r io.Reader) *Linter {
+	return &Linter{
+		r: r,
+	}
+}
+
+// NewWithMetricFamilies creates a new Linter that reads from a slice of
+// MetricFamily protobuf messages.
+func NewWithMetricFamilies(mfs []*dto.MetricFamily) *Linter {
+	return &Linter{
+		mfs: mfs,
+	}
+}
+
+// Lint performs a linting pass, returning a slice of Problems indicating any
+// issues found in the metrics stream. The slice is sorted by metric name
+// and issue description.
+func (l *Linter) Lint() ([]Problem, error) {
+	var problems []Problem
+
+	if l.r != nil {
+		d := expfmt.NewDecoder(l.r, expfmt.FmtText)
+
+		mf := &dto.MetricFamily{}
+		for {
+			if err := d.Decode(mf); err != nil {
+				if err == io.EOF {
+					break
+				}
+
+				return nil, err
+			}
+
+			problems = append(problems, lint(mf)...)
+		}
+	}
+	for _, mf := range l.mfs {
+		problems = append(problems, lint(mf)...)
+	}
+
+	// Ensure deterministic output.
+	sort.SliceStable(problems, func(i, j int) bool {
+		if problems[i].Metric == problems[j].Metric {
+			return problems[i].Text < problems[j].Text
+		}
+		return problems[i].Metric < problems[j].Metric
+	})
+
+	return problems, nil
+}
+
+// lint is the entry point for linting a single metric.
+func lint(mf *dto.MetricFamily) []Problem {
+	fns := []func(mf *dto.MetricFamily) []Problem{
+		lintHelp,
+		lintMetricUnits,
+		lintCounter,
+		lintHistogramSummaryReserved,
+		lintMetricTypeInName,
+		lintReservedChars,
+		lintCamelCase,
+		lintUnitAbbreviations,
+	}
+
+	var problems []Problem
+	for _, fn := range fns {
+		problems = append(problems, fn(mf)...)
+	}
+
+	// TODO(mdlayher): lint rules for specific metrics types.
+	return problems
+}
+
+// lintHelp detects issues related to the help text for a metric.
+func lintHelp(mf *dto.MetricFamily) []Problem {
+	var problems []Problem
+
+	// Expect all metrics to have help text available.
+	if mf.Help == nil {
+		problems = append(problems, newProblem(mf, "no help text"))
+	}
+
+	return problems
+}
+
+// lintMetricUnits detects issues with metric unit names.
+func lintMetricUnits(mf *dto.MetricFamily) []Problem {
+	var problems []Problem
+
+	unit, base, ok := metricUnits(*mf.Name)
+	if !ok {
+		// No known units detected.
+		return nil
+	}
+
+	// Unit is already a base unit.
+	if unit == base {
+		return nil
+	}
+
+	problems = append(problems, newProblem(mf, fmt.Sprintf("use base unit %q instead of %q", base, unit)))
+
+	return problems
+}
+
+// lintCounter detects issues specific to counters, as well as patterns that should
+// only be used with counters.
+func lintCounter(mf *dto.MetricFamily) []Problem {
+	var problems []Problem
+
+	isCounter := mf.GetType() == dto.MetricType_COUNTER
+	isUntyped := mf.GetType() == dto.MetricType_UNTYPED
+	hasTotalSuffix := strings.HasSuffix(mf.GetName(), "_total")
+
+	switch {
+	case isCounter && !hasTotalSuffix:
+		problems = append(problems, newProblem(mf, `counter metrics should have "_total" suffix`))
+	case !isUntyped && !isCounter && hasTotalSuffix:
+		problems = append(problems, newProblem(mf, `non-counter metrics should not have "_total" suffix`))
+	}
+
+	return problems
+}
+
+// lintHistogramSummaryReserved detects when other types of metrics use names or labels
+// reserved for use by histograms and/or summaries.
+func lintHistogramSummaryReserved(mf *dto.MetricFamily) []Problem {
+	// These rules do not apply to untyped metrics.
+	t := mf.GetType()
+	if t == dto.MetricType_UNTYPED {
+		return nil
+	}
+
+	var problems []Problem
+
+	isHistogram := t == dto.MetricType_HISTOGRAM
+	isSummary := t == dto.MetricType_SUMMARY
+
+	n := mf.GetName()
+
+	if !isHistogram && strings.HasSuffix(n, "_bucket") {
+		problems = append(problems, newProblem(mf, `non-histogram metrics should not have "_bucket" suffix`))
+	}
+	if !isHistogram && !isSummary && strings.HasSuffix(n, "_count") {
+		problems = append(problems, newProblem(mf, `non-histogram and non-summary metrics should not have "_count" suffix`))
+	}
+	if !isHistogram && !isSummary && strings.HasSuffix(n, "_sum") {
+		problems = append(problems, newProblem(mf, `non-histogram and non-summary metrics should not have "_sum" suffix`))
+	}
+
+	for _, m := range mf.GetMetric() {
+		for _, l := range m.GetLabel() {
+			ln := l.GetName()
+
+			if !isHistogram && ln == "le" {
+				problems = append(problems, newProblem(mf, `non-histogram metrics should not have "le" label`))
+			}
+			if !isSummary && ln == "quantile" {
+				problems = append(problems, newProblem(mf, `non-summary metrics should not have "quantile" label`))
+			}
+		}
+	}
+
+	return problems
+}
+
+// lintMetricTypeInName detects when metric types are included in the metric name.
+func lintMetricTypeInName(mf *dto.MetricFamily) []Problem {
+	var problems []Problem
+	n := strings.ToLower(mf.GetName())
+
+	for i, t := range dto.MetricType_name {
+		if i == int32(dto.MetricType_UNTYPED) {
+			continue
+		}
+
+		typename := strings.ToLower(t)
+		if strings.Contains(n, "_"+typename+"_") || strings.HasSuffix(n, "_"+typename) {
+			problems = append(problems, newProblem(mf, fmt.Sprintf(`metric name should not include type '%s'`, typename)))
+		}
+	}
+	return problems
+}
+
+// lintReservedChars detects colons in metric names.
+func lintReservedChars(mf *dto.MetricFamily) []Problem {
+	var problems []Problem
+	if strings.Contains(mf.GetName(), ":") {
+		problems = append(problems, newProblem(mf, "metric names should not contain ':'"))
+	}
+	return problems
+}
+
+var camelCase = regexp.MustCompile(`[a-z][A-Z]`)
+
+// lintCamelCase detects metric names and label names written in camelCase.
+func lintCamelCase(mf *dto.MetricFamily) []Problem {
+	var problems []Problem
+	if camelCase.FindString(mf.GetName()) != "" {
+		problems = append(problems, newProblem(mf, "metric names should be written in 'snake_case' not 'camelCase'"))
+	}
+
+	for _, m := range mf.GetMetric() {
+		for _, l := range m.GetLabel() {
+			if camelCase.FindString(l.GetName()) != "" {
+				problems = append(problems, newProblem(mf, "label names should be written in 'snake_case' not 'camelCase'"))
+			}
+		}
+	}
+	return problems
+}
+
+// lintUnitAbbreviations detects abbreviated units in the metric name.
+func lintUnitAbbreviations(mf *dto.MetricFamily) []Problem {
+	var problems []Problem
+	n := strings.ToLower(mf.GetName())
+	for _, s := range unitAbbreviations {
+		if strings.Contains(n, "_"+s+"_") || strings.HasSuffix(n, "_"+s) {
+			problems = append(problems, newProblem(mf, "metric names should not contain abbreviated units"))
+		}
+	}
+	return problems
+}
+
+// metricUnits attempts to detect known unit types used as part of a metric name,
+// e.g. "foo_bytes_total" or "bar_baz_milligrams".
+func metricUnits(m string) (unit string, base string, ok bool) {
+	ss := strings.Split(m, "_")
+
+	for unit, base := range units {
+		// Also check for "no prefix".
+		for _, p := range append(unitPrefixes, "") {
+			for _, s := range ss {
+				// Attempt to explicitly match a known unit with a known prefix,
+				// as some words may look like "units" when matching suffix.
+				//
+				// As an example, "thermometers" should not match "meters", but
+				// "kilometers" should.
+				if s == p+unit {
+					return p + unit, base, true
+				}
+			}
+		}
+	}
+
+	return "", "", false
+}
+
+// Units and their possible prefixes recognized by this library.  More can be
+// added over time as needed.
+var (
+	// map a unit to the appropriate base unit.
+	units = map[string]string{
+		// Base units.
+		"amperes": "amperes",
+		"bytes":   "bytes",
+		"celsius": "celsius", // Also allow Celsius because it is common in typical Prometheus use cases.
+		"grams":   "grams",
+		"joules":  "joules",
+		"kelvin":  "kelvin", // SI base unit, used in special cases (e.g. color temperature, scientific measurements).
+		"meters":  "meters", // Both American and international spelling permitted.
+		"metres":  "metres",
+		"seconds": "seconds",
+		"volts":   "volts",
+
+		// Non base units.
+		// Time.
+		"minutes": "seconds",
+		"hours":   "seconds",
+		"days":    "seconds",
+		"weeks":   "seconds",
+		// Temperature.
+		"kelvins":    "kelvin",
+		"fahrenheit": "celsius",
+		"rankine":    "celsius",
+		// Length.
+		"inches": "meters",
+		"yards":  "meters",
+		"miles":  "meters",
+		// Bytes.
+		"bits": "bytes",
+		// Energy.
+		"calories": "joules",
+		// Mass.
+		"pounds": "grams",
+		"ounces": "grams",
+	}
+
+	unitPrefixes = []string{
+		"pico",
+		"nano",
+		"micro",
+		"milli",
+		"centi",
+		"deci",
+		"deca",
+		"hecto",
+		"kilo",
+		"kibi",
+		"mega",
+		"mibi",
+		"giga",
+		"gibi",
+		"tera",
+		"tebi",
+		"peta",
+		"pebi",
+	}
+
+	// Common abbreviations that we'd like to discourage.
+	unitAbbreviations = []string{
+		"s",
+		"ms",
+		"us",
+		"ns",
+		"sec",
+		"b",
+		"kb",
+		"mb",
+		"gb",
+		"tb",
+		"pb",
+		"m",
+		"h",
+		"d",
+	}
+)

vendor/github.com/prometheus/client_golang/prometheus/testutil/testutil.go

@@ -0,0 +1,230 @@
+// Copyright 2018 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 testutil provides helpers to test code using the prometheus package
+// of client_golang.
+//
+// While writing unit tests to verify correct instrumentation of your code, it's
+// a common mistake to mostly test the instrumentation library instead of your
+// own code. Rather than verifying that a prometheus.Counter's value has changed
+// as expected or that it shows up in the exposition after registration, it is
+// in general more robust and more faithful to the concept of unit tests to use
+// mock implementations of the prometheus.Counter and prometheus.Registerer
+// interfaces that simply assert that the Add or Register methods have been
+// called with the expected arguments. However, this might be overkill in simple
+// scenarios. The ToFloat64 function is provided for simple inspection of a
+// single-value metric, but it has to be used with caution.
+//
+// End-to-end tests to verify all or larger parts of the metrics exposition can
+// be implemented with the CollectAndCompare or GatherAndCompare functions. The
+// most appropriate use is not so much testing instrumentation of your code, but
+// testing custom prometheus.Collector implementations and in particular whole
+// exporters, i.e. programs that retrieve telemetry data from a 3rd party source
+// and convert it into Prometheus metrics.
+//
+// In a similar pattern, CollectAndLint and GatherAndLint can be used to detect
+// metrics that have issues with their name, type, or metadata without being
+// necessarily invalid, e.g. a counter with a name missing the “_total” suffix.
+package testutil
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+
+	"github.com/prometheus/common/expfmt"
+
+	dto "github.com/prometheus/client_model/go"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/internal"
+)
+
+// ToFloat64 collects all Metrics from the provided Collector. It expects that
+// this results in exactly one Metric being collected, which must be a Gauge,
+// Counter, or Untyped. In all other cases, ToFloat64 panics. ToFloat64 returns
+// the value of the collected Metric.
+//
+// The Collector provided is typically a simple instance of Gauge or Counter, or
+// – less commonly – a GaugeVec or CounterVec with exactly one element. But any
+// Collector fulfilling the prerequisites described above will do.
+//
+// Use this function with caution. It is computationally very expensive and thus
+// not suited at all to read values from Metrics in regular code. This is really
+// only for testing purposes, and even for testing, other approaches are often
+// more appropriate (see this package's documentation).
+//
+// A clear anti-pattern would be to use a metric type from the prometheus
+// package to track values that are also needed for something else than the
+// exposition of Prometheus metrics. For example, you would like to track the
+// number of items in a queue because your code should reject queuing further
+// items if a certain limit is reached. It is tempting to track the number of
+// items in a prometheus.Gauge, as it is then easily available as a metric for
+// exposition, too. However, then you would need to call ToFloat64 in your
+// regular code, potentially quite often. The recommended way is to track the
+// number of items conventionally (in the way you would have done it without
+// considering Prometheus metrics) and then expose the number with a
+// prometheus.GaugeFunc.
+func ToFloat64(c prometheus.Collector) float64 {
+	var (
+		m      prometheus.Metric
+		mCount int
+		mChan  = make(chan prometheus.Metric)
+		done   = make(chan struct{})
+	)
+
+	go func() {
+		for m = range mChan {
+			mCount++
+		}
+		close(done)
+	}()
+
+	c.Collect(mChan)
+	close(mChan)
+	<-done
+
+	if mCount != 1 {
+		panic(fmt.Errorf("collected %d metrics instead of exactly 1", mCount))
+	}
+
+	pb := &dto.Metric{}
+	m.Write(pb)
+	if pb.Gauge != nil {
+		return pb.Gauge.GetValue()
+	}
+	if pb.Counter != nil {
+		return pb.Counter.GetValue()
+	}
+	if pb.Untyped != nil {
+		return pb.Untyped.GetValue()
+	}
+	panic(fmt.Errorf("collected a non-gauge/counter/untyped metric: %s", pb))
+}
+
+// CollectAndCount registers the provided Collector with a newly created
+// pedantic Registry. It then calls GatherAndCount with that Registry and with
+// the provided metricNames. In the unlikely case that the registration or the
+// gathering fails, this function panics. (This is inconsistent with the other
+// CollectAnd… functions in this package and has historical reasons. Changing
+// the function signature would be a breaking change and will therefore only
+// happen with the next major version bump.)
+func CollectAndCount(c prometheus.Collector, metricNames ...string) int {
+	reg := prometheus.NewPedanticRegistry()
+	if err := reg.Register(c); err != nil {
+		panic(fmt.Errorf("registering collector failed: %s", err))
+	}
+	result, err := GatherAndCount(reg, metricNames...)
+	if err != nil {
+		panic(err)
+	}
+	return result
+}
+
+// GatherAndCount gathers all metrics from the provided Gatherer and counts
+// them. It returns the number of metric children in all gathered metric
+// families together. If any metricNames are provided, only metrics with those
+// names are counted.
+func GatherAndCount(g prometheus.Gatherer, metricNames ...string) (int, error) {
+	got, err := g.Gather()
+	if err != nil {
+		return 0, fmt.Errorf("gathering metrics failed: %s", err)
+	}
+	if metricNames != nil {
+		got = filterMetrics(got, metricNames)
+	}
+
+	result := 0
+	for _, mf := range got {
+		result += len(mf.GetMetric())
+	}
+	return result, nil
+}
+
+// CollectAndCompare registers the provided Collector with a newly created
+// pedantic Registry. It then calls GatherAndCompare with that Registry and with
+// the provided metricNames.
+func CollectAndCompare(c prometheus.Collector, expected io.Reader, metricNames ...string) error {
+	reg := prometheus.NewPedanticRegistry()
+	if err := reg.Register(c); err != nil {
+		return fmt.Errorf("registering collector failed: %s", err)
+	}
+	return GatherAndCompare(reg, expected, metricNames...)
+}
+
+// GatherAndCompare gathers all metrics from the provided Gatherer and compares
+// it to an expected output read from the provided Reader in the Prometheus text
+// exposition format. If any metricNames are provided, only metrics with those
+// names are compared.
+func GatherAndCompare(g prometheus.Gatherer, expected io.Reader, metricNames ...string) error {
+	got, err := g.Gather()
+	if err != nil {
+		return fmt.Errorf("gathering metrics failed: %s", err)
+	}
+	if metricNames != nil {
+		got = filterMetrics(got, metricNames)
+	}
+	var tp expfmt.TextParser
+	wantRaw, err := tp.TextToMetricFamilies(expected)
+	if err != nil {
+		return fmt.Errorf("parsing expected metrics failed: %s", err)
+	}
+	want := internal.NormalizeMetricFamilies(wantRaw)
+
+	return compare(got, want)
+}
+
+// compare encodes both provided slices of metric families into the text format,
+// compares their string message, and returns an error if they do not match.
+// The error contains the encoded text of both the desired and the actual
+// result.
+func compare(got, want []*dto.MetricFamily) error {
+	var gotBuf, wantBuf bytes.Buffer
+	enc := expfmt.NewEncoder(&gotBuf, expfmt.FmtText)
+	for _, mf := range got {
+		if err := enc.Encode(mf); err != nil {
+			return fmt.Errorf("encoding gathered metrics failed: %s", err)
+		}
+	}
+	enc = expfmt.NewEncoder(&wantBuf, expfmt.FmtText)
+	for _, mf := range want {
+		if err := enc.Encode(mf); err != nil {
+			return fmt.Errorf("encoding expected metrics failed: %s", err)
+		}
+	}
+
+	if wantBuf.String() != gotBuf.String() {
+		return fmt.Errorf(`
+metric output does not match expectation; want:
+
+%s
+got:
+
+%s`, wantBuf.String(), gotBuf.String())
+
+	}
+	return nil
+}
+
+func filterMetrics(metrics []*dto.MetricFamily, names []string) []*dto.MetricFamily {
+	var filtered []*dto.MetricFamily
+	for _, m := range metrics {
+		for _, name := range names {
+			if m.GetName() == name {
+				filtered = append(filtered, m)
+				break
+			}
+		}
+	}
+	return filtered
+}

vendor/modules.txt

@@ -59,6 +59,8 @@ github.com/prometheus/client_golang/prometheus
 github.com/prometheus/client_golang/prometheus/internal
 github.com/prometheus/client_golang/prometheus/promauto
 github.com/prometheus/client_golang/prometheus/promhttp
+github.com/prometheus/client_golang/prometheus/testutil
+github.com/prometheus/client_golang/prometheus/testutil/promlint
 # github.com/prometheus/client_model v0.2.0
 ## explicit; go 1.9
 github.com/prometheus/client_model/go