Back to godoc.org
github.com/prometheus/client_golang/prometheus/promauto

package promauto

v1.6.0
Latest Go to latest
Published: Apr 28, 2020 | License: Apache-2.0 | Module: github.com/prometheus/client_golang

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 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:

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

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!

Index

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

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.

type Factory

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

func With(r prometheus.Registerer) Factory

With creates a Factory using the provided Registerer for registration of the created Collectors.

func (Factory) NewCounter

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

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

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

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

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

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

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

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

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

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

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.

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
f or F : Jump to identifier