collectors

Documentation

Overview

Package collectors provides implementations of prometheus.Collector to conveniently collect process and Go-related metrics.

Index

• func NewBuildInfoCollector() prometheus.Collector
• func NewDBStatsCollector(db *sql.DB, dbName string) prometheus.Collector
• func NewExpvarCollector(exports map[string]*prometheus.Desc) prometheus.Collector
• func NewGoCollector() prometheus.Collector
• func NewProcessCollector(opts ProcessCollectorOpts) prometheus.Collector
• type ProcessCollectorOpts

Functions

func NewBuildInfoCollector

func NewBuildInfoCollector() prometheus.Collector

NewBuildInfoCollector returns a collector collecting a single metric "go_build_info" with the constant value 1 and three labels "path", "version", and "checksum". Their label values contain the main module path, version, and checksum, respectively. The labels will only have meaningful values if the binary is built with Go module support and from source code retrieved from the source repository (rather than the local file system). This is usually accomplished by building from outside of GOPATH, specifying the full address of the main package, e.g. "GO111MODULE=on go run github.com/prometheus/client_golang/examples/random". If built without Go module support, all label values will be "unknown". If built with Go module support but using the source code from the local file system, the "path" will be set appropriately, but "checksum" will be empty and "version" will be "(devel)".

This collector uses only the build information for the main module. See https://github.com/povilasv/prommod for an example of a collector for the module dependencies.

func NewDBStatsCollector

func NewDBStatsCollector(db *sql.DB, dbName string) prometheus.Collector

NewDBStatsCollector returns a collector that exports metrics about the given *sql.DB. See https://golang.org/pkg/database/sql/#DBStats for more information on stats.

func NewExpvarCollector

func NewExpvarCollector(exports map[string]*prometheus.Desc) prometheus.Collector

NewExpvarCollector returns a newly allocated expvar Collector.

An expvar Collector collects metrics from the expvar interface. It provides a quick way to expose numeric values that are already exported via expvar as Prometheus metrics. Note that the data models of expvar and Prometheus are fundamentally different, and that the expvar Collector is inherently slower than native Prometheus metrics. Thus, the expvar Collector is probably great for experiments and prototying, but you should seriously consider a more direct implementation of Prometheus metrics for monitoring production systems.

The exports map has the following meaning:

The keys in the map correspond to expvar keys, i.e. for every expvar key you want to export as Prometheus metric, you need an entry in the exports map. The descriptor mapped to each key describes how to export the expvar value. It defines the name and the help string of the Prometheus metric proxying the expvar value. The type will always be Untyped.

For descriptors without variable labels, the expvar value must be a number or a bool. The number is then directly exported as the Prometheus sample value. (For a bool, 'false' translates to 0 and 'true' to 1). Expvar values that are not numbers or bools are silently ignored.

If the descriptor has one variable label, the expvar value must be an expvar map. The keys in the expvar map become the various values of the one Prometheus label. The values in the expvar map must be numbers or bools again as above.

For descriptors with more than one variable label, the expvar must be a nested expvar map, i.e. where the values of the topmost map are maps again etc. until a depth is reached that corresponds to the number of labels. The leaves of that structure must be numbers or bools as above to serve as the sample values.

Anything that does not fit into the scheme above is silently ignored.

func NewGoCollector

func NewGoCollector() prometheus.Collector

NewGoCollector returns a collector that exports metrics about the current Go process. This includes memory stats. To collect those, runtime.ReadMemStats is called. This requires to “stop the world”, which usually only happens for garbage collection (GC). Take the following implications into account when deciding whether to use the Go collector:

1. The performance impact of stopping the world is the more relevant the more frequently metrics are collected. However, with Go1.9 or later the stop-the-world time per metrics collection is very short (~25µs) so that the performance impact will only matter in rare cases. 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).

2. During an ongoing GC, nothing else can stop the world. Therefore, if the metrics collection happens to coincide with GC, it will only complete after GC has finished. Usually, GC is fast enough to not cause problems. However, with a very large heap, GC might take multiple seconds, which is enough to cause scrape timeouts in common setups. To avoid this problem, the Go collector will use the memstats from a previous collection if runtime.ReadMemStats takes more than 1s. However, if there are no previously collected memstats, or their collection is more than 5m ago, the collection will block until runtime.ReadMemStats succeeds.

NOTE: The problem is solved in Go 1.15, see https://github.com/golang/go/issues/19812 for the related Go issue.

func NewProcessCollector

func NewProcessCollector(opts ProcessCollectorOpts) prometheus.Collector

NewProcessCollector returns a collector which exports the current state of process metrics including CPU, memory and file descriptor usage as well as the process start time. The detailed behavior is defined by the provided ProcessCollectorOpts. The zero value of ProcessCollectorOpts creates a collector for the current process with an empty namespace string and no error reporting.

The collector only works on operating systems with a Linux-style proc filesystem and on Microsoft Windows. On other operating systems, it will not collect any metrics.

Types

type ProcessCollectorOpts

type ProcessCollectorOpts struct {
	// PidFn returns the PID of the process the collector collects metrics
	// for. It is called upon each collection. By default, the PID of the
	// current process is used, as determined on construction time by
	// calling os.Getpid().
	PidFn func() (int, error)
	// If non-empty, each of the collected metrics is prefixed by the
	// provided string and an underscore ("_").
	Namespace string
	// If true, any error encountered during collection is reported as an
	// invalid metric (see NewInvalidMetric). Otherwise, errors are ignored
	// and the collected metrics will be incomplete. (Possibly, no metrics
	// will be collected at all.) While that's usually not desired, it is
	// appropriate for the common "mix-in" of process metrics, where process
	// metrics are nice to have, but failing to collect them should not
	// disrupt the collection of the remaining metrics.
	ReportErrors bool
}

ProcessCollectorOpts defines the behavior of a process metrics collector created with NewProcessCollector.