new handler instrumentation (#285)

Add new HTTP handler instrumentation

prometheus/histogram.go

@@ -308,23 +308,23 @@ func NewHistogramVec(opts HistogramOpts, labelNames []string) *HistogramVec {
 }
 
 // GetMetricWithLabelValues replaces the method of the same name in
-// MetricVec. The difference is that this method returns a Histogram and not a
+// MetricVec. The difference is that this method returns an Observer and not a
-// Metric so that no type conversion is required.
+// Metric so that no type conversion to an Observer is required.
-func (m *HistogramVec) GetMetricWithLabelValues(lvs ...string) (Histogram, error) {
+func (m *HistogramVec) GetMetricWithLabelValues(lvs ...string) (Observer, error) {
 	metric, err := m.MetricVec.GetMetricWithLabelValues(lvs...)
 	if metric != nil {
-		return metric.(Histogram), err
+		return metric.(Observer), err
 	}
 	return nil, err
 }
 
 // GetMetricWith replaces the method of the same name in MetricVec. The
-// difference is that this method returns a Histogram and not a Metric so that no
+// difference is that this method returns an Observer and not a Metric so that no
-// type conversion is required.
+// type conversion to an Observer is required.
-func (m *HistogramVec) GetMetricWith(labels Labels) (Histogram, error) {
+func (m *HistogramVec) GetMetricWith(labels Labels) (Observer, error) {
 	metric, err := m.MetricVec.GetMetricWith(labels)
 	if metric != nil {
-		return metric.(Histogram), err
+		return metric.(Observer), err
 	}
 	return nil, err
 }
@@ -333,15 +333,15 @@ func (m *HistogramVec) GetMetricWith(labels Labels) (Histogram, error) {
 // GetMetricWithLabelValues would have returned an error. By not returning an
 // error, WithLabelValues allows shortcuts like
 //     myVec.WithLabelValues("404", "GET").Observe(42.21)
-func (m *HistogramVec) WithLabelValues(lvs ...string) Histogram {
+func (m *HistogramVec) WithLabelValues(lvs ...string) Observer {
-	return m.MetricVec.WithLabelValues(lvs...).(Histogram)
+	return m.MetricVec.WithLabelValues(lvs...).(Observer)
 }
 
 // With works as GetMetricWith, but panics where GetMetricWithLabels would have
 // returned an error. By not returning an error, With allows shortcuts like
 //     myVec.With(Labels{"code": "404", "method": "GET"}).Observe(42.21)
-func (m *HistogramVec) With(labels Labels) Histogram {
+func (m *HistogramVec) With(labels Labels) Observer {
-	return m.MetricVec.With(labels).(Histogram)
+	return m.MetricVec.With(labels).(Observer)
 }
 
 type constHistogram struct {

prometheus/histogram_test.go

@@ -286,7 +286,7 @@ func TestHistogramVecConcurrency(t *testing.T) {
 		for i := 0; i < vecLength; i++ {
 			m := &dto.Metric{}
 			s := his.WithLabelValues(string('A' + i))
-			s.Write(m)
+			s.(Histogram).Write(m)
 
 			if got, want := len(m.Histogram.Bucket), len(testBuckets)-1; got != want {
 				t.Errorf("got %d buckets in protobuf, want %d", got, want)

prometheus/observer.go

@@ -0,0 +1,50 @@
+// Copyright 2017 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
+
+// Observer is the interface that wraps the Observe method, which is used by
+// Histogram and Summary to add observations.
+type Observer interface {
+	Observe(float64)
+}
+
+// The ObserverFunc type is an adapter to allow the use of ordinary
+// functions as Observers. If f is a function with the appropriate
+// signature, ObserverFunc(f) is an Observer that calls f.
+//
+// This adapter is usually used in connection with the Timer type, and there are
+// two general use cases:
+//
+// The most common one is to use a Gauge as the Observer for a Timer.
+// See the "Gauge" Timer example.
+//
+// The more advanced use case is to create a function that dynamically decides
+// which Observer to use for observing the duration. See the "Complex" Timer
+// example.
+type ObserverFunc func(float64)
+
+// Observe calls f(value). It implements Observer.
+func (f ObserverFunc) Observe(value float64) {
+	f(value)
+}
+
+// ObserverVec is an interface implemented by `HistogramVec` and `SummaryVec`.
+type ObserverVec interface {
+	GetMetricWith(Labels) (Observer, error)
+	GetMetricWithLabelValues(lvs ...string) (Observer, error)
+	With(Labels) Observer
+	WithLabelValues(...string) Observer
+
+	Collector
+}

prometheus/promhttp/delegator_1_7.go

@@ -0,0 +1,35 @@
+// Copyright 2017 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.
+
+// +build !go1.8
+
+package promhttp
+
+import (
+	"io"
+	"net/http"
+)
+
+func newDelegator(w http.ResponseWriter) delegator {
+	d := &responseWriterDelegator{ResponseWriter: w}
+
+	_, cn := w.(http.CloseNotifier)
+	_, fl := w.(http.Flusher)
+	_, hj := w.(http.Hijacker)
+	_, rf := w.(io.ReaderFrom)
+	if cn && fl && hj && rf {
+		return &fancyDelegator{d}
+	}
+
+	return d
+}

prometheus/promhttp/delegator_1_8.go

@@ -0,0 +1,70 @@
+// Copyright 2017 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.
+
+// +build go1.8
+
+package promhttp
+
+import (
+	"io"
+	"net/http"
+)
+
+// newDelegator handles the four different methods of upgrading a
+// http.ResponseWriter to delegator.
+func newDelegator(w http.ResponseWriter) delegator {
+	d := &responseWriterDelegator{ResponseWriter: w}
+
+	_, cn := w.(http.CloseNotifier)
+	_, fl := w.(http.Flusher)
+	_, hj := w.(http.Hijacker)
+	_, ps := w.(http.Pusher)
+	_, rf := w.(io.ReaderFrom)
+
+	// Check for the four most common combination of interfaces a
+	// http.ResponseWriter might implement.
+	switch {
+	case cn && fl && hj && rf && ps:
+		// All interfaces.
+		return &fancyPushDelegator{
+			fancyDelegator: &fancyDelegator{d},
+			p:              &pushDelegator{d},
+		}
+	case cn && fl && hj && rf:
+		// All interfaces, except http.Pusher.
+		return &fancyDelegator{d}
+	case ps:
+		// Just http.Pusher.
+		return &pushDelegator{d}
+	}
+
+	return d
+}
+
+type fancyPushDelegator struct {
+	p *pushDelegator
+
+	*fancyDelegator
+}
+
+func (f *fancyPushDelegator) Push(target string, opts *http.PushOptions) error {
+	return f.p.Push(target, opts)
+}
+
+type pushDelegator struct {
+	*responseWriterDelegator
+}
+
+func (f *pushDelegator) Push(target string, opts *http.PushOptions) error {
+	return f.ResponseWriter.(http.Pusher).Push(target, opts)
+}

prometheus/promhttp/http.go

@@ -11,21 +11,19 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Copyright (c) 2013, The Prometheus Authors
+// Package promhttp provides tooling around HTTP servers and clients.
-// All rights reserved.
 //
-// Use of this source code is governed by a BSD-style license that can be found
+// First, the package allows the creation of http.Handler instances to expose
-// in the LICENSE file.
+// Prometheus metrics via HTTP. promhttp.Handler acts on the
-
+// prometheus.DefaultGatherer. With HandlerFor, you can create a handler for a
-// Package promhttp contains functions to create http.Handler instances to
+// custom registry or anything that implements the Gatherer interface. It also
-// expose Prometheus metrics via HTTP. In later versions of this package, it
+// allows the creation of handlers that act differently on errors or allow to
-// will also contain tooling to instrument instances of http.Handler and
+// log errors.
-// http.RoundTripper.
 //
-// promhttp.Handler acts on the prometheus.DefaultGatherer. With HandlerFor,
+// Second, the package provides tooling to instrument instances of http.Handler
-// you can create a handler for a custom registry or anything that implements
+// via middleware. Middleware wrappers follow the naming scheme
-// the Gatherer interface. It also allows to create handlers that act
+// InstrumentHandlerX, where X describes the intended use of the middleware.
-// differently on errors or allow to log errors.
+// See each function's doc comment for specific details.
 package promhttp
 
 import (

prometheus/promhttp/http_test.go

@@ -11,12 +11,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Copyright (c) 2013, The Prometheus Authors
-// All rights reserved.
-//
-// Use of this source code is governed by a BSD-style license that can be found
-// in the LICENSE file.
-
 package promhttp
 
 import (

prometheus/promhttp/instrument_server.go

@@ -0,0 +1,461 @@
+// Copyright 2017 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 promhttp
+
+import (
+	"bufio"
+	"io"
+	"net"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	dto "github.com/prometheus/client_model/go"
+
+	"github.com/prometheus/client_golang/prometheus"
+)
+
+// InstrumentHandlerInFlight is a middleware that wraps the provided
+// http.Handler. It sets the provided prometheus.Gauge to the number of
+// requests currently handled by the wrapped http.Handler.
+//
+// See the example for InstrumentHandlerDuration for example usage.
+func InstrumentHandlerInFlight(g prometheus.Gauge, next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		g.Inc()
+		defer g.Dec()
+		next.ServeHTTP(w, r)
+	})
+}
+
+// InstrumentHandlerDuration is a middleware that wraps the provided
+// http.Handler to observe the request duration with the provided ObserverVec.
+// The ObserverVec must have zero, one, or two labels. The only allowed label
+// names are "code" and "method". The function panics if any other instance
+// labels are provided. The Observe method of the Observer in the ObserverVec
+// is called with the request duration in seconds. Partitioning happens by HTTP
+// status code and/or HTTP method if the respective instance label names are
+// present in the ObserverVec. For unpartitioned observations, use an
+// ObserverVec with zero labels. Note that partitioning of Histograms is
+// expensive and should be used judiciously.
+//
+// If the wrapped Handler does not set a status code, a status code of 200 is assumed.
+//
+// If the wrapped Handler panics, no values are reported.
+func InstrumentHandlerDuration(obs prometheus.ObserverVec, next http.Handler) http.HandlerFunc {
+	code, method := checkLabels(obs)
+
+	if code {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			now := time.Now()
+			d := newDelegator(w)
+			next.ServeHTTP(d, r)
+
+			obs.With(labels(code, method, r.Method, d.Status())).Observe(time.Since(now).Seconds())
+		})
+	}
+
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		now := time.Now()
+		next.ServeHTTP(w, r)
+		obs.With(labels(code, method, r.Method, 0)).Observe(time.Since(now).Seconds())
+	})
+}
+
+// InstrumentHandlerCounter is a middleware that wraps the provided
+// http.Handler to observe the request result with the provided CounterVec.
+// The CounterVec must have zero, one, or two labels. The only allowed label
+// names are "code" and "method". The function panics if any other instance
+// labels are provided. Partitioning of the CounterVec happens by HTTP status
+// code and/or HTTP method if the respective instance label names are present
+// in the CounterVec. For unpartitioned observations, use a CounterVec with
+// zero labels.
+//
+// If the wrapped Handler does not set a status code, a status code of 200 is assumed.
+//
+// If the wrapped Handler panics, the Counter is not incremented.
+//
+// See the example for InstrumentHandlerDuration for example usage.
+func InstrumentHandlerCounter(counter *prometheus.CounterVec, next http.Handler) http.HandlerFunc {
+	code, method := checkLabels(counter)
+
+	if code {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			d := newDelegator(w)
+			next.ServeHTTP(d, r)
+			counter.With(labels(code, method, r.Method, d.Status())).Inc()
+		})
+	}
+
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		next.ServeHTTP(w, r)
+		counter.With(labels(code, method, r.Method, 0)).Inc()
+	})
+}
+
+// InstrumentHandlerRequestSize is a middleware that wraps the provided
+// http.Handler to observe the request size with the provided ObserverVec.
+// The ObserverVec must have zero, one, or two labels. The only allowed label
+// names are "code" and "method". The function panics if any other instance
+// labels are provided. The Observe method of the Observer in the ObserverVec
+// is called with the request size in bytes. Partitioning happens by HTTP
+// status code and/or HTTP method if the respective instance label names are
+// present in the ObserverVec. For unpartitioned observations, use an
+// ObserverVec with zero labels. Note that partitioning of Histograms is
+// expensive and should be used judiciously.
+//
+// If the wrapped Handler does not set a status code, a status code of 200 is assumed.
+//
+// If the wrapped Handler panics, no values are reported.
+//
+// See the example for InstrumentHandlerDuration for example usage.
+func InstrumentHandlerRequestSize(obs prometheus.ObserverVec, next http.Handler) http.HandlerFunc {
+	code, method := checkLabels(obs)
+
+	if code {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			d := newDelegator(w)
+			next.ServeHTTP(d, r)
+			size := computeApproximateRequestSize(r)
+			obs.With(labels(code, method, r.Method, d.Status())).Observe(float64(size))
+		})
+	}
+
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		next.ServeHTTP(w, r)
+		size := computeApproximateRequestSize(r)
+		obs.With(labels(code, method, r.Method, 0)).Observe(float64(size))
+	})
+}
+
+// InstrumentHandlerResponseSize is a middleware that wraps the provided
+// http.Handler to observe the response size with the provided ObserverVec.
+// The ObserverVec must have zero, one, or two labels. The only allowed label
+// names are "code" and "method". The function panics if any other instance
+// labels are provided. The Observe method of the Observer in the ObserverVec
+// is called with the response size in bytes. Partitioning happens by HTTP
+// status code and/or HTTP method if the respective instance label names are
+// present in the ObserverVec. For unpartitioned observations, use an
+// ObserverVec with zero labels. Note that partitioning of Histograms is
+// expensive and should be used judiciously.
+//
+// If the wrapped Handler does not set a status code, a status code of 200 is assumed.
+//
+// If the wrapped Handler panics, no values are reported.
+//
+// See the example for InstrumentHandlerDuration for example usage.
+func InstrumentHandlerResponseSize(obs prometheus.ObserverVec, next http.Handler) http.Handler {
+	code, method := checkLabels(obs)
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		d := newDelegator(w)
+		next.ServeHTTP(d, r)
+		obs.With(labels(code, method, r.Method, d.Status())).Observe(float64(d.Written()))
+	})
+}
+
+func checkLabels(c prometheus.Collector) (code bool, method bool) {
+	// TODO(beorn7): Remove this hacky way to check for instance labels
+	// once Descriptors can have their dimensionality queried.
+	var (
+		desc *prometheus.Desc
+		pm   dto.Metric
+	)
+
+	descc := make(chan *prometheus.Desc, 1)
+	c.Describe(descc)
+
+	select {
+	case desc = <-descc:
+	default:
+		panic("no description provided by collector")
+	}
+	select {
+	case <-descc:
+		panic("more than one description provided by collector")
+	default:
+	}
+
+	close(descc)
+
+	if _, err := prometheus.NewConstMetric(desc, prometheus.UntypedValue, 0); err == nil {
+		return
+	} else if m, err := prometheus.NewConstMetric(desc, prometheus.UntypedValue, 0, ""); err == nil {
+		if err := m.Write(&pm); err != nil {
+			panic("error checking metric for labels")
+		}
+
+		name := *pm.Label[0].Name
+		if name == "code" {
+			code = true
+		} else if name == "method" {
+			method = true
+		} else {
+			panic("metric partitioned with non-supported labels")
+		}
+		return
+	} else if m, err := prometheus.NewConstMetric(desc, prometheus.UntypedValue, 0, "", ""); err == nil {
+		if err := m.Write(&pm); err != nil {
+			panic("error checking metric for labels")
+		}
+
+		for _, label := range pm.Label {
+			if *label.Name == "code" || *label.Name == "method" {
+				continue
+			}
+			panic("metric partitioned with non-supported labels")
+		}
+
+		code = true
+		method = true
+		return
+	}
+
+	panic("metric partitioned with non-supported labels")
+}
+
+// emptyLabels is a one-time allocation for non-partitioned metrics to avoid
+// unnecessary allocations on each request.
+var emptyLabels = prometheus.Labels{}
+
+func labels(code, method bool, reqMethod string, status int) prometheus.Labels {
+	if !(code || method) {
+		return emptyLabels
+	}
+	labels := prometheus.Labels{}
+
+	if code {
+		labels["code"] = sanitizeCode(status)
+	}
+	if method {
+		labels["method"] = sanitizeMethod(reqMethod)
+	}
+
+	return labels
+}
+
+func computeApproximateRequestSize(r *http.Request) int {
+	s := 0
+	if r.URL != nil {
+		s += len(r.URL.String())
+	}
+
+	s += len(r.Method)
+	s += len(r.Proto)
+	for name, values := range r.Header {
+		s += len(name)
+		for _, value := range values {
+			s += len(value)
+		}
+	}
+	s += len(r.Host)
+
+	// N.B. r.Form and r.MultipartForm are assumed to be included in r.URL.
+
+	if r.ContentLength != -1 {
+		s += int(r.ContentLength)
+	}
+	return s
+}
+
+func sanitizeMethod(m string) string {
+	switch m {
+	case "GET", "get":
+		return "get"
+	case "PUT", "put":
+		return "put"
+	case "HEAD", "head":
+		return "head"
+	case "POST", "post":
+		return "post"
+	case "DELETE", "delete":
+		return "delete"
+	case "CONNECT", "connect":
+		return "connect"
+	case "OPTIONS", "options":
+		return "options"
+	case "NOTIFY", "notify":
+		return "notify"
+	default:
+		return strings.ToLower(m)
+	}
+}
+
+// If the wrapped http.Handler has not set a status code, i.e. the value is
+// currently 0, santizeCode will return 200, for consistency with behavior in
+// the stdlib.
+func sanitizeCode(s int) string {
+	switch s {
+	case 100:
+		return "100"
+	case 101:
+		return "101"
+
+	case 200, 0:
+		return "200"
+	case 201:
+		return "201"
+	case 202:
+		return "202"
+	case 203:
+		return "203"
+	case 204:
+		return "204"
+	case 205:
+		return "205"
+	case 206:
+		return "206"
+
+	case 300:
+		return "300"
+	case 301:
+		return "301"
+	case 302:
+		return "302"
+	case 304:
+		return "304"
+	case 305:
+		return "305"
+	case 307:
+		return "307"
+
+	case 400:
+		return "400"
+	case 401:
+		return "401"
+	case 402:
+		return "402"
+	case 403:
+		return "403"
+	case 404:
+		return "404"
+	case 405:
+		return "405"
+	case 406:
+		return "406"
+	case 407:
+		return "407"
+	case 408:
+		return "408"
+	case 409:
+		return "409"
+	case 410:
+		return "410"
+	case 411:
+		return "411"
+	case 412:
+		return "412"
+	case 413:
+		return "413"
+	case 414:
+		return "414"
+	case 415:
+		return "415"
+	case 416:
+		return "416"
+	case 417:
+		return "417"
+	case 418:
+		return "418"
+
+	case 500:
+		return "500"
+	case 501:
+		return "501"
+	case 502:
+		return "502"
+	case 503:
+		return "503"
+	case 504:
+		return "504"
+	case 505:
+		return "505"
+
+	case 428:
+		return "428"
+	case 429:
+		return "429"
+	case 431:
+		return "431"
+	case 511:
+		return "511"
+
+	default:
+		return strconv.Itoa(s)
+	}
+}
+
+type delegator interface {
+	Status() int
+	Written() int64
+
+	http.ResponseWriter
+}
+
+type responseWriterDelegator struct {
+	http.ResponseWriter
+
+	handler, method string
+	status          int
+	written         int64
+	wroteHeader     bool
+}
+
+func (r *responseWriterDelegator) Status() int {
+	return r.status
+}
+
+func (r *responseWriterDelegator) Written() int64 {
+	return r.written
+}
+
+func (r *responseWriterDelegator) WriteHeader(code int) {
+	r.status = code
+	r.wroteHeader = true
+	r.ResponseWriter.WriteHeader(code)
+}
+
+func (r *responseWriterDelegator) Write(b []byte) (int, error) {
+	if !r.wroteHeader {
+		r.WriteHeader(http.StatusOK)
+	}
+	n, err := r.ResponseWriter.Write(b)
+	r.written += int64(n)
+	return n, err
+}
+
+type fancyDelegator struct {
+	*responseWriterDelegator
+}
+
+func (r *fancyDelegator) CloseNotify() <-chan bool {
+	return r.ResponseWriter.(http.CloseNotifier).CloseNotify()
+}
+
+func (r *fancyDelegator) Hijack() (net.Conn, *bufio.ReadWriter, error) {
+	return r.ResponseWriter.(http.Hijacker).Hijack()
+}
+
+func (r *fancyDelegator) Flush() {
+	r.ResponseWriter.(http.Flusher).Flush()
+}
+
+func (r *fancyDelegator) ReadFrom(re io.Reader) (int64, error) {
+	if !r.wroteHeader {
+		r.WriteHeader(http.StatusOK)
+	}
+	n, err := r.ResponseWriter.(io.ReaderFrom).ReadFrom(re)
+	r.written += n
+	return n, err
+}

