touchhttp

Documentation

Overview

Package touchhttp defines the HTTP-specific behavior for metrics within an uber/fx app which uses the touchstone package.

Bootstrapping is similar to touchstone: A Config object can be available in the enclosing fx.App that will tailor certain aspects of the metrics http.Handler.

ServerBundle and ClientBundle are prebaked, opinionated metrics for instrumenting HTTP servers and clients. They each produce middleware given a label for a particular server or client.

Example

_ = fx.New(
	fx.Logger(log.New(ioutil.Discard, "", 0)),
	touchstone.Provide(),
	Provide(),
	fx.Provide(
		func(sb ServerBundle) func(http.Handler) http.Handler { // can use justinas/alice
			return sb.ForServer("main").Then
		},
		func(middleware func(http.Handler) http.Handler) http.Handler {
			return middleware(
				http.HandlerFunc(func(http.ResponseWriter, *http.Request) {
					fmt.Println("handled!")
				}),
			)
		},
	),
	fx.Invoke(
		func(h http.Handler) {
			h.ServeHTTP(
				httptest.NewRecorder(),
				httptest.NewRequest("GET", "/", nil),
			)
		},
	),
)

Output:

handled!

Index

• Constants
• func NewHandlerOpts(cfg Config, p fx.Printer, r prometheus.Registerer) (opts promhttp.HandlerOpts, err error)
• func Provide() fx.Option
• type ClientBundle
  • func NewClientBundle(f *touchstone.Factory, now func() time.Time) (cb ClientBundle, err error)
  • func (cb ClientBundle) ForClient(client string) (ci ClientInstrumenter)
• type ClientInstrumenter
  • func (ci ClientInstrumenter) Then(next httpaux.Client) httpaux.Client
• type Config
• type ErrorPrinter
  • func (ep ErrorPrinter) Println(values ...interface{})
• type Handler
• type In
• type InvalidErrorHandlingError
  • func (e *InvalidErrorHandlingError) Error() string
• type ServerBundle
  • func NewServerBundle(f *touchstone.Factory, now func() time.Time) (sb ServerBundle, err error)
  • func (sb ServerBundle) ForServer(server string) (si ServerInstrumenter)
• type ServerInstrumenter
  • func (si ServerInstrumenter) Then(next http.Handler) http.Handler

Examples

• Package

Constants

const (
	// ServerLabel is the metric label containing the name of the HTTP server.
	ServerLabel = "server"

	// ClientLabel is the metric label containing the name of the HTTP client.
	ClientLabel = "client"

	// CodeLabel is the metric label containing the HTTP response code.
	CodeLabel = "code"

	// MethodLabel is the metric label containing the HTTP request's method.
	MethodLabel = "method"

	// MethodUnrecognized is used when an HTTP method is not one of the
	// standard methods, as enumerated in the net/http package.
	MethodUnrecognized = "UNRECOGNIZED"

	// MetricServerRequestCount is the name of the counter that tracks the
	// total number of received server requests.
	MetricServerRequestCount = "server_request_count"

	// MetricServerRequestDuration is the name of the histogram that tracks
	// the total time taken by handlers to process requests.
	MetricServerRequestDuration = "server_request_duration_ms"

	// MetricServerRequestsInFlight is the name of the gauge that tracks the
	// instantaneous view of how many requests the handler is currently serving.
	MetricServerRequestsInFlight = "server_requests_in_flight"

	// MetricServerRequestSize is the name of the histogram that tracks the sizes
	// of requests received by handlers.
	MetricServerRequestSize = "server_request_size"

	// MetricClientRequestCount is the name of the counter that tracks the
	// total number of outgoing server requests.
	MetricClientRequestCount = "client_request_count"

	// MetricClientRequestDuration is the name of the histogram that tracks
	// the total time taken to send a request and receive a response.
	MetricClientRequestDuration = "client_request_duration_ms"

	// MetricClientRequestsInFlight is the name of the gauge that tracks the
	// instantaneous view of how many requests the client has currently pending.
	MetricClientRequestsInFlight = "client_requests_in_flight"

	// MetricClientRequestSize is the name of the histogram that tracks the sizes
	// of requests sent to servers.
	MetricClientRequestSize = "client_request_size"

	// MetricClientErrorCount is the total number of errors (nil responses) that
	// occurred since startup.
	MetricClientErrorCount = "client_error_count"
)

const (
	// HTTPErrorOnError is the value allowed for Config.ErrorHandling that maps
	// to promhttp.HTTPErrorOnError.  This is also the default used when no
	// value is set.
	HTTPErrorOnError = "http"

	// ContinueOnError is the value allowed for Config.ErrorHandler that maps
	// to promhttp.ContinueOnError.
	ContinueOnError = "continue"

	// PanicOnError is the value allowed for Config.ErrorHandler that maps
	// to promhttp.PanicOnError.
	PanicOnError = "panic"
)

Functions

func NewHandlerOpts

func NewHandlerOpts(cfg Config, p fx.Printer, r prometheus.Registerer) (opts promhttp.HandlerOpts, err error)

NewHandlerOpts creates a basic HandlerOpts from an Config configuration.

func Provide

func Provide() fx.Option

Provide bootstraps the promhttp environment for an uber/fx app. This function creates the following component types:

• promhttp.HandlerOpts
• touchhttp.Handler This is the http.Handler to use to serve prometheus metrics. It will be instrumented if Config.InstrumentMetricHandler is set to true.
• touchhttp.ClientBundle
• touchhttp.ServerBundle

