diff --git a/prometheus/collector.go b/prometheus/collector.go index 3c9bae2..82d4c3b 100644 --- a/prometheus/collector.go +++ b/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. diff --git a/prometheus/collector_test.go b/prometheus/collector_test.go new file mode 100644 index 0000000..45eab3e --- /dev/null +++ b/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) + } +}