promhttp

Documentation

Overview

Package promhttp contains functions to create http.Handler instances to expose Prometheus metrics via HTTP. In later versions of this package, it will also contain tooling to instrument instances of http.Handler and http.RoundTripper.

promhttp.Handler acts on the prometheus.DefaultGatherer. With HandlerFor, you can create a handler for a custom registry or anything that implements the Gatherer interface. It also allows to create handlers that act differently on errors or allow to log errors.

Index

• func Handler() http.Handler
• func HandlerFor(reg prometheus.Gatherer, opts HandlerOpts) http.Handler
• type HandlerErrorHandling
• type HandlerOpts
• type Logger

Functions

func Handler

func Handler() http.Handler

Handler returns an HTTP handler for the prometheus.DefaultGatherer. The Handler uses the default HandlerOpts, i.e. report the first error as an HTTP error, no error logging, and compression if requested by the client.

If you want to create a Handler for the DefaultGatherer with different HandlerOpts, create it with HandlerFor with prometheus.DefaultGatherer and your desired HandlerOpts.

func HandlerFor

func HandlerFor(reg prometheus.Gatherer, opts HandlerOpts) http.Handler

HandlerFor returns an http.Handler for the provided Gatherer. The behavior of the Handler is defined by the provided HandlerOpts.

Types

type HandlerErrorHandling

type HandlerErrorHandling int

HandlerErrorHandling defines how a Handler serving metrics will handle errors.

const (
	// Serve an HTTP status code 500 upon the first error
	// encountered. Report the error message in the body.
	HTTPErrorOnError HandlerErrorHandling = iota
	// Ignore errors and try to serve as many metrics as possible.  However,
	// if no metrics can be served, serve an HTTP status code 500 and the
	// last error message in the body. Only use this in deliberate "best
	// effort" metrics collection scenarios. It is recommended to at least
	// log errors (by providing an ErrorLog in HandlerOpts) to not mask
	// errors completely.
	ContinueOnError
	// Panic upon the first error encountered (useful for "crash only" apps).
	PanicOnError
)

These constants cause handlers serving metrics to behave as described if errors are encountered.

type HandlerOpts

type HandlerOpts struct {
	// ErrorLog specifies an optional logger for errors collecting and
	// serving metrics. If nil, errors are not logged at all.
	ErrorLog Logger
	// ErrorHandling defines how errors are handled. Note that errors are
	// logged regardless of the configured ErrorHandling provided ErrorLog
	// is not nil.
	ErrorHandling HandlerErrorHandling
	// If DisableCompression is true, the handler will never compress the
	// response, even if requested by the client.
	DisableCompression bool
}

HandlerOpts specifies options how to serve metrics via an http.Handler. The zero value of HandlerOpts is a reasonable default.

type Logger

type Logger interface {
	Println(v ...interface{})
}

Logger is the minimal interface HandlerOpts needs for logging. Note that log.Logger from the standard library implements this interface, and it is easy to implement by custom loggers, if they don't do so already anyway.