From d66ac8f8631d7420f87303fed341f464c66919b3 Mon Sep 17 00:00:00 2001 From: beorn7 Date: Sat, 19 May 2018 21:14:04 +0200 Subject: [PATCH] Document the stop-the-world implications of the Go collector Signed-off-by: beorn7 --- prometheus/go_collector.go | 8 ++++++-- prometheus/registry.go | 13 +++++++------ 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/prometheus/go_collector.go b/prometheus/go_collector.go index 122b169..0440bd1 100644 --- a/prometheus/go_collector.go +++ b/prometheus/go_collector.go @@ -17,8 +17,12 @@ type goCollector struct { metrics memStatsMetrics } -// NewGoCollector returns a collector which exports metrics about the current -// go process. +// NewGoCollector returns a collector which exports metrics about the current Go +// 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( diff --git a/prometheus/registry.go b/prometheus/registry.go index f8efd1f..1f9adb8 100644 --- a/prometheus/registry.go +++ b/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 -// keep default instances as global state mirrors the approach of other packages -// in the Go standard library. Note that there are caveats. Change the variables -// with caution and only if you understand the consequences. Users who want to -// avoid global state altogether should not use the convenience functions and -// act on custom instances instead. +// and a Go collector (see NewGoCollector, in particular the note about +// stop-the-world implication with Go versions older than 1.9) already +// registered. This approach to keep default instances as global state mirrors +// the approach of other packages in the Go standard library. Note that there +// are caveats. Change the variables with caution and only if you understand the +// 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