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

Signed-off-by: beorn7 <beorn@soundcloud.com>
This commit is contained in:
beorn7 2018-05-19 21:14:04 +02:00
parent 46db556846
commit d66ac8f863
2 changed files with 13 additions and 8 deletions

View File

@ -17,8 +17,12 @@ type goCollector struct {
metrics memStatsMetrics 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 { func NewGoCollector() Collector {
return &goCollector{ return &goCollector{
goroutinesDesc: NewDesc( goroutinesDesc: NewDesc(

View File

@ -38,12 +38,13 @@ const (
// Registerer and Gatherer interface a number of convenience functions in this // Registerer and Gatherer interface a number of convenience functions in this
// package act on. Initially, both variables point to the same Registry, which // package act on. Initially, both variables point to the same Registry, which
// has a process collector (currently on Linux only, see NewProcessCollector) // 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 ( var (
defaultRegistry = NewRegistry() defaultRegistry = NewRegistry()
DefaultRegisterer Registerer = defaultRegistry DefaultRegisterer Registerer = defaultRegistry