prometheus/promhttp/instrument_server_test.go

@@ -0,0 +1,165 @@
+// Copyright 2017 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 promhttp
+
+import (
+	"log"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/prometheus/client_golang/prometheus"
+)
+
+func TestMiddlewareAPI(t *testing.T) {
+	inFlightGauge := prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "in_flight_requests",
+		Help: "A gauge of requests currently being served by the wrapped handler.",
+	})
+
+	counter := prometheus.NewCounterVec(
+		prometheus.CounterOpts{
+			Name: "api_requests_total",
+			Help: "A counter for requests to the wrapped handler.",
+		},
+		[]string{"code", "method"},
+	)
+
+	histVec := prometheus.NewHistogramVec(
+		prometheus.HistogramOpts{
+			Name:    "response_duration_seconds",
+			Help:    "A histogram of request latencies.",
+			Buckets: prometheus.DefBuckets,
+		},
+		[]string{"method"},
+	)
+
+	responseSize := prometheus.NewHistogramVec(
+		prometheus.HistogramOpts{
+			Name:    "push_request_size_bytes",
+			Help:    "A histogram of request sizes for requests.",
+			Buckets: []float64{200, 500, 900, 1500},
+		},
+		[]string{},
+	)
+
+	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte("OK"))
+	})
+
+	prometheus.MustRegister(inFlightGauge, counter, histVec, responseSize)
+
+	chain := InstrumentHandlerInFlight(inFlightGauge,
+		InstrumentHandlerCounter(counter,
+			InstrumentHandlerDuration(histVec,
+				InstrumentHandlerResponseSize(responseSize, handler),
+			),
+		),
+	)
+
+	r, _ := http.NewRequest("GET", "www.example.com", nil)
+	w := httptest.NewRecorder()
+	chain.ServeHTTP(w, r)
+}
+
+func ExampleInstrumentHandlerDuration() {
+	inFlightGauge := prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "in_flight_requests",
+		Help: "A gauge of requests currently being served by the wrapped handler.",
+	})
+
+	counter := prometheus.NewCounterVec(
+		prometheus.CounterOpts{
+			Name: "api_requests_total",
+			Help: "A counter for requests to the wrapped handler.",
+		},
+		[]string{"code", "method"},
+	)
+
+	// pushVec is partitioned by the HTTP method and uses custom buckets based on
+	// the expected request duration. It uses ConstLabels to set a handler label
+	// marking pushVec as tracking the durations for pushes.
+	pushVec := prometheus.NewHistogramVec(
+		prometheus.HistogramOpts{
+			Name:        "request_duration_seconds",
+			Help:        "A histogram of latencies for requests to the push handler.",
+			Buckets:     []float64{.25, .5, 1, 2.5, 5, 10},
+			ConstLabels: prometheus.Labels{"handler": "push"},
+		},
+		[]string{"method"},
+	)
+
+	// pullVec is also partitioned by the HTTP method but uses custom buckets
+	// different from those for pushVec. It also has a different value for the
+	// constant "handler" label.
+	pullVec := prometheus.NewHistogramVec(
+		prometheus.HistogramOpts{
+			Name:        "request_duration_seconds",
+			Help:        "A histogram of latencies for requests to the pull handler.",
+			Buckets:     []float64{.005, .01, .025, .05},
+			ConstLabels: prometheus.Labels{"handler": "pull"},
+		},
+		[]string{"method"},
+	)
+
+	// responseSize has no labels, making it a zero-dimensional
+	// ObserverVec.
+	responseSize := prometheus.NewHistogramVec(
+		prometheus.HistogramOpts{
+			Name:    "response_size_bytes",
+			Help:    "A histogram of response sizes for requests.",
+			Buckets: []float64{200, 500, 900, 1500},
+		},
+		[]string{},
+	)
+
+	// Create the handlers that will be wrapped by the middleware.
+	pushHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte("Push"))
+	})
+	pullHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte("Pull"))
+	})
+
+	// Register all of the metrics in the standard registry.
+	prometheus.MustRegister(inFlightGauge, counter, pullVec, pushVec, responseSize)
+
+	// Wrap the pushHandler with our shared middleware, but use the
+	// endpoint-specific pushVec with InstrumentHandlerDuration.
+	pushChain := InstrumentHandlerInFlight(inFlightGauge,
+		InstrumentHandlerCounter(counter,
+			InstrumentHandlerDuration(pushVec,
+				InstrumentHandlerResponseSize(responseSize, pushHandler),
+			),
+		),
+	)
+
+	// Wrap the pushHandler with the shared middleware, but use the
+	// endpoint-specific pullVec with InstrumentHandlerDuration.
+	pullChain := InstrumentHandlerInFlight(inFlightGauge,
+		InstrumentHandlerCounter(counter,
+			InstrumentHandlerDuration(pullVec,
+				InstrumentHandlerResponseSize(responseSize, pullHandler),
+			),
+		),
+	)
+
+	http.Handle("/metrics", Handler())
+	http.Handle("/push", pushChain)
+	http.Handle("/pull", pullChain)
+
+	if err := http.ListenAndServe(":3000", nil); err != nil {
+		log.Fatal(err)
+	}
+}

