1// Copyright 2021 The Prometheus Authors 2// Licensed under the Apache License, Version 2.0 (the "License"); 3// you may not use this file except in compliance with the License. 4// You may obtain a copy of the License at 5// 6// http://www.apache.org/licenses/LICENSE-2.0 7// 8// Unless required by applicable law or agreed to in writing, software 9// distributed under the License is distributed on an "AS IS" BASIS, 10// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 11// See the License for the specific language governing permissions and 12// limitations under the License. 13 14package collectors 15 16import "github.com/prometheus/client_golang/prometheus" 17 18// NewGoCollector returns a collector that exports metrics about the current Go 19// process. This includes memory stats. To collect those, runtime.ReadMemStats 20// is called. This requires to “stop the world”, which usually only happens for 21// garbage collection (GC). Take the following implications into account when 22// deciding whether to use the Go collector: 23// 24// 1. The performance impact of stopping the world is the more relevant the more 25// frequently metrics are collected. However, with Go1.9 or later the 26// stop-the-world time per metrics collection is very short (~25µs) so that the 27// performance impact will only matter in rare cases. However, with older Go 28// versions, the stop-the-world duration depends on the heap size and can be 29// quite significant (~1.7 ms/GiB as per 30// https://go-review.googlesource.com/c/go/+/34937). 31// 32// 2. During an ongoing GC, nothing else can stop the world. Therefore, if the 33// metrics collection happens to coincide with GC, it will only complete after 34// GC has finished. Usually, GC is fast enough to not cause problems. However, 35// with a very large heap, GC might take multiple seconds, which is enough to 36// cause scrape timeouts in common setups. To avoid this problem, the Go 37// collector will use the memstats from a previous collection if 38// runtime.ReadMemStats takes more than 1s. However, if there are no previously 39// collected memstats, or their collection is more than 5m ago, the collection 40// will block until runtime.ReadMemStats succeeds. 41// 42// NOTE: The problem is solved in Go 1.15, see 43// https://github.com/golang/go/issues/19812 for the related Go issue. 44func NewGoCollector() prometheus.Collector { 45 //nolint:staticcheck // Ignore SA1019 until v2. 46 return prometheus.NewGoCollector() 47} 48 49// NewBuildInfoCollector returns a collector collecting a single metric 50// "go_build_info" with the constant value 1 and three labels "path", "version", 51// and "checksum". Their label values contain the main module path, version, and 52// checksum, respectively. The labels will only have meaningful values if the 53// binary is built with Go module support and from source code retrieved from 54// the source repository (rather than the local file system). This is usually 55// accomplished by building from outside of GOPATH, specifying the full address 56// of the main package, e.g. "GO111MODULE=on go run 57// github.com/prometheus/client_golang/examples/random". If built without Go 58// module support, all label values will be "unknown". If built with Go module 59// support but using the source code from the local file system, the "path" will 60// be set appropriately, but "checksum" will be empty and "version" will be 61// "(devel)". 62// 63// This collector uses only the build information for the main module. See 64// https://github.com/povilasv/prommod for an example of a collector for the 65// module dependencies. 66func NewBuildInfoCollector() prometheus.Collector { 67 //nolint:staticcheck // Ignore SA1019 until v2. 68 return prometheus.NewBuildInfoCollector() 69} 70