status

Documentation

Overview

Package status provides helpers for building standardized sla status endpoints in web services.

It provides types to wrap existing actions to track the success and error history of those actions and then report that history through status endpoints.

The package provides a `status.Controller` type that is created with the `status.NewController(...)` method:

    statusController := status.New(
		status.OptCheck(
			"redis",
			redisConnection, // implements `status.Checker` for you already
		),
		status.OptCheck(
			"postgres",
			dbConnection, // implements `status.Checker` for you already
		),
	)
	...
	app.Register(statusController)

The app will now have `/status/sla` and `/status/details` endpoints registered.

Index

• Constants
• type Actioner
• type ActionerFunc
• type Checker
• type CheckerFunc
• type Controller
  • func NewController(opts ...ControllerOption) *Controller
  • func (c Controller) Interceptor(serviceName string) async.Interceptor
  • func (c Controller) Register(app *web.App)
• type ControllerOption
  • func OptCheck(serviceName string, check Checker) ControllerOption
  • func OptConfig(cfg configmeta.Meta) ControllerOption
  • func OptLog(log logger.Log) ControllerOption
  • func OptMiddleware(middleware ...web.Middleware) ControllerOption
  • func OptTimeout(timeout time.Duration) ControllerOption
• type Details
• type ErrorInfo
• type Freeform
  • func NewFreeform(opts ...FreeformOption) *Freeform
  • func (f Freeform) CheckStatuses(ctx context.Context, servicesToCheck ...string) (FreeformResult, error)
  • func (f Freeform) Endpoint(servicesToCheck ...string) web.Action
• type FreeformOption
  • func OptFreeformLog(log logger.Log) FreeformOption
  • func OptFreeformTimeout(d time.Duration) FreeformOption
• type FreeformResult
• type Info
• type RequestInfo
• type Signal
• type TrackedAction
  • func NewTrackedAction(serviceName string, opts ...TrackedActionOption) *TrackedAction
  • func (t *TrackedAction) AddErroredRequest(args interface{})
  • func (t *TrackedAction) AddSuccessfulRequest()
  • func (t *TrackedAction) CleanOldRequests()
  • func (t *TrackedAction) GetStatus() (info Info)
  • func (t *TrackedAction) GetStatusSignal() (status Signal)
  • func (t *TrackedAction) Intercept(action Actioner) Actioner
• type TrackedActionAggregator
  • func NewTrackedActionAggregator(trackedActions ...*TrackedAction) *TrackedActionAggregator
  • func (taa *TrackedActionAggregator) Endpoint(servicesToCheck ...string) web.Action
  • func (taa *TrackedActionAggregator) Interceptor(serviceName string, opts ...TrackedActionOption) async.Interceptor
• type TrackedActionConfig
  • func (tc TrackedActionConfig) ExpirationOrDefault() time.Duration
  • func (tc *TrackedActionConfig) Resolve(ctx context.Context) error
• type TrackedActionOption
  • func OptTrackedActionConfig(cfg TrackedActionConfig) TrackedActionOption
• type TrackedActionsResult

Constants

const (
	// DefaultFreeformTimeout is a timeout.
	DefaultFreeformTimeout = 10 * time.Second
	// DefaultTrackedActionExpiration is the default tracker expiration.
	DefaultTrackedActionExpiration = 5 * time.Minute
	// DefaultYellowRequestCount is the default tracker yellow request count.
	DefaultYellowRequestCount = 10
	// DefaultYellowRequestPercentage is the default tracker yellow request percentage.
	DefaultYellowRequestPercentage = 0.005 // 0.5% or 50 bps
	// DefaultRedRequestCount is the default tracker red request count.
	DefaultRedRequestCount = 50
	// DefaultRedRequestPercentage is the default tracker yellow request percentage.
	DefaultRedRequestPercentage = 0.05 // 5% or 500 bps
)

const (
	ErrServiceCheckNotDefined ex.Class = "service check is not defined for service"
)

Errors

Types

type Actioner

type Actioner = async.Actioner

Actioner is a type alias from async.

type ActionerFunc

type ActionerFunc = async.ActionerFunc

ActionerFunc is a type alias from async.

type Checker

type Checker = async.Checker

Checker is an alias to async.Checker

type CheckerFunc

type CheckerFunc = async.CheckerFunc

CheckerFunc is an alias to async.CheckerFunc

type Controller

type Controller struct {
	Config         configmeta.Meta
	Checks         *Freeform
	TrackedActions *TrackedActionAggregator
	Middleware     []web.Middleware
}

Controller is a handler for the status endpoint.

It will register `/status/sla` and `/status/details` routes on the given app.

func NewController

func NewController(opts ...ControllerOption) *Controller

NewController returns a new controller

func (Controller) Interceptor

func (c Controller) Interceptor(serviceName string) async.Interceptor

Interceptor returns a new interceptor for a given serviceName.

func (Controller) Register

func (c Controller) Register(app *web.App)

Register adds the controller's routes to the app.

type ControllerOption

type ControllerOption func(c *Controller)

ControllerOption mutates a controller.

func OptCheck

func OptCheck(serviceName string, check Checker) ControllerOption

OptCheck adds an sla check for a given service.

func OptConfig

func OptConfig(cfg configmeta.Meta) ControllerOption

OptConfig returns an option that sets the configmeta.

func OptLog

func OptLog(log logger.Log) ControllerOption

OptLog returns an option that sets the logger.

func OptMiddleware

func OptMiddleware(middleware ...web.Middleware) ControllerOption

OptMiddleware adds default middleware for the status routes.

Middleware must be set _before_ you register the controller.

func OptTimeout

func OptTimeout(timeout time.Duration) ControllerOption

OptTimeout returns an option that sets checks timeout.

