1// Copyright 2014 The Prometheus Authors 2// Licensed under the Apache License, Version 2.0 (the "License"); 3// you may not use this file except in compliance with the License. 4// You may obtain a copy of the License at 5// 6// http://www.apache.org/licenses/LICENSE-2.0 7// 8// Unless required by applicable law or agreed to in writing, software 9// distributed under the License is distributed on an "AS IS" BASIS, 10// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 11// See the License for the specific language governing permissions and 12// limitations under the License. 13 14package prometheus 15 16// Collector is the interface implemented by anything that can be used by 17// Prometheus to collect metrics. A Collector has to be registered for 18// collection. See Registerer.Register. 19// 20// The stock metrics provided by this package (Gauge, Counter, Summary, 21// Histogram, Untyped) are also Collectors (which only ever collect one metric, 22// namely itself). An implementer of Collector may, however, collect multiple 23// metrics in a coordinated fashion and/or create metrics on the fly. Examples 24// for collectors already implemented in this library are the metric vectors 25// (i.e. collection of multiple instances of the same Metric but with different 26// label values) like GaugeVec or SummaryVec, and the ExpvarCollector. 27type Collector interface { 28 // Describe sends the super-set of all possible descriptors of metrics 29 // collected by this Collector to the provided channel and returns once 30 // the last descriptor has been sent. The sent descriptors fulfill the 31 // consistency and uniqueness requirements described in the Desc 32 // documentation. (It is valid if one and the same Collector sends 33 // duplicate descriptors. Those duplicates are simply ignored. However, 34 // two different Collectors must not send duplicate descriptors.) This 35 // method idempotently sends the same descriptors throughout the 36 // lifetime of the Collector. If a Collector encounters an error while 37 // executing this method, it must send an invalid descriptor (created 38 // with NewInvalidDesc) to signal the error to the registry. 39 Describe(chan<- *Desc) 40 // Collect is called by the Prometheus registry when collecting 41 // metrics. The implementation sends each collected metric via the 42 // provided channel and returns once the last metric has been sent. The 43 // descriptor of each sent metric is one of those returned by 44 // Describe. Returned metrics that share the same descriptor must differ 45 // in their variable label values. This method may be called 46 // concurrently and must therefore be implemented in a concurrency safe 47 // way. Blocking occurs at the expense of total performance of rendering 48 // all registered metrics. Ideally, Collector implementations support 49 // concurrent readers. 50 Collect(chan<- Metric) 51} 52 53// selfCollector implements Collector for a single Metric so that the Metric 54// collects itself. Add it as an anonymous field to a struct that implements 55// Metric, and call init with the Metric itself as an argument. 56type selfCollector struct { 57 self Metric 58} 59 60// init provides the selfCollector with a reference to the metric it is supposed 61// to collect. It is usually called within the factory function to create a 62// metric. See example. 63func (c *selfCollector) init(self Metric) { 64 c.self = self 65} 66 67// Describe implements Collector. 68func (c *selfCollector) Describe(ch chan<- *Desc) { 69 ch <- c.self.Desc() 70} 71 72// Collect implements Collector. 73func (c *selfCollector) Collect(ch chan<- Metric) { 74 ch <- c.self 75} 76