Documentation
¶
Index ¶
- Variables
- func Run(plugins map[string]Plugin, configPath, tombStonePath string, ...) error
- func Truncate(s string, limit int) string
- type Alert
- type AlertDetails
- type Check
- type CheckListener
- type CheckSettings
- type CheckState
- type CheckTombStone
- type Fact
- type Group
- type GrpcServer
- func (s *GrpcServer) GetCheck(_ context.Context, name *api.CheckName) (*api.Check, error)
- func (s *GrpcServer) GetChecks(_ context.Context, _ *api.Empty) (*api.CheckList, error)
- func (s *GrpcServer) Results(_ *api.Empty, rs api.GoPlum_ResultsServer) error
- func (s *GrpcServer) ResumeCheck(_ context.Context, name *api.CheckName) (*api.Check, error)
- func (s *GrpcServer) Start() error
- func (s *GrpcServer) Stop()
- func (s *GrpcServer) SuspendCheck(_ context.Context, name *api.CheckName) (*api.Check, error)
- type LongRunning
- type Plugin
- type Plum
- func (p *Plum) AddCheckListener(listener CheckListener)
- func (p *Plum) AlertsMatching(names []string) []Alert
- func (p *Plum) RaiseAlerts(c *ScheduledCheck, previousState CheckState)
- func (p *Plum) ReadConfig(path string) error
- func (p *Plum) RegisterPlugin(name string, plugin Plugin)
- func (p *Plum) RegisterPlugins(plugins map[string]Plugin)
- func (p *Plum) RemoveCheckListener(listener CheckListener)
- func (p *Plum) RestoreState(tombStonePath string) error
- func (p *Plum) Run(ctx context.Context)
- func (p *Plum) RunCheck(c *ScheduledCheck)
- func (p *Plum) SaveState(tombStonePath string) error
- func (p *Plum) Suspend(checkName string) *ScheduledCheck
- func (p *Plum) Unsuspend(checkName string) *ScheduledCheck
- type Result
- type ResultHistory
- type ScheduledCheck
- type Stateful
- type TombStone
- type Validator
Constants ¶
This section is empty.
Variables ¶
var DefaultSettings = CheckSettings{ Alerts: []string{"*"}, Interval: time.Second * 30, Timeout: time.Second * 20, GoodThreshold: 2, FailingThreshold: 2, }
Functions ¶
func Run ¶
func Run(plugins map[string]Plugin, configPath, tombStonePath string, signals <-chan os.Signal) error
Run creates a new instance of Plum, registers plugins and loads configuration, and starts the main loop. It blocks until a value is received on signals, then saves state and cleans up. An error is returned if goplum couldn't start. It is expected that flag.Parse has been called prior to calling this method.
Types ¶
type Alert ¶
type Alert interface {
// Send dispatches an alert in relation to the given check event.
Send(details AlertDetails) error
}
Alert defines the method to inform the user of a change to a service - e.g. when it comes up or goes down.
Alerts may also implement the Validator interface to validate their arguments when configured.
type AlertDetails ¶
type AlertDetails struct {
// Text is a short, pre-generated message describing the alert.
Text string `json:"text"`
// Name is the name of the check that transitioned.
Name string `json:"name"`
// Type is the type of check involved.
Type string `json:"type"`
// Config is the user-supplied parameters to the check, with any secrets redacted.
Config any `json:"config"`
// LastResult is the most recent result that caused the transition.
LastResult *Result `json:"last_result"`
// PreviousState is the state this check was previously in.
PreviousState CheckState `json:"previous_state"`
// NewState is the state this check is now in.
NewState CheckState `json:"new_state"`
// IsReminder indicates that this alert is a periodic reminder for an ongoing failure, not a new state change.
IsReminder bool `json:"is_reminder"`
// Link is the URL configured for the check with its placeholders expanded, or empty if there isn't one.
Link string `json:"link,omitempty"`
}
AlertDetails contains information about a triggered alert
func (AlertDetails) TextWithLink ¶ added in v1.3.0
func (d AlertDetails) TextWithLink(limit int) string
TextWithLink returns Text, followed by Link on its own line if there is one.
If limit is positive the result is at most limit characters. Text is shortened to make room for Link, unless that would leave too little of it, in which case Link is omitted.
type Check ¶
type Check interface {
// Execute performs the actual check to see if the service is up or not.
// It should block until a result is available or the passed context is cancelled.
Execute(ctx context.Context) Result
}
Check defines the method to see if a service is up or not. The check is persistent - its Execute method will be called repeatedly over the lifetime of the application.
Checks may also implement the Validator interface to validate their arguments when configured.
Exported fields that hold secrets (passwords, tokens, etc) should be tagged with `redact:"true"`, so their values are not included in alerts. String fields holding URLs that may embed credentials should instead be tagged with `redact:"url"`, so only the password is removed.
type CheckListener ¶
type CheckListener func(*ScheduledCheck, Result)
type CheckSettings ¶
type CheckSettings struct {
Alerts []string
Groups []string
Interval time.Duration
Timeout time.Duration
Reminder time.Duration
GoodThreshold int `config:"good_threshold"`
FailingThreshold int `config:"failing_threshold"`
Link string
}
func (CheckSettings) Copy ¶
func (c CheckSettings) Copy() CheckSettings
type CheckState ¶
type CheckState int
CheckState describes the state of a check.
const ( // StateIndeterminate indicates that it's not clear if the check passed or failed, e.g. it hasn't run yet. StateIndeterminate CheckState = iota // StateGood indicates the service is operating correctly. StateGood // StateFailing indicates a problem with the service. StateFailing )
func (CheckState) MarshalJSON ¶
func (c CheckState) MarshalJSON() ([]byte, error)
func (CheckState) String ¶
func (c CheckState) String() string
String returns an english, lowercase name for the state.
func (*CheckState) UnmarshalJSON ¶
func (c *CheckState) UnmarshalJSON(val []byte) error
type CheckTombStone ¶
type CheckTombStone struct {
LastRun time.Time `json:"LastRun"`
Settled bool `json:"Settled"`
State CheckState `json:"State"`
Suspended bool `json:"Suspended"`
LastAlertTime time.Time `json:"last_alert_time,omitzero"`
History ResultHistory `json:"History"`
PluginState json.RawMessage `json:"plugin_state,omitempty"`
}
type Fact ¶
type Fact string
Fact defines a type of information that may be returned in a Result.
Fact names should consist of the package name that defines them, a '#' character, and then a short, human-friendly name for the metric in `snake_case`.
var ( // ResponseTime denotes the length of time it took for a service to respond to a request. // Its value should be a time.Duration. ResponseTime Fact = "chameth.com/goplum#response_time" // CheckTime indicates how long the entire check took to invoke. Its value should be a time.Duration. CheckTime Fact = "chameth.com/goplum#check_time" )
type GrpcServer ¶
type GrpcServer struct {
api.UnimplementedGoPlumServer
// contains filtered or unexported fields
}
func NewGrpcServer ¶
func NewGrpcServer(plum *Plum) *GrpcServer
func (*GrpcServer) Results ¶
func (s *GrpcServer) Results(_ *api.Empty, rs api.GoPlum_ResultsServer) error
func (*GrpcServer) ResumeCheck ¶
func (*GrpcServer) Start ¶
func (s *GrpcServer) Start() error
Start begins serving the API in the background. If the certificates can't be loaded then goplum runs without an API, and no error is returned.
func (*GrpcServer) Stop ¶
func (s *GrpcServer) Stop()
func (*GrpcServer) SuspendCheck ¶
type LongRunning ¶
type LongRunning interface {
// Timeout specifies the upper-bound for how long the check will take.
Timeout() time.Duration
}
LongRunning is implemented by checks that intentionally run for a long period of time. Checks that implement this interface won't be subject to user-defined timeouts.
type Plugin ¶
Plugin is the API between plugins and the core. Plugins are compiled into the binary and registered by name with Plum.RegisterPlugin (or passed to Run). A single instance is used for the lifetime of a Plum; if the plugin has configurable settings it should be registered as a pointer so they can be populated.
The Check and Alert funcs should provide new instances of the named type, or nil if such a type does not exist. Exported fields of the checks and alerts will then be populated according to the user's config, and the Validate() func will be called.
type Plum ¶
type Plum struct {
Alerts map[string]Alert
Checks map[string]*ScheduledCheck
Groups map[string]*Group
// contains filtered or unexported fields
}
func (*Plum) AddCheckListener ¶
func (p *Plum) AddCheckListener(listener CheckListener)
func (*Plum) AlertsMatching ¶
AlertsMatching returns the alerts whose names match any of the given names, which may contain '*' wildcards. Names of "-" are ignored, so that a check can be configured to send no alerts.
func (*Plum) RaiseAlerts ¶
func (p *Plum) RaiseAlerts(c *ScheduledCheck, previousState CheckState)
func (*Plum) ReadConfig ¶
func (*Plum) RegisterPlugin ¶
func (*Plum) RegisterPlugins ¶
func (*Plum) RemoveCheckListener ¶
func (p *Plum) RemoveCheckListener(listener CheckListener)
func (*Plum) RestoreState ¶
func (*Plum) Run ¶
Run schedules checks until ctx is cancelled, then waits for any running checks and alerts to finish. Cancelling ctx also interrupts the running checks, and their results are discarded.
func (*Plum) RunCheck ¶
func (p *Plum) RunCheck(c *ScheduledCheck)
func (*Plum) Suspend ¶
func (p *Plum) Suspend(checkName string) *ScheduledCheck
Suspend sets the check with the given name to be suspended (i.e., it won't run until unsuspended). Returns the modified check, or nil if the check didn't exist.
func (*Plum) Unsuspend ¶
func (p *Plum) Unsuspend(checkName string) *ScheduledCheck
Unsuspend sets the check with the given name to be resumed (i.e., it will run normally). Returns the modified check, or nil if the check didn't exist.
type Result ¶
type Result struct {
// State gives the current state of the service.
State CheckState `json:"state"`
// Time is the time the check was performed.
Time time.Time `json:"time"`
// Detail is an short, optional explanation of the current state.
Detail string `json:"detail,omitempty"`
// Facts provides details about the check and/or the remote service, such as the response time or version.
Facts map[Fact]any `json:"facts,omitempty"`
}
Result contains information about a check that was performed.
func FailingResult ¶
FailingResult creates a new result indicating the service is in a bad state.
func GoodResult ¶
func GoodResult() Result
GoodResult creates a new result indicating the service is in a good state.
func IndeterminateResult ¶
IndeterminateResult creates a new result indicating the check wasn't able to compute a state.
type ResultHistory ¶
type ResultHistory [10]*Result
func (ResultHistory) State ¶
func (h ResultHistory) State(thresholds map[CheckState]int) CheckState
type ScheduledCheck ¶
type ScheduledCheck struct {
Name string
Type string
Config *CheckSettings
Check Check
LastRun time.Time
LastAlertTime time.Time
Scheduled bool
Settled bool
State CheckState
Suspended bool
History ResultHistory
}
func (*ScheduledCheck) AddResult ¶
func (c *ScheduledCheck) AddResult(result *Result) ResultHistory
func (*ScheduledCheck) LastResult ¶
func (c *ScheduledCheck) LastResult() *Result
func (*ScheduledCheck) Remaining ¶
func (c *ScheduledCheck) Remaining() time.Duration
type Stateful ¶
Stateful is implemented by checks that keep local state that should be persisted across restarts.
type TombStone ¶
type TombStone struct {
Time time.Time `json:"Time"`
Checks map[string]CheckTombStone `json:"Checks"`
}
func LoadTombStone ¶
func NewTombStone ¶
func NewTombStone(checks map[string]*ScheduledCheck) *TombStone

Discord
E-mail
Microsoft Teams
Phone call (via Twilio)
Pushover
Slack
SMS (via Twilio)
Webhook