Rename Deliver into Gather

This commit is contained in:
beorn7 2016-08-04 15:26:27 +02:00
parent f9c977b1d6
commit f0c45acc50
8 changed files with 53 additions and 54 deletions

View File

@ -146,7 +146,7 @@
// So far, everything we did operated on the so-called default registry, as it
// can be found in the global DefaultRegistry variable. With NewRegistry, you
// can create a custom registry, or you can even implement the Registerer or
// Deliverer interfaces yourself. The methods Register and Unregister work in
// Gatherer interfaces yourself. The methods Register and Unregister work in
// the same way on a custom registry as the global functions Register and
// Unregister on the default registry.
//
@ -163,10 +163,10 @@
//
// HTTP Exposition
//
// The Registry implements the Deliverer interface. The caller of the Deliver
// method can then expose the delivered metrics in some way. Usually, the
// metrics are served via HTTP on the /metrics endpoint. That's happening in the
// example above. The tools to expose metrics via HTTP are in the promhttp
// The Registry implements the Gatherer interface. The caller of the Gather
// method can then expose the gathered metrics in some way. Usually, the metrics
// are served via HTTP on the /metrics endpoint. That's happening in the example
// above. The tools to expose metrics via HTTP are in the promhttp
// sub-package. (The top-level functions in the prometheus package are
// deprecated.)
//

View File

