Document the stop-the-world implications of the Go collector

Signed-off-by: beorn7 <beorn@soundcloud.com>

prometheus/go_collector.go

@@ -17,8 +17,12 @@ type goCollector struct {
 	metrics memStatsMetrics
 }
 
-// NewGoCollector returns a collector which exports metrics about the current
+// NewGoCollector returns a collector which exports metrics about the current Go
-// go process.
+// process. This includes memory stats. To collect those, runtime.ReadMemStats
+// is called. This causes a stop-the-world, which is very short with Go1.9+
+// (~25µs). However, with older Go versions, the stop-the-world duration depends
+// on the heap size and can be quite significant (~1.7 ms/GiB as per
+// https://go-review.googlesource.com/c/go/+/34937).
 func NewGoCollector() Collector {
 	return &goCollector{
 		goroutinesDesc: NewDesc(

prometheus/registry.go

@@ -38,12 +38,13 @@ const (
 // Registerer and Gatherer interface a number of convenience functions in this
 // package act on. Initially, both variables point to the same Registry, which
 // has a process collector (currently on Linux only, see NewProcessCollector)
-// and a Go collector (see NewGoCollector) already registered. This approach to
+// and a Go collector (see NewGoCollector, in particular the note about
-// keep default instances as global state mirrors the approach of other packages
+// stop-the-world implication with Go versions older than 1.9) already
-// in the Go standard library. Note that there are caveats. Change the variables
+// registered. This approach to keep default instances as global state mirrors
-// with caution and only if you understand the consequences. Users who want to
+// the approach of other packages in the Go standard library. Note that there
-// avoid global state altogether should not use the convenience functions and
+// are caveats. Change the variables with caution and only if you understand the
-// act on custom instances instead.
+// consequences. Users who want to avoid global state altogether should not use
+// the convenience functions and act on custom instances instead.
 var (
 	defaultRegistry              = NewRegistry()
 	DefaultRegisterer Registerer = defaultRegistry