collectors

Documentation

Overview

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

Index

• Variables
• 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 ...func(o *internal.GoCollectorOptions)) prometheus.Collector
• func NewProcessCollector(opts ProcessCollectorOpts) prometheus.Collector
• func WithGoCollections(flags GoCollectionOption) func(options *internal.GoCollectorOptions)
• func WithGoCollectorMemStatsMetricsDisabled() func(options *internal.GoCollectorOptions)
• func WithGoCollectorRuntimeMetrics(rules ...GoRuntimeMetricsRule) func(options *internal.GoCollectorOptions)
• func WithoutGoCollectorRuntimeMetrics(matchers ...*regexp.Regexp) func(options *internal.GoCollectorOptions)
• type GoCollectionOption
• type GoRuntimeMetricsRule
• type ProcessCollectorOpts

Variables

var (
	// MetricsAll allows all the metrics to be collected from Go runtime.
	MetricsAll = GoRuntimeMetricsRule{regexp.MustCompile("/.*")}
	// MetricsGC allows only GC metrics to be collected from Go runtime.
	// e.g. go_gc_cycles_automatic_gc_cycles_total
	// NOTE: This does not include new class of "/cpu/classes/gc/..." metrics.
	// Use custom metric rule to access those.
	MetricsGC = GoRuntimeMetricsRule{regexp.MustCompile(`^/gc/.*`)}
	// MetricsMemory allows only memory metrics to be collected from Go runtime.
	// e.g. go_memory_classes_heap_free_bytes
	MetricsMemory = GoRuntimeMetricsRule{regexp.MustCompile(`^/memory/.*`)}
	// MetricsScheduler allows only scheduler metrics to be collected from Go runtime.
	// e.g. go_sched_goroutines_goroutines
	MetricsScheduler = GoRuntimeMetricsRule{regexp.MustCompile(`^/sched/.*`)}
	// MetricsDebug allows only debug metrics to be collected from Go runtime.
	// e.g. go_godebug_non_default_behavior_gocachetest_events_total
	MetricsDebug = GoRuntimeMetricsRule{regexp.MustCompile(`^/godebug/.*`)}
)

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 prototyping, 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 ...func(o *internal.GoCollectorOptions)) prometheus.Collector

NewGoCollector returns a collector that exports metrics about the current Go process using debug.GCStats (base metrics) and runtime/metrics (both in MemStats style and new ones).

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) func(options *internal.GoCollectorOptions)

WithGoCollections allows enabling different collections for Go collector on top of base metrics.

Deprecated: Use WithGoCollectorRuntimeMetrics() and WithGoCollectorMemStatsMetricsDisabled() instead to control metrics.

func WithGoCollectorMemStatsMetricsDisabled

func WithGoCollectorMemStatsMetricsDisabled() func(options *internal.GoCollectorOptions)

WithGoCollectorMemStatsMetricsDisabled disables metrics that is gathered in 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,

NOTE(bwplotka): The above represents runtime.MemStats statistics, but they are actually implemented using new runtime/metrics package. (except skipped go_memstats_gc_cpu_fraction -- see https://github.com/prometheus/client_golang/issues/842#issuecomment-861812034 for explanation).

Some users might want to disable this on collector level (although you can use scrape relabelling on Prometheus), because similar metrics can be now obtained using WithGoCollectorRuntimeMetrics. Note that the semantics of new metrics might be different, plus the names can be change over time with different Go version.

NOTE(bwplotka): Changing metric names can be tedious at times as the alerts, recording rules and dashboards have to be adjusted. The old metrics are also very useful, with many guides and books written about how to interpret them.

As a result our recommendation would be to stick with MemStats like metrics and enable other runtime/metrics if you are interested in advanced insights Go provides. See ExampleGoCollector_WithAdvancedGoMetrics.

func WithGoCollectorRuntimeMetrics

func WithGoCollectorRuntimeMetrics(rules ...GoRuntimeMetricsRule) func(options *internal.GoCollectorOptions)

WithGoCollectorRuntimeMetrics allows enabling and configuring particular group of runtime/metrics. See the list of metrics https://golang.bg/src/runtime/metrics/description.go (pick the Go version you use there!). You can use this option in repeated manner, which will add new rules. The order of rules is important, the last rule that matches particular metrics is applied.

func WithoutGoCollectorRuntimeMetrics

func WithoutGoCollectorRuntimeMetrics(matchers ...*regexp.Regexp) func(options *internal.GoCollectorOptions)

WithoutGoCollectorRuntimeMetrics allows disabling group of runtime/metrics that you might have added in WithGoCollectorRuntimeMetrics. It behaves similarly to WithGoCollectorRuntimeMetrics just with deny-list semantics.

Types

type GoCollectionOption

type GoCollectionOption uint32

GoCollectionOption represents Go collection option flag. Deprecated.

const (
	// GoRuntimeMemStatsCollection represents the metrics represented by runtime.MemStats structure.
	//
	// Deprecated: Use WithGoCollectorMemStatsMetricsDisabled() function to disable those metrics in the collector.
	GoRuntimeMemStatsCollection GoCollectionOption = 1 << iota
	// GoRuntimeMetricsCollection is the new set of metrics represented by runtime/metrics package.
	//
	// Deprecated: Use WithGoCollectorRuntimeMetrics(GoRuntimeMetricsRule{Matcher: regexp.MustCompile("/.*")})
	// function to enable those metrics in the collector.
	GoRuntimeMetricsCollection
)

type GoRuntimeMetricsRule

type GoRuntimeMetricsRule struct {
	// Matcher represents RE2 expression will match the runtime/metrics from https://golang.bg/src/runtime/metrics/description.go
	// Use `regexp.MustCompile` or `regexp.Compile` to create this field.
	Matcher *regexp.Regexp
}

GoRuntimeMetricsRule allow enabling and configuring particular group of runtime/metrics. TODO(bwplotka): Consider adding ability to adjust buckets.

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.