Merge pull request #455 from prometheus/beorn7/desc

Add a DescribeByCollect helper

prometheus/collector.go

@@ -61,6 +61,37 @@ type Collector interface {
 	Collect(chan<- Metric)
 }
 
+// DescribeByCollect is a helper to implement the Describe method of a custom
+// Collector. It collects the metrics from the provided Collector and sends
+// their descriptors to the provided channel.
+//
+// If a Collector collects the same metrics throughout its lifetime, its
+// Describe method can simply be implemented as:
+//
+//   func (c customCollector) Describe(ch chan<- *Desc) {
+//   	DescribeByCollect(c, ch)
+//   }
+//
+// However, this will not work if the metrics collected change dynamically over
+// the lifetime of the Collector in a way that their combined set of descriptors
+// changes as well. The shortcut implementation will then violate the contract
+// of the Describe method. If a Collector sometimes collects no metrics at all
+// (for example vectors like CounterVec, GaugeVec, etc., which only collect
+// metrics after a metric with a fully specified label set has been accessed),
+// it might even get registered as an unchecked Collecter (cf. the Register
+// method of the Registerer interface). Hence, only use this shortcut
+// implementation of Describe if you are certain to fulfill the contract.
+func DescribeByCollect(c Collector, descs chan<- *Desc) {
+	metrics := make(chan Metric)
+	go func() {
+		c.Collect(metrics)
+		close(metrics)
+	}()
+	for m := range metrics {
+		descs <- m.Desc()
+	}
+}
+
 // selfCollector implements Collector for a single Metric so that the Metric
 // collects itself. Add it as an anonymous field to a struct that implements
 // Metric, and call init with the Metric itself as an argument.

prometheus/collector_test.go

@@ -0,0 +1,62 @@
+// 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 prometheus
+
+import "testing"
+
+type collectorDescribedByCollect struct {
+	cnt Counter
+	gge Gauge
+}
+
+func (c collectorDescribedByCollect) Collect(ch chan<- Metric) {
+	ch <- c.cnt
+	ch <- c.gge
+}
+
+func (c collectorDescribedByCollect) Describe(ch chan<- *Desc) {
+	DescribeByCollect(c, ch)
+}
+
+func TestDescribeByCollect(t *testing.T) {
+
+	goodCollector := collectorDescribedByCollect{
+		cnt: NewCounter(CounterOpts{Name: "c1", Help: "help c1"}),
+		gge: NewGauge(GaugeOpts{Name: "g1", Help: "help g1"}),
+	}
+	collidingCollector := collectorDescribedByCollect{
+		cnt: NewCounter(CounterOpts{Name: "c2", Help: "help c2"}),
+		gge: NewGauge(GaugeOpts{Name: "g1", Help: "help g1"}),
+	}
+	inconsistentCollector := collectorDescribedByCollect{
+		cnt: NewCounter(CounterOpts{Name: "c3", Help: "help c3"}),
+		gge: NewGauge(GaugeOpts{Name: "c3", Help: "help inconsistent"}),
+	}
+
+	reg := NewPedanticRegistry()
+
+	if err := reg.Register(goodCollector); err != nil {
+		t.Error("registration failed:", err)
+	}
+	if err := reg.Register(collidingCollector); err == nil {
+		t.Error("registration unexpectedly succeeded")
+	}
+	if err := reg.Register(inconsistentCollector); err == nil {
+		t.Error("registration unexpectedly succeeded")
+	}
+
+	if _, err := reg.Gather(); err != nil {
+		t.Error("gathering failed:", err)
+	}
+}