instrumented_http

README

instrumented_http

A Go http.RoundTripper that exports request statistics via Prometheus.

Example

Transparently inject instrumented_http into any http.Client or http.RoundTripper and get metrics about all requests made.

$ curl -Ss 127.0.0.1:9099/metrics | grep http
http_request_duration_seconds{handler="instrumented_http",host="my-cluster.example.org",method="GET",path="pods",query="",scheme="https",status="200",quantile="0.5"} 0.83626
http_request_duration_seconds{handler="instrumented_http",host="my-cluster.example.org",method="GET",path="pods",query="",scheme="https",status="200",quantile="0.9"} 0.736648
http_request_duration_seconds{handler="instrumented_http",host="my-cluster.example.org",method="GET",path="pods",query="",scheme="https",status="200",quantile="0.99"} 0.736648
http_request_duration_seconds_sum{handler="instrumented_http",host="my-cluster.example.org",method="GET",path="pods",query="",scheme="https",status="200"} 0.820274243
http_request_duration_seconds_count{handler="instrumented_http",host="my-cluster.example.org",method="GET",path="pods",query="",scheme="https",status="200"} 2

Usage

Browse the examples directory to see how instrumented_http works with:

• http.DefaultClient: examples/default-client
• a custom http.Transport: examples/custom-transport
• the Google CloudDNS client: examples/googledns
• the AWS Route53 client: examples/route53
• the Kubernetes client: examples/kubernetes
• Resty: examples/resty
• Sling: examples/sling
• Gentleman: examples/gentleman

Documentation

Overview

Package instrumented_http provides a drop-in metrics-enabled replacement for any http.Client or http.RoundTripper.

Index

• Constants
• Variables
• func NewClient(next *http.Client, cbs *Callbacks) *http.Client
• func NewTransport(next http.RoundTripper, cbs *Callbacks) http.RoundTripper
• type Callbacks
• type Transport
  • func (it *Transport) RoundTrip(req *http.Request) (*http.Response, error)

Constants

const (
	BogusStatusCode = 999
)

Variables

var (
	// RequestDurationSeconds is a Prometheus summary to collect request times.
	RequestDurationSeconds = prometheus.NewSummaryVec(
		prometheus.SummaryOpts{
			Name:        "request_duration_seconds",
			Help:        "The HTTP request latencies in seconds.",
			Subsystem:   "http",
			ConstLabels: prometheus.Labels{"handler": handlerName},
			Objectives:  map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},
		},
		[]string{"scheme", "host", "path", "query", "method", "status"},
	)

	// EliminatingProcessor is a callback that returns a blank string on any input.
	EliminatingProcessor = func(_ string) string { return "" }
	// IdentityProcessor is callback that returns whatever is passed to it.
	IdentityProcessor = func(input string) string { return input }
	// LastPathElementProcessor is callback that returns the last element of a URL path.
	LastPathElementProcessor = func(path string) string {
		parts := strings.Split(path, "/")
		return parts[len(parts)-1]
	}
	// IntToStringProcessor converts an integer value to its string representation.
	IntToStringProcessor = func(input int) string { return fmt.Sprintf("%d", input) }
	// ServerErrorCodeProcessor exports all failed responses (5xx, timeouts, ...) as status=failure
	ServerErrorCodeProcessor = func(code int) string {
		if code >= http.StatusInternalServerError {
			return "failure"
		}
		return "success"
	}
)

Functions

func NewClient

func NewClient(next *http.Client, cbs *Callbacks) *http.Client

NewClient takes a *http.Client and returns a *http.Client that has its RoundTripper wrapped with instrumentation. Optionally, It can receive a collection of callbacks that process request path and query into a suitable label value.

func NewTransport

func NewTransport(next http.RoundTripper, cbs *Callbacks) http.RoundTripper

NewTransport takes a http.RoundTripper, wraps it with instrumentation and returns it as a new http.RoundTripper. Optionally, It can receive a collection of callbacks that process request path and query into a suitable label value.

Types

type Callbacks

type Callbacks struct {
	PathProcessor  func(string) string
	QueryProcessor func(string) string
	CodeProcessor  func(int) string
}

Callbacks is a collection of callbacks passed to Transport.

type Transport

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

Transport is a http.RoundTripper that collects Prometheus metrics of every request it processes. It allows to be configured with callbacks that process request path and query into a suitable label value.

func (*Transport) RoundTrip

func (it *Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper. It forwards the request to the next RoundTripper and measures the time it took in Prometheus summary.