Create a "merge gatherer"

This allows to finally get rid of the infamous injection hook in the
interface. The old SetMetricFamilyInjectionHook still exist as a
deprecated function but is now implemented with the new plumbing under
the hood.

Now that we have multiple Gatherer implementation, I renamed
push.Registry to push.FromGatherer.

This commit also improves the consistency checks, which happened as a
byproduct of the refactoring to allow checking in both the "merge
gatherer" Gatherers as well as in the normal Registry.

prometheus/examples_test.go

@@ -14,13 +14,16 @@
 package prometheus_test
 
 import (
+ "bytes"
  "fmt"
  "math"
  "net/http"
  "runtime"
  "sort"
+ "strings"
 
  dto "github.com/prometheus/client_model/go"
+ "github.com/prometheus/common/expfmt"
 
  "github.com/golang/protobuf/proto"
 
@@ -638,3 +641,111 @@ func ExampleAlreadyRegisteredError() {
  }
  }
 }
+
+func ExampleGatherers() {
+ reg := prometheus.NewRegistry()
+ temp := prometheus.NewGaugeVec(
+ prometheus.GaugeOpts{
+ Name: "temperature_kelvin",
+ Help: "Temperature in Kelvin.",
+ },
+ []string{"location"},
+ )
+ reg.MustRegister(temp)
+ temp.WithLabelValues("outside").Set(273.14)
+ temp.WithLabelValues("inside").Set(298.44)
+
+ var parser expfmt.TextParser
+
+ text := `
+# TYPE humidity_percent gauge
+# HELP humidity_percent Humidity in %.
+humidity_percent{location="outside"} 45.4
+humidity_percent{location="inside"} 33.2
+# TYPE temperature_kelvin gauge
+# HELP temperature_kelvin Temperature in Kelvin.
+temperature_kelvin{location="somewhere else"} 4.5
+`
+
+ parseText := func() ([]*dto.MetricFamily, error) {
+ parsed, err := parser.TextToMetricFamilies(strings.NewReader(text))
+ if err != nil {
+ return nil, err
+ }
+ var result []*dto.MetricFamily
+ for _, mf := range parsed {
+ result = append(result, mf)
+ }
+ return result, nil
+ }
+
+ gatherers := prometheus.Gatherers{
+ reg,
+ prometheus.GathererFunc(parseText),
+ }
+
+ gathering, err := gatherers.Gather()
+ if err != nil {
+ fmt.Println(err)
+ }
+
+ out := &bytes.Buffer{}
+ for _, mf := range gathering {
+ if _, err := expfmt.MetricFamilyToText(out, mf); err != nil {
+ panic(err)
+ }
+ }
+ fmt.Print(out.String())
+ fmt.Println("----------")
+
+ // Note how the temperature_kelvin metric family has been merged from
+ // different sources. Now try
+ text = `
+# TYPE humidity_percent gauge
+# HELP humidity_percent Humidity in %.
+humidity_percent{location="outside"} 45.4
+humidity_percent{location="inside"} 33.2
+# TYPE temperature_kelvin gauge
+# HELP temperature_kelvin Temperature in Kelvin.
+# Duplicate metric:
+temperature_kelvin{location="outside"} 265.3
+ # Wrong labels:
+temperature_kelvin 4.5
+`
+
+ gathering, err = gatherers.Gather()
+ if err != nil {
+ fmt.Println(err)
+ }
+ // Note that still as many metrics as possible are returned:
+ out.Reset()
+ for _, mf := range gathering {
+ if _, err := expfmt.MetricFamilyToText(out, mf); err != nil {
+ panic(err)
+ }
+ }
+ fmt.Print(out.String())
+
+ // Output:
+ // # HELP humidity_percent Humidity in %.
+ // # TYPE humidity_percent gauge
+ // humidity_percent{location="inside"} 33.2
+ // humidity_percent{location="outside"} 45.4
+ // # HELP temperature_kelvin Temperature in Kelvin.
+ // # TYPE temperature_kelvin gauge
+ // temperature_kelvin{location="inside"} 298.44
+ // temperature_kelvin{location="outside"} 273.14
+ // temperature_kelvin{location="somewhere else"} 4.5
+ // ----------
+ // 2 error(s) occurred:
+ // * collected metric temperature_kelvin label:<name:"location" value:"outside" > gauge:<value:265.3 > was collected before with the same name and label values
+ // * collected metric temperature_kelvin gauge:<value:4.5 > has label dimensions inconsistent with previously collected metrics in the same metric family
+ // # HELP humidity_percent Humidity in %.
+ // # TYPE humidity_percent gauge
+ // humidity_percent{location="inside"} 33.2
+ // humidity_percent{location="outside"} 45.4
+ // # HELP temperature_kelvin Temperature in Kelvin.
+ // # TYPE temperature_kelvin gauge
+ // temperature_kelvin{location="inside"} 298.44
+ // temperature_kelvin{location="outside"} 273.14
+}

