Skip to content

Commit b89620c

Browse files
beorn7beorn7
authored
Merge pull request #862 from johejo/new_collector_package
Add new collectors package
2 parents 3998a67 + e07445a commit b89620c

7 files changed

+210
-86
lines changed

‎prometheus/collectors/collectors.go

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
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+
14+
// Package collectors provides implementations of prometheus.Collector to
15+
// conveniently collect process and Go-related metrics.
16+
package collectors

‎prometheus/collectors/expvar_collector.go

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
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+
14+
package collectors
15+
16+
import "github.com/prometheus/client_golang/prometheus"
17+
18+
// NewExpvarCollector returns a newly allocated expvar Collector.
19+
//
20+
// An expvar Collector collects metrics from the expvar interface. It provides a
21+
// quick way to expose numeric values that are already exported via expvar as
22+
// Prometheus metrics. Note that the data models of expvar and Prometheus are
23+
// fundamentally different, and that the expvar Collector is inherently slower
24+
// than native Prometheus metrics. Thus, the expvar Collector is probably great
25+
// for experiments and prototying, but you should seriously consider a more
26+
// direct implementation of Prometheus metrics for monitoring production
27+
// systems.
28+
//
29+
// The exports map has the following meaning:
30+
//
31+
// The keys in the map correspond to expvar keys, i.e. for every expvar key you
32+
// want to export as Prometheus metric, you need an entry in the exports
33+
// map. The descriptor mapped to each key describes how to export the expvar
34+
// value. It defines the name and the help string of the Prometheus metric
35+
// proxying the expvar value. The type will always be Untyped.
36+
//
37+
// For descriptors without variable labels, the expvar value must be a number or
38+
// a bool. The number is then directly exported as the Prometheus sample
39+
// value. (For a bool, 'false' translates to 0 and 'true' to 1). Expvar values
40+
// that are not numbers or bools are silently ignored.
41+
//
42+
// If the descriptor has one variable label, the expvar value must be an expvar
43+
// map. The keys in the expvar map become the various values of the one
44+
// Prometheus label. The values in the expvar map must be numbers or bools again
45+
// as above.
46+
//
47+
// For descriptors with more than one variable label, the expvar must be a
48+
// nested expvar map, i.e. where the values of the topmost map are maps again
49+
// etc. until a depth is reached that corresponds to the number of labels. The
50+
// leaves of that structure must be numbers or bools as above to serve as the
51+
// sample values.
52+
//
53+
// Anything that does not fit into the scheme above is silently ignored.
54+
func NewExpvarCollector(exports map[string]*prometheus.Desc) prometheus.Collector {
55+
//nolint:staticcheck // Ignore SA1019 until v2.
56+
return prometheus.NewExpvarCollector(exports)
57+
}

‎prometheus/collectors/go_collector.go

+69
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
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+
14+
package collectors
15+
16+
import "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.
44+
func 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.
66+
func NewBuildInfoCollector() prometheus.Collector {
67+
//nolint:staticcheck // Ignore SA1019 until v2.
68+
return prometheus.NewBuildInfoCollector()
69+
}

‎prometheus/collectors/process_collector.go

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
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+
14+
package collectors
15+
16+
import "github.com/prometheus/client_golang/prometheus"
17+
18+
// ProcessCollectorOpts defines the behavior of a process metrics collector
19+
// created with NewProcessCollector.
20+
type ProcessCollectorOpts struct {
21+
// PidFn returns the PID of the process the collector collects metrics
22+
// for. It is called upon each collection. By default, the PID of the
23+
// current process is used, as determined on construction time by
24+
// calling os.Getpid().
25+
PidFn func() (int, error)
26+
// If non-empty, each of the collected metrics is prefixed by the
27+
// provided string and an underscore ("_").
28+
Namespace string
29+
// If true, any error encountered during collection is reported as an
30+
// invalid metric (see NewInvalidMetric). Otherwise, errors are ignored
31+
// and the collected metrics will be incomplete. (Possibly, no metrics
32+
// will be collected at all.) While that's usually not desired, it is
33+
// appropriate for the common "mix-in" of process metrics, where process
34+
// metrics are nice to have, but failing to collect them should not
35+
// disrupt the collection of the remaining metrics.
36+
ReportErrors bool
37+
}
38+
39+
// NewProcessCollector returns a collector which exports the current state of
40+
// process metrics including CPU, memory and file descriptor usage as well as
41+
// the process start time. The detailed behavior is defined by the provided
42+
// ProcessCollectorOpts. The zero value of ProcessCollectorOpts creates a
43+
// collector for the current process with an empty namespace string and no error
44+
// reporting.
45+
//
46+
// The collector only works on operating systems with a Linux-style proc
47+
// filesystem and on Microsoft Windows. On other operating systems, it will not
48+
// collect any metrics.
49+
func NewProcessCollector(opts ProcessCollectorOpts) prometheus.Collector {
50+
//nolint:staticcheck // Ignore SA1019 until v2.
51+
return prometheus.NewProcessCollector(prometheus.ProcessCollectorOpts{
52+
PidFn: opts.PidFn,
53+
Namespace: opts.Namespace,
54+
ReportErrors: opts.ReportErrors,
55+
})
56+
}

