admin

README

moov-io/base/admin

Package admin implements an http.Server which can be used for operations and monitoring tools. It's designed to be shipped (and ran) inside an existing Go service.

Here's an example of adding admin.Server to serve Prometheus metrics:

import (
    "fmt"
    "os"

    "github.com/moov-io/base/admin"

    "github.com/go-kit/log"
)

var logger log.Logger

// in main.go or cmd/server/main.go

adminServer, err := admin.New(Opts{
	Addr: ":9090",
})
if err != nil {
    // handle error
}
go func() {
	logger.Log("admin", fmt.Sprintf("listening on %s", adminServer.BindAddr()))
	if err := adminServer.Listen(); err != nil {
		err = fmt.Errorf("problem starting admin http: %v", err)
		logger.Log("admin", err)
		// errs <- err // send err to shutdown channel
	}
}()
defer adminServer.Shutdown()

Endpoints

An Admin server has some default endpoints that are useful for operational support and monitoring.

Liveness Probe

This endpoint inspects a set of liveness functions and returns 200 OK if all functions return without errors. If errors are found then a 400 Bad Request response with a JSON object is returned describing the errors.

GET /live

Liveness probes can be registered with the following callback:

func (s *Server) AddLivenessCheck(name string, f func() error)

Readiness Probe

This endpoint inspects a set of readiness functions and returns 200 OK if all functions return without errors. If errors are found then a 400 Bad Request response with a JSON object is returned describing the errors.

GET /ready

Readiness probes can be registered with the following callback:

func (s *Server) AddReadinessCheck(name string, f func() error)

Metrics

This endpoint returns prometheus metrics registered to the prometheus/client_golang singleton metrics registry. Their promauto package can be used to add Counters, Guages, Histograms, etc. The default Go metrics provided by prometheus/client_golang are included.

GET /metrics

...
# HELP promhttp_metric_handler_requests_total Total number of scrapes by HTTP status code.
# TYPE promhttp_metric_handler_requests_total counter
promhttp_metric_handler_requests_total{code="200"} 0
promhttp_metric_handler_requests_total{code="500"} 0
promhttp_metric_handler_requests_total{code="503"} 0
# HELP stream_file_processing_errors Counter of stream submitted ACH files that failed processing
# TYPE stream_file_processing_errors counter
stream_file_processing_errors 0

Documentation

Overview

Package admin implements an http.Server which can be used for operations and monitoring tools. It's designed to be shipped (and ran) inside an existing Go service.

Index

• func Handler() http.Handler
• type Opts
• type Server
  • func New(opts Opts) (*Server, error)
  • func (s *Server) AddHandler(path string, hf http.HandlerFunc)
  • func (s *Server) AddLivenessCheck(name string, f func() error)
  • func (s *Server) AddReadinessCheck(name string, f func() error)
  • func (s *Server) AddVersionHandler(version string)
  • func (s *Server) BindAddr() string
  • func (s *Server) Listen() error
  • func (s *Server) SetIdleTimeout(timeout time.Duration)
  • func (s *Server) SetReadTimeout(timeout time.Duration)
  • func (s *Server) SetWriteTimeout(timeout time.Duration)
  • func (s *Server) Shutdown()
  • func (s *Server) Subrouter(pathPrefix string) *mux.Router

Functions

func Handler

func Handler() http.Handler

Handler returns an http.Handler for the admin http service. This contains metrics and pprof handlers.

No metrics specific to the handler are recorded.

We only want to expose on the admin servlet because these profiles/dumps can contain sensitive info (raw memory).

Types

type Opts

type Opts struct {
	Addr    string
	Timeout time.Duration
}

type Server

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

Server represents a holder around a net/http Server which is used for admin endpoints. (i.e. metrics, healthcheck)

func New

func New(opts Opts) (*Server, error)

New returns an admin.Server instance that handles Prometheus metrics and pprof requests. Callers can use ':0' to bind onto a random port and call BindAddr() for the address.

func (*Server) AddHandler

func (s *Server) AddHandler(path string, hf http.HandlerFunc)

AddHandler will append an http.HandlerFunc to the admin Server

func (*Server) AddLivenessCheck

func (s *Server) AddLivenessCheck(name string, f func() error)

AddLivenessCheck will register a new health check that is executed on every HTTP request of 'GET /live' against the admin server.

Every check will timeout after 10s and return a timeout error.

These checks are designed to be unhealthy only when the application has started but a dependency is unreachable or unhealthy.

func (*Server) AddReadinessCheck

func (s *Server) AddReadinessCheck(name string, f func() error)

AddReadinessCheck will register a new health check that is executed on every HTTP request of 'GET /ready' against the admin server.

Every check will timeout after 10s and return a timeout error.

These checks are designed to be unhealthy while the application is starting.

func (*Server) AddVersionHandler

func (s *Server) AddVersionHandler(version string)

AddVersionHandler will append 'GET /version' route returning the provided version

func (*Server) BindAddr

func (s *Server) BindAddr() string

BindAddr returns the server's bind address. This is in Go's format so :8080 is valid.

func (*Server) Listen

func (s *Server) Listen() error

Listen brings up the admin HTTP server. This call blocks until the server is Shutdown or panics.

func (*Server) SetIdleTimeout

func (s *Server) SetIdleTimeout(timeout time.Duration)

func (*Server) SetReadTimeout

func (s *Server) SetReadTimeout(timeout time.Duration)

func (*Server) SetWriteTimeout

func (s *Server) SetWriteTimeout(timeout time.Duration)

func (*Server) Shutdown

func (s *Server) Shutdown()

Shutdown unbinds the HTTP server.

func (*Server) Subrouter

func (s *Server) Subrouter(pathPrefix string) *mux.Router

Subrouter creates and returns a subrouter with the specific prefix.

The returned subrouter can use middleware without impacting the parent router. For example:

svr, err := New(Opts{
	Addr: ":9090",
})

subRouter := svr.Subrouter("/prefix")
subRouter.Use(someMiddleware)
subRouter.HandleFunc("/resource", ResourceHandler)

Here, requests for "/prefix/resource" would go through someMiddleware while the liveliness and readiness routes added to the parent router by New() would not.