Overview ▹

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!

Package promauto

Overview ▹

Overview ▾

Index ▹

Index ▾

Package files

func NewCounter ¶

func NewCounterFunc ¶

func NewCounterVec ¶

func NewGauge ¶

func NewGaugeFunc ¶

func NewGaugeVec ¶

func NewHistogram ¶

func NewHistogramVec ¶

func NewSummary ¶

func NewSummaryVec ¶

func NewUntypedFunc ¶

type Factory ¶

func With ¶

func (Factory) NewCounter ¶

func (Factory) NewCounterFunc ¶

func (Factory) NewCounterVec ¶

func (Factory) NewGauge ¶

func (Factory) NewGaugeFunc ¶

func (Factory) NewGaugeVec ¶

func (Factory) NewHistogram ¶

func (Factory) NewHistogramVec ¶

func (Factory) NewSummary ¶

func (Factory) NewSummaryVec ¶

func (Factory) NewUntypedFunc ¶