prometheus/summary.go

@@ -419,24 +419,24 @@ func NewSummaryVec(opts SummaryOpts, labelNames []string) *SummaryVec {
 	}
 }
 
-// GetMetricWithLabelValues replaces the method of the same name in
+// GetMetricWithLabelValues replaces the method of the same name in MetricVec.
-// MetricVec. The difference is that this method returns a Summary and not a
+// The difference is that this method returns an Observer and not a Metric so
-// Metric so that no type conversion is required.
+// that no type conversion to an Observer is required.
-func (m *SummaryVec) GetMetricWithLabelValues(lvs ...string) (Summary, error) {
+func (m *SummaryVec) GetMetricWithLabelValues(lvs ...string) (Observer, error) {
 	metric, err := m.MetricVec.GetMetricWithLabelValues(lvs...)
 	if metric != nil {
-		return metric.(Summary), err
+		return metric.(Observer), err
 	}
 	return nil, err
 }
 
 // GetMetricWith replaces the method of the same name in MetricVec. The
-// difference is that this method returns a Summary and not a Metric so that no
+// difference is that this method returns an Observer and not a Metric so that
-// type conversion is required.
+// no type conversion to an Observer is required.
-func (m *SummaryVec) GetMetricWith(labels Labels) (Summary, error) {
+func (m *SummaryVec) GetMetricWith(labels Labels) (Observer, error) {
 	metric, err := m.MetricVec.GetMetricWith(labels)
 	if metric != nil {
-		return metric.(Summary), err
+		return metric.(Observer), err
 	}
 	return nil, err
 }
@@ -445,15 +445,15 @@ func (m *SummaryVec) GetMetricWith(labels Labels) (Summary, error) {
 // GetMetricWithLabelValues would have returned an error. By not returning an
 // error, WithLabelValues allows shortcuts like
 //     myVec.WithLabelValues("404", "GET").Observe(42.21)
-func (m *SummaryVec) WithLabelValues(lvs ...string) Summary {
+func (m *SummaryVec) WithLabelValues(lvs ...string) Observer {
-	return m.MetricVec.WithLabelValues(lvs...).(Summary)
+	return m.MetricVec.WithLabelValues(lvs...).(Observer)
 }
 
 // With works as GetMetricWith, but panics where GetMetricWithLabels would have
 // returned an error. By not returning an error, With allows shortcuts like
 //     myVec.With(Labels{"code": "404", "method": "GET"}).Observe(42.21)
-func (m *SummaryVec) With(labels Labels) Summary {
+func (m *SummaryVec) With(labels Labels) Observer {
-	return m.MetricVec.With(labels).(Summary)
+	return m.MetricVec.With(labels).(Observer)
 }
 
 type constSummary struct {

prometheus/summary_test.go

@@ -301,7 +301,7 @@ func TestSummaryVecConcurrency(t *testing.T) {
 		for i := 0; i < vecLength; i++ {
 			m := &dto.Metric{}
 			s := sum.WithLabelValues(string('A' + i))
-			s.Write(m)
+			s.(Summary).Write(m)
 			if got, want := int(*m.Summary.SampleCount), len(allVars[i]); got != want {
 				t.Errorf("got sample count %d for label %c, want %d", got, 'A'+i, want)
 			}

prometheus/timer.go

@@ -15,32 +15,6 @@ package prometheus
 
 import "time"
 
-// Observer is the interface that wraps the Observe method, which is used by
-// Histogram and Summary to add observations.
-type Observer interface {
-	Observe(float64)
-}
-
-// The ObserverFunc type is an adapter to allow the use of ordinary
-// functions as Observers. If f is a function with the appropriate
-// signature, ObserverFunc(f) is an Observer that calls f.
-//
-// This adapter is usually used in connection with the Timer type, and there are
-// two general use cases:
-//
-// The most common one is to use a Gauge as the Observer for a Timer.
-// See the "Gauge" Timer example.
-//
-// The more advanced use case is to create a function that dynamically decides
-// which Observer to use for observing the duration. See the "Complex" Timer
-// example.
-type ObserverFunc func(float64)
-
-// Observe calls f(value). It implements Observer.
-func (f ObserverFunc) Observe(value float64) {
-	f(value)
-}
-
 // Timer is a helper type to time functions. Use NewTimer to create new
 // instances.
 type Timer struct {

prometheus/timer_test.go

@@ -115,36 +115,36 @@ func TestTimerByOutcome(t *testing.T) {
 	}
 
 	timedFunc()
-	his.WithLabelValues("foo").Write(m)
+	his.WithLabelValues("foo").(Histogram).Write(m)
 	if want, got := uint64(0), m.GetHistogram().GetSampleCount(); want != got {
 		t.Errorf("want %d observations for 'foo' histogram, got %d", want, got)
 	}
 	m.Reset()
-	his.WithLabelValues("bar").Write(m)
+	his.WithLabelValues("bar").(Histogram).Write(m)
 	if want, got := uint64(1), m.GetHistogram().GetSampleCount(); want != got {
 		t.Errorf("want %d observations for 'bar' histogram, got %d", want, got)
 	}
 
 	timedFunc()
 	m.Reset()
-	his.WithLabelValues("foo").Write(m)
+	his.WithLabelValues("foo").(Histogram).Write(m)
 	if want, got := uint64(1), m.GetHistogram().GetSampleCount(); want != got {
 		t.Errorf("want %d observations for 'foo' histogram, got %d", want, got)
 	}
 	m.Reset()
-	his.WithLabelValues("bar").Write(m)
+	his.WithLabelValues("bar").(Histogram).Write(m)
 	if want, got := uint64(1), m.GetHistogram().GetSampleCount(); want != got {
 		t.Errorf("want %d observations for 'bar' histogram, got %d", want, got)
 	}
 
 	timedFunc()
 	m.Reset()
-	his.WithLabelValues("foo").Write(m)
+	his.WithLabelValues("foo").(Histogram).Write(m)
 	if want, got := uint64(1), m.GetHistogram().GetSampleCount(); want != got {
 		t.Errorf("want %d observations for 'foo' histogram, got %d", want, got)
 	}
 	m.Reset()
-	his.WithLabelValues("bar").Write(m)
+	his.WithLabelValues("bar").(Histogram).Write(m)
 	if want, got := uint64(2), m.GetHistogram().GetSampleCount(); want != got {
 		t.Errorf("want %d observations for 'bar' histogram, got %d", want, got)
 	}