type Details

type Details struct {
	ErrorCount     int            `json:"errorCount"`
	RequestCount   int            `json:"requestCount"`
	ErrorBreakdown map[string]int `json:"errorBreakdown"`
}

Details holds the details about the status results.

type ErrorInfo

type ErrorInfo struct {
	RequestInfo
	Args interface{}
}

ErrorInfo is a type.

type Freeform

type Freeform struct {
	// Timeout serves as an overall timeout, but is
	// enforced per action.
	Timeout time.Duration
	// ServiceChecks are the individual checks
	// we'll try as part of the status.
	ServiceChecks map[string]Checker
	// Log is a reference to a logger for
	// situations where there are errors.
	Log logger.Log
}

Freeform holds sla check actions.

func NewFreeform

func NewFreeform(opts ...FreeformOption) *Freeform

NewFreeform returns a new freeform check aggregator.

func (Freeform) CheckStatuses

func (f Freeform) CheckStatuses(ctx context.Context, servicesToCheck ...string) (FreeformResult, error)

CheckStatuses runs the check statuses for a given list of service names.

func (Freeform) Endpoint

func (f Freeform) Endpoint(servicesToCheck ...string) web.Action

Endpoint implements the handler for a given list of services.

type FreeformOption

type FreeformOption func(*Freeform)

FreeformOption mutates a freeform check.

func OptFreeformLog

func OptFreeformLog(log logger.Log) FreeformOption

OptFreeformLog sets the logger.

func OptFreeformTimeout

func OptFreeformTimeout(d time.Duration) FreeformOption

OptFreeformTimeout sets the timeout.

type FreeformResult

type FreeformResult map[string]bool

FreeformResult is a json result from the freeform check.

type Info

type Info struct {
	Name    string  `json:"name"`
	Status  Signal  `json:"status"`
	Details Details `json:"details"`
}

Info wraps tracked details.

type RequestInfo

type RequestInfo struct {
	RequestTime time.Time
}

RequestInfo is a type.

type Signal

type Signal string

Signal is a status signal.

const (
	SignalUnknown Signal = ""
	SignalGreen   Signal = "green"
	SignalYellow  Signal = "yellow"
	SignalRed     Signal = "red"
)

Signal constants

type TrackedAction

type TrackedAction struct {
	TrackedActionConfig
	sync.Mutex

	ServiceName string
	// contains filtered or unexported fields
}

TrackedAction is a wrapper for action that tracks a rolling window of history based on the configured expiration.

func NewTrackedAction

func NewTrackedAction(serviceName string, opts ...TrackedActionOption) *TrackedAction

NewTrackedAction returns a new tracked action.

func (*TrackedAction) AddErroredRequest

func (t *TrackedAction) AddErroredRequest(args interface{})

AddErroredRequest adds an errored request.

It is safe to call concurrently from multiple goroutines.

func (*TrackedAction) AddSuccessfulRequest

func (t *TrackedAction) AddSuccessfulRequest()

AddSuccessfulRequest adds a successful request.

It is safe to call concurrently from multiple goroutines.

func (*TrackedAction) CleanOldRequests

func (t *TrackedAction) CleanOldRequests()

CleanOldRequests is an action delegate that removes expired requests from the tracker

It is safe to call concurrently from multiple goroutines.

func (*TrackedAction) GetStatus

func (t *TrackedAction) GetStatus() (info Info)

GetStatus gets the status for the tracker.

It is safe to call concurrently from multiple goroutines.

func (*TrackedAction) GetStatusSignal

func (t *TrackedAction) GetStatusSignal() (status Signal)

GetStatusSignal returns the current status signal.

It is safe to call concurrently from multiple goroutines.

func (*TrackedAction) Intercept

func (t *TrackedAction) Intercept(action Actioner) Actioner

Intercept implements async.Interceptor.

type TrackedActionAggregator

type TrackedActionAggregator struct {
	TrackedActions map[string]*TrackedAction
	Log            logger.Log
}

TrackedActionAggregator aggregates tracker results.

func NewTrackedActionAggregator

func NewTrackedActionAggregator(trackedActions ...*TrackedAction) *TrackedActionAggregator

NewTrackedActionAggregator returns a new tracked action aggregator.

func (*TrackedActionAggregator) Endpoint

func (taa *TrackedActionAggregator) Endpoint(servicesToCheck ...string) web.Action

Endpoint implements the endpoint.

func (*TrackedActionAggregator) Interceptor

func (taa *TrackedActionAggregator) Interceptor(serviceName string, opts ...TrackedActionOption) async.Interceptor

Interceptor returns a new tracked action.

type TrackedActionConfig

type TrackedActionConfig struct {
	YellowRequestCount      int
	YellowRequestPercentage float64
	RedRequestCount         int
	RedRequestPercentage    float64
	Expiration              time.Duration
}

TrackedActionConfig is the configuration for the tracker.

func (TrackedActionConfig) ExpirationOrDefault

func (tc TrackedActionConfig) ExpirationOrDefault() time.Duration

ExpirationOrDefault returns an expiration or a default.

func (*TrackedActionConfig) Resolve

func (tc *TrackedActionConfig) Resolve(ctx context.Context) error

Resolve resolves the config.

type TrackedActionOption

type TrackedActionOption func(*TrackedAction)

TrackedActionOption mutates a tracked action.

func OptTrackedActionConfig

func OptTrackedActionConfig(cfg TrackedActionConfig) TrackedActionOption

OptTrackedActionConfig sets the tracked action config.

type TrackedActionsResult

type TrackedActionsResult struct {
	Status     Signal          `json:"status"`
	SubSystems map[string]Info `json:"subsystems"`
}

TrackedActionsResult are tracked actions details.