goma

README

Goma

Goma is:

• Japanese name of sesame seeds, and
• an extensible monitoring agent written in Go, described here.

Abstract

Goma is a general purpose monitoring server/client. It can run multiple monitoring processes concurrently in a single server process.

Basically, goma does active (not passive) monitoring to objects like web sites or local OS, and kicks actions on failure and/or recovery.

Monitor processes are loaded from configuration files from a directory at start up, and can be added/started/stopped/removed dynamically via command-line and REST API.

Goma is designed with DevOps in mind. Developers can define and add monitors for their programs easily by putting a rule file to the configuration directory or by REST API. Monitoring rules and actions can be configured flexibly as goma can run arbitrary commands for them.

What goma is not

goma is not designed for metrics collection. Use other tools such as Zabbix for that purpose.

Architecture

goma can run multiple independent monitors in a single process.

A monitor consists of a probe, one or more actions, and optionally a filter. A monitor probes something periodically, and kick actions for failure when the probe, or filtered result of the probe, reports failures. The monitor kicks actions for recovery when the probe or filtered result of the probe reports recovery from failures.

A probe checks a system and report its status as a floating point number. All probes have timeouts; if a probe cannot return a value before the timeout, goma will cancel the probe.

A filter manipulates probe outputs; for example, a filter can produce moving average of probe outputs.

An action implements actions on failures and recoveries.

goma comes with a set of probes, actions, and filters. New probes, actions, and filters can be added as compiled-in plugins.

Pull requests to add new plugins are welcome!

Usage

Read USAGE.md for details.

Install

The latest officially supported Go version is recommended.

go install github.com/cybozu-go/goma/cmd/goma@latest

License

MIT

Documentation

Index

• Constants
• Variables
• func CreateMonitor(d *MonitorDefinition) (*monitor.Monitor, error)
• func FloatEquals(a, b float64) bool
• func GetBool(key string, m map[string]interface{}) (bool, error)
• func GetFloat(key string, m map[string]interface{}) (float64, error)
• func GetInt(key string, m map[string]interface{}) (int, error)
• func GetString(key string, m map[string]interface{}) (string, error)
• func GetStringList(key string, m map[string]interface{}) ([]string, error)
• func GetStringMap(key string, m map[string]interface{}) (map[string]string, error)
• func NewRouter() *mux.Router
• func Serve(addr string) error
• type List
• type MonitorDefinition
• type MonitorInfo

Constants

const (

	// Version may be used for REST API version checks in future.
	Version = "1.0"

	// VersionHeader is the HTTP request header for Version.
	VersionHeader = "X-Goma-Version"
)

const (
	// EPSILON is permitted error for float comparison.
	EPSILON = 0.00000001
)

Variables

var (
	ErrBadName      = errors.New("bad monitor name")
	ErrNoType       = errors.New("no type")
	ErrInvalidType  = errors.New("invalid type")
	ErrInvalidRange = errors.New("invalid min/max range")
	ErrNoKey        = errors.New("no key")
)

Errors for goma.

Functions

func CreateMonitor

func CreateMonitor(d *MonitorDefinition) (*monitor.Monitor, error)

CreateMonitor creates a monitor from MonitorDefinition.

func FloatEquals

func FloatEquals(a, b float64) bool

FloatEquals compares two floats allowing error within EPSILON.

func GetBool

func GetBool(key string, m map[string]interface{}) (bool, error)

GetBool extracts a boolean from TOML decoded map. If m[key] does not exist or is not a bool, non-nil error is returned.

func GetFloat

func GetFloat(key string, m map[string]interface{}) (float64, error)

GetFloat extracts a float from TOML decoded map. If m[key] does not exist or is not a float/int, non-nil error is returned.

func GetInt

func GetInt(key string, m map[string]interface{}) (int, error)

GetInt extracts an integer from TOML decoded map. If m[key] does not exist or is not an integer, non-nil error is returned.

func GetString

func GetString(key string, m map[string]interface{}) (string, error)

GetString extracts a string from TOML decoded map. If m[key] does not exist or is not a string, non-nil error is returned.

func GetStringList

func GetStringList(key string, m map[string]interface{}) ([]string, error)

GetStringList constructs a string list from TOML decoded map. If m[key] does not exist or is not a string list, non-nil error is returned.

func GetStringMap

func GetStringMap(key string, m map[string]interface{}) (map[string]string, error)

GetStringMap constructs a map[string]string from TOML decoded map. If m[key] does not exist or is not a string map, non-nil error is returned.

func NewRouter

func NewRouter() *mux.Router

NewRouter creates gorilla/mux *Router for REST API.

func Serve

func Serve(addr string) error

Serve runs REST API server until the global environment is canceled.

Types

type List

type List []*MonitorInfo

List represents JSON response for list command.

type MonitorDefinition

type MonitorDefinition struct {
	Name     string                   `toml:"name" json:"name"`
	Probe    map[string]interface{}   `toml:"probe" json:"probe"`
	Filter   map[string]interface{}   `toml:"filter" json:"filter,omitempty"`
	Actions  []map[string]interface{} `toml:"actions" json:"actions"`
	Interval int                      `toml:"interval" json:"interval,omitempty"`
	Timeout  int                      `toml:"timeout" json:"timeout,omitempty"`
	Min      float64                  `toml:"min" json:"min,omitempty"`
	Max      float64                  `toml:"max" json:"max,omitempty"`
}

MonitorDefinition is a struct to load monitor definitions. TOML and JSON can be used.

type MonitorInfo

type MonitorInfo struct {
	ID      int    `json:"id,string"`
	Name    string `json:"name"`
	Running bool   `json:"running"`
	Failing bool   `json:"failing"`
}

MonitorInfo represents status of a monitor. This is used by show and list commands.