prometheus/metric.go

@@ -22,10 +22,8 @@ import (
 const separatorByte byte = 255
 
 // A Metric models a single sample value with its meta data being exported to
-// Prometheus. Implementers of Metric in this package inclued Gauge, Counter,
-// Untyped, and Summary. Users can implement their own Metric types, but that
-// should be rarely needed. See the example for SelfCollector, which is also an
-// example for a user-implemented Metric.
+// Prometheus. Implementations of Metric in this package are Gauge, Counter,
+// Histogram, Summary, and Untyped.
 type Metric interface {
  // Desc returns the descriptor for the Metric. This method idempotently
  // returns the same descriptor throughout the lifetime of the
@@ -36,16 +34,18 @@ type Metric interface {
  // Write encodes the Metric into a "Metric" Protocol Buffer data
  // transmission object.
  //
- // Implementers of custom Metric types must observe concurrency safety
- // as reads of this metric may occur at any time, and any blocking
- // occurs at the expense of total performance of rendering all
- // registered metrics. Ideally Metric implementations should support
- // concurrent readers.
+ // Metric implementations must observe concurrency safety as reads of
+ // this metric may occur at any time, and any blocking occurs at the
+ // expense of total performance of rendering all registered
+ // metrics. Ideally, Metric implementations should support concurrent
+ // readers.
  //
- // While populating dto.Metric, it is recommended to sort labels
- // lexicographically. (Implementers may find LabelPairSorter useful for
- // that.) Callers of Write should still make sure of sorting if they
- // depend on it.
+ // While populating dto.Metric, it is the responsibility of the
+ // implementation to ensure validity of the Metric protobuf (like valid
+ // UTF-8 strings or syntactically valid metric and label names). It is
+ // recommended to sort labels lexicographically. (Implementers may find
+ // LabelPairSorter useful for that.) Callers of Write should still make
+ // sure of sorting if they depend on it.
  Write(*dto.Metric) error
  // TODO(beorn7): The original rationale of passing in a pre-allocated
  // dto.Metric protobuf to save allocations has disappeared. The

prometheus/promhttp/http_test.go

@@ -88,13 +88,11 @@ func TestHandlerErrorHandling(t *testing.T) {
  ErrorLog: logger,
  ErrorHandling: PanicOnError,
  })
- wantMsg := `error gathering metrics: 1 error(s) occurred:
-* error collecting metric Desc{fqName: "invalid_metric", help: "not helpful", constLabels: {}, variableLabels: []}: collect error
+ wantMsg := `error gathering metrics: error collecting metric Desc{fqName: "invalid_metric", help: "not helpful", constLabels: {}, variableLabels: []}: collect error
 `
  wantErrorBody := `An error has occurred during metrics gathering:
 
-1 error(s) occurred:
-* error collecting metric Desc{fqName: "invalid_metric", help: "not helpful", constLabels: {}, variableLabels: []}: collect error
+error collecting metric Desc{fqName: "invalid_metric", help: "not helpful", constLabels: {}, variableLabels: []}: collect error
 `
  wantOKBody := `# HELP name docstring
 # TYPE name counter
@@ -110,10 +108,10 @@ the_count 0
  t.Errorf("got HTTP status code %d, want %d", got, want)
  }
  if got := logBuf.String(); got != wantMsg {
- t.Errorf("got log message %q, want %q", got, wantMsg)
+ t.Errorf("got log message:\n%s\nwant log mesage:\n%s\n", got, wantMsg)
  }
  if got := writer.Body.String(); got != wantErrorBody {
- t.Errorf("got body %q, want %q", got, wantErrorBody)
+ t.Errorf("got body:\n%s\nwant body:\n%s\n", got, wantErrorBody)
  }
  logBuf.Reset()
  writer.Body.Reset()

prometheus/push/examples_test.go

@@ -46,7 +46,7 @@ func ExampleRegistry() {
  registry.MustRegister(completionTime)
 
  completionTime.Set(float64(time.Now().Unix()))
- if err := push.Registry(
+ if err := push.FromGatherer(
  "db_backup", push.HostnameGroupingKey(),
  "http:https://pushgateway:9091",
  registry,

prometheus/push/push.go

@@ -44,14 +44,14 @@ import (
 
 const contentTypeHeader = "Content-Type"
 
-// Registry triggers a metric collection by the provided Gatherer (which is
-// usually implemented by a prometheus.Registry, thus the name of the function)
-// and pushes all gathered metrics to the Pushgateway specified by url, using
-// the provided job name and the (optional) further grouping labels (the
-// grouping map may be nil). See the Pushgateway documentation for detailed
-// implications of the job and other grouping labels. Neither the job name nor
-// any grouping label value may contain a "/". The metrics pushed must not
-// contain a job label of their own nor any of the grouping labels.
+// FromGatherer triggers a metric collection by the provided Gatherer (which is
+// usually implemented by a prometheus.Registry) and pushes all gathered metrics
+// to the Pushgateway specified by url, using the provided job name and the
+// (optional) further grouping labels (the grouping map may be nil). See the
+// Pushgateway documentation for detailed implications of the job and other
+// grouping labels. Neither the job name nor any grouping label value may
+// contain a "/". The metrics pushed must not contain a job label of their own
+// nor any of the grouping labels.
 //
 // You can use just host:port or ip:port as url, in which case 'http:https://' is
 // added automatically. You can also include the schema in the URL. However, do
@@ -60,18 +60,18 @@ const contentTypeHeader = "Content-Type"
 // Note that all previously pushed metrics with the same job and other grouping
 // labels will be replaced with the metrics pushed by this call. (It uses HTTP
 // method 'PUT' to push to the Pushgateway.)
-func Registry(job string, grouping map[string]string, url string, reg prometheus.Gatherer) error {
- return push(job, grouping, url, reg, "PUT")
+func FromGatherer(job string, grouping map[string]string, url string, g prometheus.Gatherer) error {
+ return push(job, grouping, url, g, "PUT")
 }
 
-// RegistryAdd works like Registry, but only previously pushed metrics with the
-// same name (and the same job and other grouping labels) will be replaced. (It
-// uses HTTP method 'POST' to push to the Pushgateway.)
-func RegistryAdd(job string, grouping map[string]string, url string, reg prometheus.Gatherer) error {
- return push(job, grouping, url, reg, "POST")
+// AddFromGatherer works like FromGatherer, but only previously pushed metrics
+// with the same name (and the same job and other grouping labels) will be
+// replaced. (It uses HTTP method 'POST' to push to the Pushgateway.)
+func AddFromGatherer(job string, grouping map[string]string, url string, g prometheus.Gatherer) error {
+ return push(job, grouping, url, g, "POST")
 }
 
-func push(job string, grouping map[string]string, pushURL string, reg prometheus.Gatherer, method string) error {
+func push(job string, grouping map[string]string, pushURL string, g prometheus.Gatherer, method string) error {
  if !strings.Contains(pushURL, ":https://") {
  pushURL = "http:https://" + pushURL
  }
@@ -94,7 +94,7 @@ func push(job string, grouping map[string]string, pushURL string, reg prometheus
  }
  pushURL = fmt.Sprintf("%s/metrics/job/%s", pushURL, strings.Join(urlComponents, "/"))
 
- mfs, err := reg.Gather()
+ mfs, err := g.Gather()
  if err != nil {
  return err
  }
@@ -134,14 +134,14 @@ func push(job string, grouping map[string]string, pushURL string, reg prometheus
  return nil
 }
 
-// Collectors works like Registry, but it does not use a Gatherer. Instead, it
-// collects from the provided collectors directly. It is a convenient way to
+// Collectors works like FromGatherer, but it does not use a Gatherer. Instead,
+// it collects from the provided collectors directly. It is a convenient way to
 // push only a few metrics.
 func Collectors(job string, grouping map[string]string, url string, collectors ...prometheus.Collector) error {
  return pushCollectors(job, grouping, url, "PUT", collectors...)
 }
 
-// AddCollectors works like RegistryAdd, but it does not use a Gatherer.
+// AddCollectors works like AddFromGatherer, but it does not use a Gatherer.
 // Instead, it collects from the provided collectors directly. It is a
 // convenient way to push only a few metrics.
 func AddCollectors(job string, grouping map[string]string, url string, collectors ...prometheus.Collector) error {

prometheus/push/push_test.go

@@ -150,7 +150,7 @@ func TestPush(t *testing.T) {
  }
 
  // Push registry, all good.
- if err := Registry("testjob", HostnameGroupingKey(), pgwOK.URL, reg); err != nil {
+ if err := FromGatherer("testjob", HostnameGroupingKey(), pgwOK.URL, reg); err != nil {
  t.Fatal(err)
  }
  if lastMethod != "PUT" {
@@ -161,7 +161,7 @@ func TestPush(t *testing.T) {
  }
 
  // PushAdd registry, all good.
- if err := RegistryAdd("testjob", map[string]string{"a": "x", "b": "y"}, pgwOK.URL, reg); err != nil {
+ if err := AddFromGatherer("testjob", map[string]string{"a": "x", "b": "y"}, pgwOK.URL, reg); err != nil {
  t.Fatal(err)
  }
  if lastMethod != "POST" {