states

README

States

States is an observability tool to observe a system state, we can speak about app database connection, app readiness, or everything else which is not identified as a numeric value

This package want to provide almost the same expericence thant managing app metrics with Prometheus.

Documentation

Overview

Package states is an observability tool to observe a system state, we can speak about app database connection, app readiness, or everything else which is not identified as a numeric value.

Example

High-level example for an app

package main

import (
	"net/http"
)

// Our custom state
// The best way to have enums in Go
type MyState string

// Implement fmt.Stringer
func (m MyState) String() string {
	return string(m)
}

// Well defined state names
const (
	READY   = MyState("ready")
	ERROR   = MyState("error")
	PENDING = MyState("pending")
)

// High-level example for an app
func main() {
	// Create a new state
	mystate := NewState(StateOptions{
		Namespace: "my.app",
		System:    "http.server",
		Name:      "state",
	}, PENDING)

	// Register the new state to the default registry
	MustRegister(mystate)

	// later in the code
	mystate.Set(READY)

	//http.Handle("/states", stateshttp.Handler())
	// http.Handle("/metrics", promhttp.Handler())
	err := http.ListenAndServe(":8080", nil)
	if err != nil {
		panic(err)
	}
}

Index

• Variables
• func Gather() warp10.GTSList
• func MustRegister(state State)
• func Register(state State) error
• type Registry
  • func NewRegistry() Registry
• type State
  • func NewState(options StateOptions, initialValue fmt.Stringer) State
• type StateOptions
• type States

Examples

• Package

Variables

var (
	// DefaultRegistry is ...
	DefaultRegistry = NewRegistry()

	// DefaultStateValue is used when the state is not known
	DefaultStateValue = defaultStateValue{}

	Separator = "."
)

var AlreadyExistsErr = errors.Errorf("this state already exists")

AlreadyExistsErr is throw when you try to register two identical states

Functions

func Gather

func Gather() warp10.GTSList

Gather return a GTS list of all his states

func MustRegister

func MustRegister(state State)

MustRegister register a state to the default Registry Panic if the state already exists

func Register

func Register(state State) error

Register register a state to the default Registry

Types

type Registry

type Registry interface {
	// Register a new state to this registry
	// Can fail if another state with the same namespace/system/name exists
	Register(State) error
	// Register a new state to this registry
	// Panic if another state with the same namespace/system/name exists
	MustRegister(State)
	// Gather a list of all states timeseries
	Gather() warp10.GTSList
}

Registry collect a set of app states

func NewRegistry

func NewRegistry() Registry

NewRegistry create a new Registry

type State

type State interface {
	// Metric return a timeseries
	Metric() *warp10.GTS
	// String pretty print the namespace, system, name and value of the state
	String() string
	// Set update the current state
	Set(fmt.Stringer)
	// Print informations about this state
	Help() string
}

State give the current state of a system

func NewState

func NewState(options StateOptions, initialValue fmt.Stringer) State

NewState create a new state

type StateOptions

type StateOptions struct {
	Namespace string            `json:"namespace,omitempty"`
	System    string            `json:"system,omitempty"`
	Name      string            `json:"name"`
	Help      string            `json:"help,omitempty"`
	Labels    map[string]string `json:"labels"`
}

StateOptions is used to declare a new State

type States

type States []State

States is a list of States