Merge pull request #201 from prometheus/beorn7/doc

Document the issues of InstrumentHandler

prometheus/http.go

@@ -57,12 +57,31 @@ func nowSeries(t ...time.Time) nower {
 // has a constant label named "handler" with the provided handlerName as
 // value. http_requests_total is a metric vector partitioned by HTTP method
 // (label name "method") and HTTP status code (label name "code").
+//
+// Note that InstrumentHandler has several issues:
+//
+// - It uses Summaries rather than Histograms. Summaries are not useful if
+//   aggregation accross multiple instances is required.
+//
+// - It uses microseconds as unit, which is deprecated and should be reploced by
+//   seconds.
+//
+// - The size of the request is calculated in a separate goroutine. Since this
+//   calculatior requires access to the request header, it creates a race with
+//   any writes to the header performed during request handling.
+//   httputil.ReverseProxy is a prominent example for a handler
+//   performing such writes.
+//
+// Upcoming versions of this package will provide ways of instrumenting HTTP
+// handlers that are more flexible and have fewer issues. Consider this function
+// DEPRECATED and prefer direct instrumentation in the meantime.
 func InstrumentHandler(handlerName string, handler http.Handler) http.HandlerFunc {
 	return InstrumentHandlerFunc(handlerName, handler.ServeHTTP)
 }
 
 // InstrumentHandlerFunc wraps the given function for instrumentation. It
-// otherwise works in the same way as InstrumentHandler.
+// otherwise works in the same way as InstrumentHandler (and shares the same
+// issues).
 func InstrumentHandlerFunc(handlerName string, handlerFunc func(http.ResponseWriter, *http.Request)) http.HandlerFunc {
 	return InstrumentHandlerFuncWithOpts(
 		SummaryOpts{
@@ -73,13 +92,13 @@ func InstrumentHandlerFunc(handlerName string, handlerFunc func(http.ResponseWri
 	)
 }
 
-// InstrumentHandlerWithOpts works like InstrumentHandler but provides more
+// InstrumentHandlerWithOpts works like InstrumentHandler (and shares the same
-// flexibility (at the cost of a more complex call syntax). As
+// issues) but provides more flexibility (at the cost of a more complex call
-// InstrumentHandler, this function registers four metric collectors, but it
+// syntax). As InstrumentHandler, this function registers four metric
-// uses the provided SummaryOpts to create them. However, the fields "Name" and
+// collectors, but it uses the provided SummaryOpts to create them. However, the
-// "Help" in the SummaryOpts are ignored. "Name" is replaced by
+// fields "Name" and "Help" in the SummaryOpts are ignored. "Name" is replaced
-// "requests_total", "request_duration_microseconds", "request_size_bytes", and
+// by "requests_total", "request_duration_microseconds", "request_size_bytes",
-// "response_size_bytes", respectively. "Help" is replaced by an appropriate
+// and "response_size_bytes", respectively. "Help" is replaced by an appropriate
 // help string. The names of the variable labels of the http_requests_total
 // CounterVec are "method" (get, post, etc.), and "code" (HTTP status code).
 //
@@ -102,9 +121,10 @@ func InstrumentHandlerWithOpts(opts SummaryOpts, handler http.Handler) http.Hand
 	return InstrumentHandlerFuncWithOpts(opts, handler.ServeHTTP)
 }
 
-// InstrumentHandlerFuncWithOpts works like InstrumentHandlerFunc but provides
+// InstrumentHandlerFuncWithOpts works like InstrumentHandlerFunc (and shares
-// more flexibility (at the cost of a more complex call syntax). See
+// the same issues) but provides more flexibility (at the cost of a more complex
-// InstrumentHandlerWithOpts for details how the provided SummaryOpts are used.
+// call syntax). See InstrumentHandlerWithOpts for details how the provided
+// SummaryOpts are used.
 func InstrumentHandlerFuncWithOpts(opts SummaryOpts, handlerFunc func(http.ResponseWriter, *http.Request)) http.HandlerFunc {
 	reqCnt := NewCounterVec(
 		CounterOpts{

prometheus/registry.go

@@ -84,6 +84,9 @@ const (
 // Handler returns the HTTP handler for the global Prometheus registry. It is
 // already instrumented with InstrumentHandler (using "prometheus" as handler
 // name). Usually the handler is used to handle the "/metrics" endpoint.
+//
+// Please note the issues described in the doc comment of InstrumentHandler. You
+// might want to consider using UninstrumentedHandler instead.
 func Handler() http.Handler {
 	return InstrumentHandler("prometheus", defRegistry)
 }