‎prometheus/expvar_collector.go

+3-36
Original file line numberDiff line numberDiff line change
@@ -22,43 +22,10 @@ type expvarCollector struct {
2222
exports map[string]*Desc
2323
}
2424

25-
// NewExpvarCollector returns a newly allocated expvar Collector that still has
26-
// to be registered with a Prometheus registry.
25+
// NewExpvarCollector is the obsolete version of collectors.NewExpvarCollector.
26+
// See there for documentation.
2727
//
28-
// An expvar Collector collects metrics from the expvar interface. It provides a
29-
// quick way to expose numeric values that are already exported via expvar as
30-
// Prometheus metrics. Note that the data models of expvar and Prometheus are
31-
// fundamentally different, and that the expvar Collector is inherently slower
32-
// than native Prometheus metrics. Thus, the expvar Collector is probably great
33-
// for experiments and prototying, but you should seriously consider a more
34-
// direct implementation of Prometheus metrics for monitoring production
35-
// systems.
36-
//
37-
// The exports map has the following meaning:
38-
//
39-
// The keys in the map correspond to expvar keys, i.e. for every expvar key you
40-
// want to export as Prometheus metric, you need an entry in the exports
41-
// map. The descriptor mapped to each key describes how to export the expvar
42-
// value. It defines the name and the help string of the Prometheus metric
43-
// proxying the expvar value. The type will always be Untyped.
44-
//
45-
// For descriptors without variable labels, the expvar value must be a number or
46-
// a bool. The number is then directly exported as the Prometheus sample
47-
// value. (For a bool, 'false' translates to 0 and 'true' to 1). Expvar values
48-
// that are not numbers or bools are silently ignored.
49-
//
50-
// If the descriptor has one variable label, the expvar value must be an expvar
51-
// map. The keys in the expvar map become the various values of the one
52-
// Prometheus label. The values in the expvar map must be numbers or bools again
53-
// as above.
54-
//
55-
// For descriptors with more than one variable label, the expvar must be a
56-
// nested expvar map, i.e. where the values of the topmost map are maps again
57-
// etc. until a depth is reached that corresponds to the number of labels. The
58-
// leaves of that structure must be numbers or bools as above to serve as the
59-
// sample values.
60-
//
61-
// Anything that does not fit into the scheme above is silently ignored.
28+
// Deprecated: Use collectors.NewExpvarCollector instead.
6229
func NewExpvarCollector(exports map[string]*Desc) Collector {
6330
return &expvarCollector{
6431
exports: exports,

‎prometheus/go_collector.go

+6-41
Original file line numberDiff line numberDiff line change
@@ -36,32 +36,10 @@ type goCollector struct {
3636
msMaxAge time.Duration // Maximum allowed age of old memstats.
3737
}
3838

39-
// NewGoCollector returns a collector that exports metrics about the current Go
40-
// process. This includes memory stats. To collect those, runtime.ReadMemStats
41-
// is called. This requires to “stop the world”, which usually only happens for
42-
// garbage collection (GC). Take the following implications into account when
43-
// deciding whether to use the Go collector:
39+
// NewGoCollector is the obsolete version of collectors.NewGoCollector.
40+
// See there for documentation.
4441
//
45-
// 1. The performance impact of stopping the world is the more relevant the more
46-
// frequently metrics are collected. However, with Go1.9 or later the
47-
// stop-the-world time per metrics collection is very short (~25µs) so that the
48-
// performance impact will only matter in rare cases. However, with older Go
49-
// versions, the stop-the-world duration depends on the heap size and can be
50-
// quite significant (~1.7 ms/GiB as per
51-
// https://go-review.googlesource.com/c/go/+/34937).
52-
//
53-
// 2. During an ongoing GC, nothing else can stop the world. Therefore, if the
54-
// metrics collection happens to coincide with GC, it will only complete after
55-
// GC has finished. Usually, GC is fast enough to not cause problems. However,
56-
// with a very large heap, GC might take multiple seconds, which is enough to
57-
// cause scrape timeouts in common setups. To avoid this problem, the Go
58-
// collector will use the memstats from a previous collection if
59-
// runtime.ReadMemStats takes more than 1s. However, if there are no previously
60-
// collected memstats, or their collection is more than 5m ago, the collection
61-
// will block until runtime.ReadMemStats succeeds.
62-
//
63-
// NOTE: The problem is solved in Go 1.15, see
64-
// https://github.com/golang/go/issues/19812 for the related Go issue.
42+
// Deprecated: Use collectors.NewGoCollector instead.
6543
func NewGoCollector() Collector {
6644
return &goCollector{
6745
goroutinesDesc: NewDesc(
@@ -366,23 +344,10 @@ type memStatsMetrics []struct {
366344
valType ValueType
367345
}
368346

369-
// NewBuildInfoCollector returns a collector collecting a single metric
370-
// "go_build_info" with the constant value 1 and three labels "path", "version",
371-
// and "checksum". Their label values contain the main module path, version, and
372-
// checksum, respectively. The labels will only have meaningful values if the
373-
// binary is built with Go module support and from source code retrieved from
374-
// the source repository (rather than the local file system). This is usually
375-
// accomplished by building from outside of GOPATH, specifying the full address
376-
// of the main package, e.g. "GO111MODULE=on go run
377-
// github.com/prometheus/client_golang/examples/random". If built without Go
378-
// module support, all label values will be "unknown". If built with Go module
379-
// support but using the source code from the local file system, the "path" will
380-
// be set appropriately, but "checksum" will be empty and "version" will be
381-
// "(devel)".
347+
// NewBuildInfoCollector is the obsolete version of collectors.NewBuildInfoCollector.
348+
// See there for documentation.
382349
//
383-
// This collector uses only the build information for the main module. See
384-
// https://github.com/povilasv/prommod for an example of a collector for the
385-
// module dependencies.
350+
// Deprecated: Use collectors.NewBuildInfoCollector instead.
386351
func NewBuildInfoCollector() Collector {
387352
path, version, sum := "unknown", "unknown", "unknown"
388353
if bi, ok := debug.ReadBuildInfo(); ok {

‎prometheus/process_collector.go

+3-9
Original file line numberDiff line numberDiff line change
@@ -54,16 +54,10 @@ type ProcessCollectorOpts struct {
5454
ReportErrors bool
5555
}
5656

57-
// NewProcessCollector returns a collector which exports the current state of
58-
// process metrics including CPU, memory and file descriptor usage as well as
59-
// the process start time. The detailed behavior is defined by the provided
60-
// ProcessCollectorOpts. The zero value of ProcessCollectorOpts creates a
61-
// collector for the current process with an empty namespace string and no error
62-
// reporting.
57+
// NewProcessCollector is the obsolete version of collectors.NewProcessCollector.
58+
// See there for documentation.
6359
//
64-
// The collector only works on operating systems with a Linux-style proc
65-
// filesystem and on Microsoft Windows. On other operating systems, it will not
66-
// collect any metrics.
60+
// Deprecated: Use collectors.NewProcessCollector instead.
6761
func NewProcessCollector(opts ProcessCollectorOpts) Collector {
6862
ns := ""
6963
if len(opts.Namespace) > 0 {

0 commit comments

Comments
 (0)