Overview¶

Package promauto provides alternative constructors for the fundamentalPrometheus metric types and their …Vec and …Func variants. The difference totheir counterparts in the prometheus package is that the promautoconstructors register the Collectors with a registry before returning them.There are two sets of constructors. The constructors in the first set aretop-level functions, while the constructors in the other set are methods ofthe Factory type. The top-level functions return Collectors registered withthe global registry (prometheus.DefaultRegisterer), while the methods returnCollectors registered with the registry the Factory was constructed with. Allconstructors panic if the registration fails.

The following example is a complete program to create a histogram of normallydistributed random numbers from the math/rand package:

package mainimport ("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 mainimport ("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, whichenables two usage patterns. With(prometheus.Registerer) can be called once perline:

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 aseparate package?

The main problem is that registration may fail, e.g. if a metric inconsistentwith or equal to the newly to be registered one is already registered.Therefore, the Register method in the prometheus.Registerer interface returnsan error, and the same is the case for the top-level prometheus.Registerfunction that registers with the global registry. The prometheus package alsoprovides MustRegister versions for both. They panic if the registrationfails, and they clearly call this out by using the Must… idiom. Panicking isproblematic in this case because it doesn't just happen on input provided bythe caller that is invalid on its own. Things are a bit more subtle here:Metric creation and registration tend to be spread widely over thecodebase. It can easily happen that an incompatible metric is added to anunrelated part of the code, and suddenly code that used to work perfectlyfine starts to panic (provided that the registration of the newly addedmetric happens before the registration of the previously existingmetric). This may come as an even bigger surprise with the global registry,where simply importing another package can trigger a panic (if the newlyimported package registers metrics in its init function). At least, in theprometheus package, creation of metrics and other collectors is separate fromregistration. You first create the metric, and then you decide explicitly ifyou want to register it with a local or the global registry, and if you wantto handle the error or risk a panic. With the constructors in the promautopackage, registration is automatic, and if it fails, it will alwayspanic. Furthermore, the constructors will often be called in the var sectionof a file, which means that panicking will happen as a side effect of merelyimporting a package.

A separate package allows conservative users to entirely ignore it. Andwhoever wants to use it will do so explicitly, with an opportunity to readthis 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 With(r prometheus.Registerer) 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

This section is empty.

This section is empty.