From 87f94343516647b02cab4a5a47f34b1983ffa7dc Mon Sep 17 00:00:00 2001 From: beorn7 Date: Thu, 13 Feb 2020 20:52:44 +0100 Subject: [PATCH 1/3] Remove obsolete references to `Untyped` from doc comments Signed-off-by: beorn7 --- prometheus/doc.go | 37 ++++++++++++++++++------------------- prometheus/value.go | 3 ++- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/prometheus/doc.go b/prometheus/doc.go index 01977de66..98450125d 100644 --- a/prometheus/doc.go +++ b/prometheus/doc.go @@ -84,25 +84,21 @@ // of those four metric types can be found in the Prometheus docs: // https://prometheus.io/docs/concepts/metric_types/ // -// A fifth "type" of metric is Untyped. It behaves like a Gauge, but signals the -// Prometheus server not to assume anything about its type. -// -// In addition to the fundamental metric types Gauge, Counter, Summary, -// Histogram, and Untyped, a very important part of the Prometheus data model is -// the partitioning of samples along dimensions called labels, which results in +// In addition to the fundamental metric types Gauge, Counter, Summary, and +// Histogram, a very important part of the Prometheus data model is the +// partitioning of samples along dimensions called labels, which results in // metric vectors. The fundamental types are GaugeVec, CounterVec, SummaryVec, -// HistogramVec, and UntypedVec. +// and HistogramVec. // // While only the fundamental metric types implement the Metric interface, both // the metrics and their vector versions implement the Collector interface. A // Collector manages the collection of a number of Metrics, but for convenience, -// a Metric can also “collect itself”. Note that Gauge, Counter, Summary, -// Histogram, and Untyped are interfaces themselves while GaugeVec, CounterVec, -// SummaryVec, HistogramVec, and UntypedVec are not. +// a Metric can also “collect itself”. Note that Gauge, Counter, Summary, and +// Histogram are interfaces themselves while GaugeVec, CounterVec, SummaryVec, +// and HistogramVec are not. // // To create instances of Metrics and their vector versions, you need a suitable -// …Opts struct, i.e. GaugeOpts, CounterOpts, SummaryOpts, HistogramOpts, or -// UntypedOpts. +// …Opts struct, i.e. GaugeOpts, CounterOpts, SummaryOpts, or HistogramOpts. // // Custom Collectors and constant Metrics // @@ -118,13 +114,16 @@ // existing numbers into Prometheus Metrics during collection. An own // implementation of the Collector interface is perfect for that. You can create // Metric instances “on the fly” using NewConstMetric, NewConstHistogram, and -// NewConstSummary (and their respective Must… versions). That will happen in -// the Collect method. The Describe method has to return separate Desc -// instances, representative of the “throw-away” metrics to be created later. -// NewDesc comes in handy to create those Desc instances. Alternatively, you -// could return no Desc at all, which will mark the Collector “unchecked”. No -// checks are performed at registration time, but metric consistency will still -// be ensured at scrape time, i.e. any inconsistencies will lead to scrape +// NewConstSummary (and their respective Must… versions). NewConstMetric is used +// for all metric types with just a float64 as their value: Counter, Gauge, and +// a special “type” called Untyped. Use the latter if you are not sure if the +// mirrored metric is a Counter or a Gauge. Creation of the Metric instance +// happens in the Collect method. The Describe method has to return separate +// Desc instances, representative of the “throw-away” metrics to be created +// later. NewDesc comes in handy to create those Desc instances. Alternatively, +// you could return no Desc at all, which will mark the Collector “unchecked”. +// No checks are performed at registration time, but metric consistency will +// still be ensured at scrape time, i.e. any inconsistencies will lead to scrape // errors. Thus, with unchecked Collectors, the responsibility to not collect // metrics that lead to inconsistencies in the total scrape result lies with the // implementer of the Collector. While this is not a desirable state, it is diff --git a/prometheus/value.go b/prometheus/value.go index 3dcb4fde2..2be470ce1 100644 --- a/prometheus/value.go +++ b/prometheus/value.go @@ -28,7 +28,8 @@ import ( // ValueType is an enumeration of metric types that represent a simple value. type ValueType int -// Possible values for the ValueType enum. +// Possible values for the ValueType enum. Use UntypedValue to mark a metric +// with an unknown type. const ( _ ValueType = iota CounterValue From 92c1ac77e7941dc8fd8cc2e6a1665f90db74f3da Mon Sep 17 00:00:00 2001 From: beorn7 Date: Wed, 12 Feb 2020 19:24:11 +0100 Subject: [PATCH 2/3] Add a "factory" to make promauto work for custom registries Also, update the package documentation. The concerns about the global registry aren't really valid anymore because promauto now also works with custom registries. The musings about the http.DefaultMux are more a digression and shouldn't be in a doc comment. Signed-off-by: beorn7 --- prometheus/promauto/auto.go | 286 ++++++++++++++++++++++++++---------- 1 file changed, 209 insertions(+), 77 deletions(-) diff --git a/prometheus/promauto/auto.go b/prometheus/promauto/auto.go index a00ba1eb8..070a4f571 100644 --- a/prometheus/promauto/auto.go +++ b/prometheus/promauto/auto.go @@ -11,11 +11,16 @@ // See the License for the specific language governing permissions and // limitations under the License. -// Package promauto provides constructors for the usual Prometheus metrics that -// return them already registered with the global registry -// (prometheus.DefaultRegisterer). This allows very compact code, avoiding any -// references to the registry altogether, but all the constructors in this -// package will panic if the registration fails. +// Package promauto provides alternative constructors for the fundamental +// Prometheus metric types and their …Vec and …Func variants. The difference to +// their counterparts in the prometheus package is that the promauto +// constructors return Collectors that are already registered with a +// registry. There are two sets of constructors. The constructors in the first +// set are top-level functions, while the constructors in the other set are +// methods of the Factory type. The top-level function return Collectors +// registered with the global registry (prometheus.DefaultRegisterer), while the +// methods return Collectors registered with the registry the Factory was +// constructed with. All constructors panic if the registration fails. // // The following example is a complete program to create a histogram of normally // distributed random numbers from the math/rand package: @@ -79,51 +84,78 @@ // http.ListenAndServe(":1971", nil) // } // +// A Factory is created with the With(prometheus.Registerer) function, which +// enables two usage pattern. With(prometheus.Registerer) can be called once per +// line: +// +// var ( +// reg = prometheus.NewRegistry() +// randomNumbers = promauto.With(reg).NewHistogram(prometheus.HistogramOpts{ +// Name: "random_numbers", +// Help: "A histogram of normally distributed random numbers.", +// Buckets: prometheus.LinearBuckets(-3, .1, 61), +// }) +// requestCount = promauto.With(reg).NewCounterVec( +// prometheus.CounterOpts{ +// Name: "http_requests_total", +// Help: "Total number of HTTP requests by status code end method.", +// }, +// []string{"code", "method"}, +// ) +// ) +// +// Or it can be used to create a Factory once to be used multiple times: +// +// var ( +// reg = prometheus.NewRegistry() +// factory = promauto.With(reg) +// randomNumbers = factory.NewHistogram(prometheus.HistogramOpts{ +// Name: "random_numbers", +// Help: "A histogram of normally distributed random numbers.", +// Buckets: prometheus.LinearBuckets(-3, .1, 61), +// }) +// requestCount = factory.NewCounterVec( +// prometheus.CounterOpts{ +// Name: "http_requests_total", +// Help: "Total number of HTTP requests by status code end method.", +// }, +// []string{"code", "method"}, +// ) +// ) +// // This appears very handy. So why are these constructors locked away in a -// separate package? There are two caveats: -// -// First, in more complex programs, global state is often quite problematic. -// That's the reason why the metrics constructors in the prometheus package do -// not interact with the global prometheus.DefaultRegisterer on their own. You -// are free to use the Register or MustRegister functions to register them with -// the global prometheus.DefaultRegisterer, but you could as well choose a local -// Registerer (usually created with prometheus.NewRegistry, but there are other -// scenarios, e.g. testing). -// -// The second issue is that registration may fail, e.g. if a metric inconsistent -// with the newly to be registered one is already registered. But how to signal -// and handle a panic in the automatic registration with the default registry? -// The only way is panicking. While panicking on invalid input provided by the -// programmer is certainly fine, things are a bit more subtle in this case: You -// might just add another package to the program, and that package (in its init -// function) happens to register a metric with the same name as your code. Now, -// all of a sudden, either your code or the code of the newly imported package -// panics, depending on initialization order, without any opportunity to handle -// the case gracefully. Even worse is a scenario where registration happens -// later during the runtime (e.g. upon loading some kind of plugin), where the -// panic could be triggered long after the code has been deployed to -// production. A possibility to panic should be explicitly called out by the -// Must… idiom, cf. prometheus.MustRegister. But adding a separate set of -// constructors in the prometheus package called MustRegisterNewCounterVec or -// similar would be quite unwieldy. Adding an extra MustRegister method to each -// metric, returning the registered metric, would result in nice code for those -// using the method, but would pollute every single metric interface for -// everybody avoiding the global registry. -// -// To address both issues, the problematic auto-registering and possibly -// panicking constructors are all in this package with a clear warning -// ahead. And whoever cares about avoiding global state and possibly panicking -// function calls can simply ignore the existence of the promauto package -// altogether. -// -// A final note: There is a similar case in the net/http package of the standard -// library. It has DefaultServeMux as a global instance of ServeMux, and the -// Handle function acts on it, panicking if a handler for the same pattern has -// already been registered. However, one might argue that the whole HTTP routing -// is usually set up closely together in the same package or file, while -// Prometheus metrics tend to be spread widely over the codebase, increasing the -// chance of surprising registration failures. Furthermore, the use of global -// state in net/http has been criticized widely, and some avoid it altogether. +// separate package? +// +// The main problem is that registration may fail, e.g. if a metric inconsistent +// with the newly to be registered one is already registered. Therefore, the +// Register method in the prometheus.Registerer interface returns an error, and +// the same is the case for the top-level prometheus.Register function that +// registers with the global registry. The prometheus package also provides +// MustRegister versions for both. They panic if the registration fails, and +// they clearly call this out by using the Must… idiom. Panicking is a bit +// problematic here because it doesn't just happen on input provided by the +// caller that is invalid on its own. Things are a bit more subtle here: Metric +// creation and registration tend to be spread widely over the codebase. It can +// easily happen that an incompatible metric is added to an unrelated part of +// the code, and suddenly code that used to work perfectly fine starts to panic +// (provided that the registration of the newly added metric happens before the +// registration of the previously existing metric). This may come as an even +// bigger surprise with the global registry, where simply importing another +// package can trigger a panic (if the newly imported package registers metrics +// in its init function). At least, in the prometheus package, creation of +// metrics and other collectors is separate from registration. You first create +// the metric, and then you decide explicitly if you want to register it with a +// local or the global registry, and if you want to handle the error or risk a +// panic. With the constructors in the promauto package, registration is +// automatic, and if it fails, it will always panic. Furthermore, the +// constructors will often be called in the var section of a file, which means +// that panicking will happen as a side effect of merely importing a package. +// +// A separate package allows conservative users to entirely ignore it. And +// whoever wants to use it, will do so explicitly, with an opportunity to read +// this warning. +// +// Enjoy promauto responsibly! package promauto import "github.com/prometheus/client_golang/prometheus" @@ -132,9 +164,7 @@ import "github.com/prometheus/client_golang/prometheus" // but it automatically registers the Counter with the // prometheus.DefaultRegisterer. If the registration fails, NewCounter panics. func NewCounter(opts prometheus.CounterOpts) prometheus.Counter { - c := prometheus.NewCounter(opts) - prometheus.MustRegister(c) - return c + return With(prometheus.DefaultRegisterer).NewCounter(opts) } // NewCounterVec works like the function of the same name in the prometheus @@ -142,9 +172,7 @@ func NewCounter(opts prometheus.CounterOpts) prometheus.Counter { // prometheus.DefaultRegisterer. If the registration fails, NewCounterVec // panics. func NewCounterVec(opts prometheus.CounterOpts, labelNames []string) *prometheus.CounterVec { - c := prometheus.NewCounterVec(opts, labelNames) - prometheus.MustRegister(c) - return c + return With(prometheus.DefaultRegisterer).NewCounterVec(opts, labelNames) } // NewCounterFunc works like the function of the same name in the prometheus @@ -152,45 +180,35 @@ func NewCounterVec(opts prometheus.CounterOpts, labelNames []string) *prometheus // prometheus.DefaultRegisterer. If the registration fails, NewCounterFunc // panics. func NewCounterFunc(opts prometheus.CounterOpts, function func() float64) prometheus.CounterFunc { - g := prometheus.NewCounterFunc(opts, function) - prometheus.MustRegister(g) - return g + return With(prometheus.DefaultRegisterer).NewCounterFunc(opts, function) } // NewGauge works like the function of the same name in the prometheus package // but it automatically registers the Gauge with the // prometheus.DefaultRegisterer. If the registration fails, NewGauge panics. func NewGauge(opts prometheus.GaugeOpts) prometheus.Gauge { - g := prometheus.NewGauge(opts) - prometheus.MustRegister(g) - return g + return With(prometheus.DefaultRegisterer).NewGauge(opts) } // NewGaugeVec works like the function of the same name in the prometheus // package but it automatically registers the GaugeVec with the // prometheus.DefaultRegisterer. If the registration fails, NewGaugeVec panics. func NewGaugeVec(opts prometheus.GaugeOpts, labelNames []string) *prometheus.GaugeVec { - g := prometheus.NewGaugeVec(opts, labelNames) - prometheus.MustRegister(g) - return g + return With(prometheus.DefaultRegisterer).NewGaugeVec(opts, labelNames) } // NewGaugeFunc works like the function of the same name in the prometheus // package but it automatically registers the GaugeFunc with the // prometheus.DefaultRegisterer. If the registration fails, NewGaugeFunc panics. func NewGaugeFunc(opts prometheus.GaugeOpts, function func() float64) prometheus.GaugeFunc { - g := prometheus.NewGaugeFunc(opts, function) - prometheus.MustRegister(g) - return g + return With(prometheus.DefaultRegisterer).NewGaugeFunc(opts, function) } // NewSummary works like the function of the same name in the prometheus package // but it automatically registers the Summary with the // prometheus.DefaultRegisterer. If the registration fails, NewSummary panics. func NewSummary(opts prometheus.SummaryOpts) prometheus.Summary { - s := prometheus.NewSummary(opts) - prometheus.MustRegister(s) - return s + return With(prometheus.DefaultRegisterer).NewSummary(opts) } // NewSummaryVec works like the function of the same name in the prometheus @@ -198,18 +216,14 @@ func NewSummary(opts prometheus.SummaryOpts) prometheus.Summary { // prometheus.DefaultRegisterer. If the registration fails, NewSummaryVec // panics. func NewSummaryVec(opts prometheus.SummaryOpts, labelNames []string) *prometheus.SummaryVec { - s := prometheus.NewSummaryVec(opts, labelNames) - prometheus.MustRegister(s) - return s + return With(prometheus.DefaultRegisterer).NewSummaryVec(opts, labelNames) } // NewHistogram works like the function of the same name in the prometheus // package but it automatically registers the Histogram with the // prometheus.DefaultRegisterer. If the registration fails, NewHistogram panics. func NewHistogram(opts prometheus.HistogramOpts) prometheus.Histogram { - h := prometheus.NewHistogram(opts) - prometheus.MustRegister(h) - return h + return With(prometheus.DefaultRegisterer).NewHistogram(opts) } // NewHistogramVec works like the function of the same name in the prometheus @@ -217,7 +231,125 @@ func NewHistogram(opts prometheus.HistogramOpts) prometheus.Histogram { // prometheus.DefaultRegisterer. If the registration fails, NewHistogramVec // panics. func NewHistogramVec(opts prometheus.HistogramOpts, labelNames []string) *prometheus.HistogramVec { + return With(prometheus.DefaultRegisterer).NewHistogramVec(opts, labelNames) +} + +// Factory provides factory methods to create Collectors that are automatically +// registered with a Registerer. Create a Factory with the With function, +// providing a Registerer to auto-register created Collectors with. The zero +// value of a Factory creates Collectors that are not registered with any +// Registerer. All methods of the Factory panic if the registration fails. +type Factory struct { + r prometheus.Registerer +} + +// With creates a Factory using the provided Registerer for registration of the +// created Collectors. +func With(r prometheus.Registerer) Factory { return Factory{r} } + +// NewCounter works like the function of the same name in the prometheus package +// but it automatically registers the Counter with the Factory's Registerer. +func (f Factory) NewCounter(opts prometheus.CounterOpts) prometheus.Counter { + c := prometheus.NewCounter(opts) + if f.r != nil { + f.r.MustRegister(c) + } + return c +} + +// NewCounterVec works like the function of the same name in the prometheus +// package but it automatically registers the CounterVec with the Factory's +// Registerer. +func (f Factory) NewCounterVec(opts prometheus.CounterOpts, labelNames []string) *prometheus.CounterVec { + c := prometheus.NewCounterVec(opts, labelNames) + if f.r != nil { + f.r.MustRegister(c) + } + return c +} + +// NewCounterFunc works like the function of the same name in the prometheus +// package but it automatically registers the CounterFunc with the Factory's +// Registerer. +func (f Factory) NewCounterFunc(opts prometheus.CounterOpts, function func() float64) prometheus.CounterFunc { + c := prometheus.NewCounterFunc(opts, function) + if f.r != nil { + f.r.MustRegister(c) + } + return c +} + +// NewGauge works like the function of the same name in the prometheus package +// but it automatically registers the Gauge with the Factory's Registerer. +func (f Factory) NewGauge(opts prometheus.GaugeOpts) prometheus.Gauge { + g := prometheus.NewGauge(opts) + if f.r != nil { + f.r.MustRegister(g) + } + return g +} + +// NewGaugeVec works like the function of the same name in the prometheus +// package but it automatically registers the GaugeVec with the Factory's +// Registerer. +func (f Factory) NewGaugeVec(opts prometheus.GaugeOpts, labelNames []string) *prometheus.GaugeVec { + g := prometheus.NewGaugeVec(opts, labelNames) + if f.r != nil { + f.r.MustRegister(g) + } + return g +} + +// NewGaugeFunc works like the function of the same name in the prometheus +// package but it automatically registers the GaugeFunc with the Factory's +// Registerer. +func (f Factory) NewGaugeFunc(opts prometheus.GaugeOpts, function func() float64) prometheus.GaugeFunc { + g := prometheus.NewGaugeFunc(opts, function) + if f.r != nil { + f.r.MustRegister(g) + } + return g +} + +// NewSummary works like the function of the same name in the prometheus package +// but it automatically registers the Summary with the Factory's Registerer. +func (f Factory) NewSummary(opts prometheus.SummaryOpts) prometheus.Summary { + s := prometheus.NewSummary(opts) + if f.r != nil { + f.r.MustRegister(s) + } + return s +} + +// NewSummaryVec works like the function of the same name in the prometheus +// package but it automatically registers the SummaryVec with the Factory's +// Registerer. +func (f Factory) NewSummaryVec(opts prometheus.SummaryOpts, labelNames []string) *prometheus.SummaryVec { + s := prometheus.NewSummaryVec(opts, labelNames) + if f.r != nil { + f.r.MustRegister(s) + } + return s +} + +// NewHistogram works like the function of the same name in the prometheus +// package but it automatically registers the Histogram with the Factory's +// Registerer. +func (f Factory) NewHistogram(opts prometheus.HistogramOpts) prometheus.Histogram { + h := prometheus.NewHistogram(opts) + if f.r != nil { + f.r.MustRegister(h) + } + return h +} + +// NewHistogramVec works like the function of the same name in the prometheus +// package but it automatically registers the HistogramVec with the Factory's +// Registerer. +func (f Factory) NewHistogramVec(opts prometheus.HistogramOpts, labelNames []string) *prometheus.HistogramVec { h := prometheus.NewHistogramVec(opts, labelNames) - prometheus.MustRegister(h) + if f.r != nil { + f.r.MustRegister(h) + } return h } From 1c2884b8072e80bd4367516b119eb716e79bb276 Mon Sep 17 00:00:00 2001 From: beorn7 Date: Thu, 13 Feb 2020 22:08:18 +0100 Subject: [PATCH 3/3] Add NewUntypedFunc to promauto This constructor was simply forgotten. Signed-off-by: beorn7 --- prometheus/promauto/auto.go | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/prometheus/promauto/auto.go b/prometheus/promauto/auto.go index 070a4f571..3c10c8524 100644 --- a/prometheus/promauto/auto.go +++ b/prometheus/promauto/auto.go @@ -234,6 +234,14 @@ func NewHistogramVec(opts prometheus.HistogramOpts, labelNames []string) *promet return With(prometheus.DefaultRegisterer).NewHistogramVec(opts, labelNames) } +// NewUntypedFunc works like the function of the same name in the prometheus +// package but it automatically registers the UntypedFunc with the +// prometheus.DefaultRegisterer. If the registration fails, NewUntypedFunc +// panics. +func NewUntypedFunc(opts prometheus.UntypedOpts, function func() float64) prometheus.UntypedFunc { + return With(prometheus.DefaultRegisterer).NewUntypedFunc(opts, function) +} + // Factory provides factory methods to create Collectors that are automatically // registered with a Registerer. Create a Factory with the With function, // providing a Registerer to auto-register created Collectors with. The zero @@ -353,3 +361,14 @@ func (f Factory) NewHistogramVec(opts prometheus.HistogramOpts, labelNames []str } return h } + +// NewUntypedFunc works like the function of the same name in the prometheus +// package but it automatically registers the UntypedFunc with the Factory's +// Registerer. +func (f Factory) NewUntypedFunc(opts prometheus.UntypedOpts, function func() float64) prometheus.UntypedFunc { + u := prometheus.NewUntypedFunc(opts, function) + if f.r != nil { + f.r.MustRegister(u) + } + return u +}