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(opts ...goOption) prometheus.Collector
• func NewProcessCollector(opts ProcessCollectorOpts) prometheus.Collector
• func WithGoCollections(flags GoCollectionOption) goOption
• type GoCollectionOption
• 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(opts ...goOption) prometheus.Collector

NewGoCollector returns a collector that exports metrics about the current Go process using debug.GCStats using runtime/metrics.

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.

func WithGoCollections

func WithGoCollections(flags GoCollectionOption) goOption

WithGoCollections allows enabling different collections for Go collector on top of base metrics like go_goroutines, go_threads, go_gc_duration_seconds, go_memstats_last_gc_time_seconds, go_info.

Check GoRuntimeMemStatsCollection and GoRuntimeMetricsCollection for more details. You can use none, one or more collections at once. For example: WithGoCollections(GoRuntimeMemStatsCollection | GoRuntimeMetricsCollection) means both GoRuntimeMemStatsCollection metrics and GoRuntimeMetricsCollection will be exposed.

The current default is GoRuntimeMemStatsCollection, so the compatibility mode with client_golang pre v1.12 (move to runtime/metrics).

Types

type GoCollectionOption

type GoCollectionOption uint32

const (
	// GoRuntimeMemStatsCollection represents the metrics represented by runtime.MemStats structure such as
	// go_memstats_alloc_bytes
	// go_memstats_alloc_bytes_total
	// go_memstats_sys_bytes
	// go_memstats_lookups_total
	// go_memstats_mallocs_total
	// go_memstats_frees_total
	// go_memstats_heap_alloc_bytes
	// go_memstats_heap_sys_bytes
	// go_memstats_heap_idle_bytes
	// go_memstats_heap_inuse_bytes
	// go_memstats_heap_released_bytes
	// go_memstats_heap_objects
	// go_memstats_stack_inuse_bytes
	// go_memstats_stack_sys_bytes
	// go_memstats_mspan_inuse_bytes
	// go_memstats_mspan_sys_bytes
	// go_memstats_mcache_inuse_bytes
	// go_memstats_mcache_sys_bytes
	// go_memstats_buck_hash_sys_bytes
	// go_memstats_gc_sys_bytes
	// go_memstats_other_sys_bytes
	// go_memstats_next_gc_bytes
	// so the metrics known from pre client_golang v1.12.0, except skipped go_memstats_gc_cpu_fraction (see
	// https://github.com/prometheus/client_golang/issues/842#issuecomment-861812034 for explanation.
	//
	// NOTE that this mode represents runtime.MemStats statistics, but they are
	// actually implemented using new runtime/metrics package.
	// Deprecated: Use GoRuntimeMetricsCollection instead going forward.
	GoRuntimeMemStatsCollection GoCollectionOption = 1 << iota
	// GoRuntimeMetricsCollection is the new set of metrics represented by runtime/metrics package and follows
	// consistent naming. The exposed metric set depends on Go version, but it is controlled against
	// unexpected cardinality. This set has overlapping information with GoRuntimeMemStatsCollection, just with
	// new names. GoRuntimeMetricsCollection is what is recommended for using going forward.
	GoRuntimeMetricsCollection
)

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.