Documentation ¶
Overview ¶
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 register the Collectors with a registry before returning them. 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 functions 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:
package main import ( "math/rand" "net/http" "github.com/prometheus/client_golang/prometheus" "github.com/prometheus/client_golang/prometheus/promauto" "github.com/prometheus/client_golang/prometheus/promhttp" ) var histogram = promauto.NewHistogram(prometheus.HistogramOpts{ Name: "random_numbers", Help: "A histogram of normally distributed random numbers.", Buckets: prometheus.LinearBuckets(-3, .1, 61), }) func Random() { for { histogram.Observe(rand.NormFloat64()) } } func main() { go Random() http.Handle("/metrics", promhttp.Handler()) http.ListenAndServe(":1971", nil) }
Prometheus's version of a minimal hello-world program:
package main import ( "fmt" "net/http" "github.com/prometheus/client_golang/prometheus" "github.com/prometheus/client_golang/prometheus/promauto" "github.com/prometheus/client_golang/prometheus/promhttp" ) func main() { http.Handle("/", promhttp.InstrumentHandlerCounter( promauto.NewCounterVec( prometheus.CounterOpts{ Name: "hello_requests_total", Help: "Total number of hello-world requests by HTTP code.", }, []string{"code"}, ), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { fmt.Fprint(w, "Hello, world!") }), )) http.Handle("/metrics", promhttp.Handler()) http.ListenAndServe(":1971", nil) }
A Factory is created with the With(prometheus.Registerer) function, which enables two usage patterns. 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 and 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 and method.", }, []string{"code", "method"}, ) )
This appears very handy. So why are these constructors locked away in a separate package?
The main problem is that registration may fail, e.g. if a metric inconsistent with or equal to 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 problematic in this case 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!
Index ¶
- func NewCounter(opts prometheus.CounterOpts) prometheus.Counter
- func NewCounterFunc(opts prometheus.CounterOpts, function func() float64) prometheus.CounterFunc
- func NewCounterVec(opts prometheus.CounterOpts, labelNames []string) *prometheus.CounterVec
- func NewGauge(opts prometheus.GaugeOpts) prometheus.Gauge
- func NewGaugeFunc(opts prometheus.GaugeOpts, function func() float64) prometheus.GaugeFunc
- func NewGaugeVec(opts prometheus.GaugeOpts, labelNames []string) *prometheus.GaugeVec
- func NewHistogram(opts prometheus.HistogramOpts) prometheus.Histogram
- func NewHistogramVec(opts prometheus.HistogramOpts, labelNames []string) *prometheus.HistogramVec
- func NewSummary(opts prometheus.SummaryOpts) prometheus.Summary
- func NewSummaryVec(opts prometheus.SummaryOpts, labelNames []string) *prometheus.SummaryVec
- func NewUntypedFunc(opts prometheus.UntypedOpts, function func() float64) prometheus.UntypedFunc
- type Factory
- func (f Factory) NewCounter(opts prometheus.CounterOpts) prometheus.Counter
- func (f Factory) NewCounterFunc(opts prometheus.CounterOpts, function func() float64) prometheus.CounterFunc
- func (f Factory) NewCounterVec(opts prometheus.CounterOpts, labelNames []string) *prometheus.CounterVec
- func (f Factory) NewGauge(opts prometheus.GaugeOpts) prometheus.Gauge
- func (f Factory) NewGaugeFunc(opts prometheus.GaugeOpts, function func() float64) prometheus.GaugeFunc
- func (f Factory) NewGaugeVec(opts prometheus.GaugeOpts, labelNames []string) *prometheus.GaugeVec
- func (f Factory) NewHistogram(opts prometheus.HistogramOpts) prometheus.Histogram
- func (f Factory) NewHistogramVec(opts prometheus.HistogramOpts, labelNames []string) *prometheus.HistogramVec
- func (f Factory) NewSummary(opts prometheus.SummaryOpts) prometheus.Summary
- func (f Factory) NewSummaryVec(opts prometheus.SummaryOpts, labelNames []string) *prometheus.SummaryVec
- func (f Factory) NewUntypedFunc(opts prometheus.UntypedOpts, function func() float64) prometheus.UntypedFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewCounter ¶
func NewCounter(opts prometheus.CounterOpts) prometheus.Counter
NewCounter works like the function of the same name in the prometheus package but it automatically registers the Counter with the prometheus.DefaultRegisterer. If the registration fails, NewCounter panics.
func NewCounterFunc ¶
func NewCounterFunc(opts prometheus.CounterOpts, function func() float64) prometheus.CounterFunc
NewCounterFunc works like the function of the same name in the prometheus package but it automatically registers the CounterFunc with the prometheus.DefaultRegisterer. If the registration fails, NewCounterFunc panics.
func NewCounterVec ¶
func NewCounterVec(opts prometheus.CounterOpts, labelNames []string) *prometheus.CounterVec
NewCounterVec works like the function of the same name in the prometheus package but it automatically registers the CounterVec with the prometheus.DefaultRegisterer. If the registration fails, NewCounterVec panics.
func NewGauge ¶
func NewGauge(opts prometheus.GaugeOpts) prometheus.Gauge
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 NewGaugeFunc ¶
func NewGaugeFunc(opts prometheus.GaugeOpts, function func() float64) prometheus.GaugeFunc
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 NewGaugeVec ¶
func NewGaugeVec(opts prometheus.GaugeOpts, labelNames []string) *prometheus.GaugeVec
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 NewHistogram ¶
func NewHistogram(opts prometheus.HistogramOpts) prometheus.Histogram
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 NewHistogramVec ¶
func NewHistogramVec(opts prometheus.HistogramOpts, labelNames []string) *prometheus.HistogramVec
NewHistogramVec works like the function of the same name in the prometheus package but it automatically registers the HistogramVec with the prometheus.DefaultRegisterer. If the registration fails, NewHistogramVec panics.
func NewSummary ¶
func NewSummary(opts prometheus.SummaryOpts) prometheus.Summary
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 NewSummaryVec ¶
func NewSummaryVec(opts prometheus.SummaryOpts, labelNames []string) *prometheus.SummaryVec
NewSummaryVec works like the function of the same name in the prometheus package but it automatically registers the SummaryVec with the prometheus.DefaultRegisterer. If the registration fails, NewSummaryVec panics.
func NewUntypedFunc ¶ added in v0.12.1
func NewUntypedFunc(opts prometheus.UntypedOpts, function func() float64) prometheus.UntypedFunc
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.
Types ¶
type Factory ¶ added in v0.12.1
type Factory struct {
// contains filtered or unexported fields
}
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.
func With ¶ added in v0.12.1
func With(r prometheus.Registerer) Factory
With creates a Factory using the provided Registerer for registration of the created Collectors. If the provided Registerer is nil, the returned Factory creates Collectors that are not registered with any Registerer.
func (Factory) NewCounter ¶ added in v0.12.1
func (f Factory) NewCounter(opts prometheus.CounterOpts) prometheus.Counter
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 (Factory) NewCounterFunc ¶ added in v0.12.1
func (f Factory) NewCounterFunc(opts prometheus.CounterOpts, function func() float64) prometheus.CounterFunc
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 (Factory) NewCounterVec ¶ added in v0.12.1
func (f Factory) NewCounterVec(opts prometheus.CounterOpts, labelNames []string) *prometheus.CounterVec
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 (Factory) NewGauge ¶ added in v0.12.1
func (f Factory) NewGauge(opts prometheus.GaugeOpts) prometheus.Gauge
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 (Factory) NewGaugeFunc ¶ added in v0.12.1
func (f Factory) NewGaugeFunc(opts prometheus.GaugeOpts, function func() float64) prometheus.GaugeFunc
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 (Factory) NewGaugeVec ¶ added in v0.12.1
func (f Factory) NewGaugeVec(opts prometheus.GaugeOpts, labelNames []string) *prometheus.GaugeVec
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 (Factory) NewHistogram ¶ added in v0.12.1
func (f Factory) NewHistogram(opts prometheus.HistogramOpts) prometheus.Histogram
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 (Factory) NewHistogramVec ¶ added in v0.12.1
func (f Factory) NewHistogramVec(opts prometheus.HistogramOpts, labelNames []string) *prometheus.HistogramVec
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 (Factory) NewSummary ¶ added in v0.12.1
func (f Factory) NewSummary(opts prometheus.SummaryOpts) prometheus.Summary
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 (Factory) NewSummaryVec ¶ added in v0.12.1
func (f Factory) NewSummaryVec(opts prometheus.SummaryOpts, labelNames []string) *prometheus.SummaryVec
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 (Factory) NewUntypedFunc ¶ added in v0.12.1
func (f Factory) NewUntypedFunc(opts prometheus.UntypedOpts, function func() float64) prometheus.UntypedFunc
NewUntypedFunc works like the function of the same name in the prometheus package but it automatically registers the UntypedFunc with the Factory's Registerer.