@ -390,7 +390,7 @@ func ExampleSummaryVec() {
reg := prometheus.NewRegistry()
reg.MustRegister(temps)
metricFamilies, err := reg.Deliver()
metricFamilies, err := reg.Gather()
if err != nil || len(metricFamilies) != 1 {
panic("unexpected behavior of custom test registry")
}

View File

@ -56,7 +56,7 @@ func giveBuf(buf *bytes.Buffer) {
bufPool.Put(buf)
}
// Handler returns an HTTP handler for the DefaultDeliverer. It is
// Handler returns an HTTP handler for the DefaultGatherer. It is
// already instrumented with InstrumentHandler (using "prometheus" as handler
// name).
//
@ -67,12 +67,12 @@ func Handler() http.Handler {
return InstrumentHandler("prometheus", UninstrumentedHandler())
}
// UninstrumentedHandler returns an HTTP handler for the DefaultDeliverer.
// UninstrumentedHandler returns an HTTP handler for the DefaultGatherer.
//
// Deprecated: Use promhttp.Handler instead. See there for further documentation.
func UninstrumentedHandler() http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
mfs, err := DefaultDeliverer.Deliver()
mfs, err := DefaultGatherer.Gather()
if err != nil {
http.Error(w, "An error has occurred during metrics collection:\n\n"+err.Error(), http.StatusInternalServerError)
return

View File

@ -25,7 +25,7 @@ func TestProcessCollector(t *testing.T) {
t.Fatal(err)
}
mfs, err := registry.Deliver()
mfs, err := registry.Gather()
if err != nil {
t.Fatal(err)
}

View File

@ -22,9 +22,9 @@
// will also contain tooling to instrument instances of http.Handler and
// http.RoundTripper.
//
// promhttp.Handler acts on the prometheus.DefaultDeliverer. With HandlerFor,
// promhttp.Handler acts on the prometheus.DefaultGatherer. With HandlerFor,
// you can create a handler for a custom registry or anything that implements
// the Deliverer interface. It also allows to create handlers that act
// the Gatherer interface. It also allows to create handlers that act
// differently on errors or allow to log errors.
package promhttp
@ -64,22 +64,22 @@ func giveBuf(buf *bytes.Buffer) {
bufPool.Put(buf)
}
// Handler returns an HTTP handler for the prometheus.DefaultDeliverer. The
// Handler returns an HTTP handler for the prometheus.DefaultGatherer. The
// Handler uses the default HandlerOpts, i.e. report the first error as an HTTP
// error, no error logging, and compression if requested by the client.
//
// If you want to create a Handler for the DefaultDeliverer with different
// HandlerOpts, create it with HandlerFor with prometheus.DefaultDeliverer and
// If you want to create a Handler for the DefaultGatherer with different
// HandlerOpts, create it with HandlerFor with prometheus.DefaultGatherer and
// your desired HandlerOpts.
func Handler() http.Handler {
return HandlerFor(prometheus.DefaultDeliverer, HandlerOpts{})
return HandlerFor(prometheus.DefaultGatherer, HandlerOpts{})
}
// HandlerFor returns an http.Handler for the provided Deliverer. The behavior
// HandlerFor returns an http.Handler for the provided Gatherer. The behavior
// ef the Handler is defined by the provided HandlerOpts.
func HandlerFor(reg prometheus.Deliverer, opts HandlerOpts) http.Handler {
func HandlerFor(reg prometheus.Gatherer, opts HandlerOpts) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
mfs, err := reg.Deliver()
mfs, err := reg.Gather()
if err != nil {
if opts.ErrorLog != nil {
opts.ErrorLog.Println("error collecting metrics:", err)

View File

@ -44,9 +44,9 @@ import (
const contentTypeHeader = "Content-Type"
// Registry triggers a metric collection by the provided Deliverer (which is
// 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 delivered metrics to the Pushgateway specified by url, using
// 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
@ -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.Deliverer) error {
func Registry(job string, grouping map[string]string, url string, reg prometheus.Gatherer) error {
return push(job, grouping, url, reg, "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.Deliverer) error {
func RegistryAdd(job string, grouping map[string]string, url string, reg prometheus.Gatherer) error {
return push(job, grouping, url, reg, "POST")
}
func push(job string, grouping map[string]string, pushURL string, reg prometheus.Deliverer, method string) error {
func push(job string, grouping map[string]string, pushURL string, reg prometheus.Gatherer, method string) error {
if !strings.Contains(pushURL, "://") {
pushURL = "http://" + 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.Deliver()
mfs, err := reg.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 Deliverer. Instead, it
// 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
// 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 Deliverer.
// AddCollectors works like RegistryAdd, 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 {

View File

@ -83,7 +83,7 @@ func TestPush(t *testing.T) {
reg.MustRegister(metric1)
reg.MustRegister(metric2)
mfs, err := reg.Deliver()
mfs, err := reg.Gather()
if err != nil {
t.Fatal(err)
}

View File

@ -33,7 +33,7 @@ const (
)
// DefaultRegistry is a Registry instance that has a ProcessCollector and a
// GoCollector pre-registered. DefaultRegisterer and DefaultDeliverer are both
// GoCollector pre-registered. DefaultRegisterer and DefaultGatherer are both
// pointing to it. A number of convenience functions in this package act on
// them. This approach to keep a default instance as global state mirrors the
// approach of other packages in the Go standard library. Note that there are
@ -43,7 +43,7 @@ const (
var (
DefaultRegistry = NewRegistry()
DefaultRegisterer Registerer = DefaultRegistry
DefaultDeliverer Deliverer = DefaultRegistry
DefaultGatherer Gatherer = DefaultRegistry
)
func init() {
@ -115,24 +115,23 @@ type Registerer interface {
Unregister(Collector) bool
}
// Deliverer is the interface for the part of a registry in charge of delivering
// the collected metrics, wich the same general implication as described for the
// Registerer interface.
type Deliverer interface {
// Deliver collects metrics from registered Collectors and returns them
// as lexicographically sorted MetricFamily protobufs. Even if an error
// occurs, Deliver attempts to collect as many metrics as
// possible. Hence, if a non-nil error is returned, the returned
// MetricFamily slice could be nil (in case of a fatal error that
// prevented any meaningful metric collection) or contain a number of
// MetricFamily protobufs, some of which might be incomplete, and some
// might be missing altogether. The returned error (which might be a
// multierror.Error) explains the details. In any case, the MetricFamily
// protobufs are consistent and valid for Prometheus to ingest (e.g. no
// duplicate metrics, no invalid identifiers). In scenarios where
// complete collection is critical, the returned MetricFamily protobufs
// should be disregarded if the returned error is non-nil.
Deliver() ([]*dto.MetricFamily, error)
// Gatherer is the interface for the part of a registry in charge of gathering
// the collected metrics into a number of MetricFamilies. The Gatherer interface
// comes with the same general implication as described for the Registerer
// interface.
type Gatherer interface {
// Gather calls the Collect method of the registered Collectors and then
// gathers the collected metrics into a lexicographically sorted slice
// of MetricFamily protobufs. Even if an error occurs, Gather attempts
// to gather as many metrics as possible. Hence, if a non-nil error is
// returned, the returned MetricFamily slice could be nil (in case of a
// fatal error that prevented any meaningful metric collection) or
// contain a number of MetricFamily protobufs, some of which might be
// incomplete, and some might be missing altogether. The returned error
// (which might be a MultiError) explains the details. In scenarios
// where complete collection is critical, the returned MetricFamily
// protobufs should be disregarded if the returned error is non-nil.
Gather() ([]*dto.MetricFamily, error)
}
// Register registers the provided Collector with the DefaultRegisterer.
@ -221,10 +220,10 @@ func (err AlreadyRegisteredError) Error() string {
return "duplicate metrics collector registration attempted"
}
// Registry registers Prometheus collectors, collects their metrics, and
// delivers them for exposition. It implements Registerer and Deliverer. The
// zero value is not usable. Use NewRegistry or NewPedanticRegistry to create
// instances.
// Registry registers Prometheus collectors, collects their metrics, and gathers
// them into MetricFamilies for exposition. It implements Registerer and
// Gatherer. The zero value is not usable. Create instances with NewRegistry or
// NewPedanticRegistry.
type Registry struct {
mtx sync.RWMutex
collectorsByID map[uint64]Collector // ID is a hash of the descIDs.
@ -361,8 +360,8 @@ func (r *Registry) MustRegister(cs ...Collector) {
}
}
// Deliver implements Deliverer.
func (r *Registry) Deliver() ([]*dto.MetricFamily, error) {
// Gather implements Gatherer.
func (r *Registry) Gather() ([]*dto.MetricFamily, error) {
var (
metricChan = make(chan Metric, capMetricChan)
metricHashes = map[uint64]struct{}{}