Types

type ClientBundle

type ClientBundle struct {
	// contains filtered or unexported fields
}

ClientBundle is a prebaked set of clientside HTTP metrics. A ClientBundle is used to create middleware in the form of a ClientInstrumenter.

func NewClientBundle

func NewClientBundle(f *touchstone.Factory, now func() time.Time) (cb ClientBundle, err error)

NewClientBundle constructs a bundle of HTTP metrics using the given Factory. This function should be called at most once for any given Factory, or a prometheus.AlreadyRegisteredError will occur.

If now is nil, time.Now is used.

func (ClientBundle) ForClient

func (cb ClientBundle) ForClient(client string) (ci ClientInstrumenter)

ForClient curries this bundle with the given client name and produces a ClientInstrumenter.

type ClientInstrumenter

type ClientInstrumenter struct {
	// contains filtered or unexported fields
}

ClientInstrumenter is a clientside middleware that provides HTTP client metrics.

func (ClientInstrumenter) Then

func (ci ClientInstrumenter) Then(next httpaux.Client) httpaux.Client

Then is a client middleware that instruments the given client. This middleware is compatible with httpaux.

type Config

type Config struct {
	// ErrorHandling is the promhttp.HandlerErrorHandling value.  If this field
	// is unset, promhttp.HTTPErrorOnError is used.
	//
	// See: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus/promhttp#HandlerErrorHandling
	ErrorHandling string `json:"errorHandling" yaml:"errorHandling"`

	// DisableCompression disables compression on metrics output.
	DisableCompression bool `json:"disableCompression" yaml:"disableCompression"`

	// MaxRequestsInFlight controls the number of concurrent HTTP metrics requests.
	MaxRequestsInFlight int `json:"maxRequestsInFlight" yaml:"maxRequestsInFlight"`

	// Timeout is the time period after which the handler will return a 503.
	Timeout time.Duration `json:"timeout" yaml:"timeout"`

	// EnableOpenMetrics controls whether open metrics encoding is available
	// during content negotiation.
	EnableOpenMetrics bool `json:"enableOpenMetrics" yaml:"enableOpenMetrics"`

	// InstrumentMetricHandler indicates whether the http.Handler that renders
	// prometheus metrics will itself be decorated with metrics.
	//
	// See: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus/promhttp#InstrumentMetricHandler
	InstrumentMetricHandler bool `json:"instrumentMetricHandler" yaml:"instrumentMetricHandler"`
}

Config is the configuration for boostrapping the promhttp package.

type ErrorPrinter

type ErrorPrinter struct {
	fx.Printer
}

ErrorPrinter adapts an fx.Printer and allows it to be used as an error Logger for prometheus.

func (ErrorPrinter) Println

func (ep ErrorPrinter) Println(values ...interface{})

Println satisfies the promhttp.Logger interface.

type Handler

type Handler http.Handler

Handler is a type alias for http.Handler that makes dependency injection easier. The handler bootstrapped by this package will be of this type, which means injection by type will not interfere with any other http.Handler component in the application.

The promhttp.HandlerFor function is used to create this type using the handler options created from the Config type.

See: https://pkg.go.dev/github.com/prometheus/client_golang/prometheus/promhttp#HandlerFor

type In

type In struct {
	fx.In

	// Config is the prometheus configuration.  This is optional,
	// as a zero value for Config will result in a default environment.
	Config Config `optional:"true"`

	// Printer is the fx.Printer to which this package writes messages.
	// This is optional, and if unset no messages are written.
	Printer fx.Printer `optional:"true"`

	// Now is the optional current time function.  If supplied, this
	// will be used for computing metric durations.
	Now func() time.Time `optional:"true"`
}

In represents the components used by this package to bootstrap a promhttp environment. Provide uses these components.

type InvalidErrorHandlingError

type InvalidErrorHandlingError struct {
	// Value is the unrecognized Config.ErrorHandling value.
	Value string
}

InvalidErrorHandlingError is the error returned when Config.ErrorHandling is not a recognized value.

func (*InvalidErrorHandlingError) Error

func (e *InvalidErrorHandlingError) Error() string

Error satisfies the error interface.

type ServerBundle

type ServerBundle struct {
	// contains filtered or unexported fields
}

ServerBundle is a prebaked set of serverside HTTP metrics. A ServerBundle is used to create middleware in the form of a ServerInstrumenter.

func NewServerBundle

func NewServerBundle(f *touchstone.Factory, now func() time.Time) (sb ServerBundle, err error)

NewServerBundle constructs a bundle of HTTP metrics using the given Factory. This function should be called at most once for any given Factory, or a prometheus.AlreadyRegisteredError will occur.

If now is nil, time.Now is used.

func (ServerBundle) ForServer

func (sb ServerBundle) ForServer(server string) (si ServerInstrumenter)

ForServer curries this bundle with the given server name and produces a ServerInstrumenter.

type ServerInstrumenter

type ServerInstrumenter struct {
	// contains filtered or unexported fields
}

ServerInstrumenter is a serverside middleware that provides http.Handler metrics.

func (ServerInstrumenter) Then

func (si ServerInstrumenter) Then(next http.Handler) http.Handler

Then is a server middleware that instruments the given handler. This middleware is compatible with justinas/alice and gorilla/mux.