statuscheck

README

Concept

The statuscheck infrastructure plugin monitors the overall status of a CN-Infra based app and form partial statuses of agents plugins. The status is exposed to external clients via ETCD - datasync and HTTP, as shown in the following diagram:

For more detailed description see the godoc (especially doc.go).

Overall Agent Status

The overall Agent Status is aggregated from all Plugins' Status (logical AND for each Plugin Status success/error).

The agent's current overall status can be retrieved from ETCD from the following key: /vnf-agent/<agent-label>/check/status

$ etcdctl get /vnf-agent/<agent-label>/check/status/v1/agent
/vnf-agent/<agent-label>/check/status/v1/agent
{"build_version":"e059fdfcd96565eb976a947b59ce56cfb7b1e8a0","build_date":"2017-06-16.14:59","state":1,"start_time":1497617981,"last_change":1497617981,"last_update":1497617991}

To verify the agent status via HTTP (e.g. for Kubernetes liveness and readiness probes, use the /liveness and /readiness URLs:

$ curl -X GET http://localhost:9191/liveness
{"build_version":"e059fdfcd96565eb976a947b59ce56cfb7b1e8a0","build_date":"2017-06-16.14:59","state":1,"start_time":1497617981,"last_change":1497617981,"last_update":1497617991}
$ curl -X GET http://localhost:9191/readiness
{"build_version":"e059fdfcd96565eb976a947b59ce56cfb7b1e8a0","build_date":"2017-06-16.14:59","state":1,"start_time":1497617981,"last_change":1497617981,"last_update":1497617991}

To change the HTTP server port (default 9191), use the http-port option of the agent, e.g.:

$ vpp-agent -http-port 9090

Plugin Status

TODO: reword it's not clear what you mean. Plugin Status can be PUSHed by multiple plugins but there is possible PULL based approach when status check plugin periodically probes previously registered plugins.

To retrieve the current status of a plugin from ETCD, use the following key template: /vnf-agent/<agent-label>/check/status/v1/plugin/<PLUGIN_NAME>

For example, to retrieve the status of the GoVPP plugin, use:

$ etcdctl get /vnf-agent/<agent-label>/check/status/v1/plugin/GOVPP
/vnf-agent/<agent-label>/check/status/v1/plugin/GOVPP
{"state":2,"last_change":1496322205,"last_update":1496322361,"error":"VPP disconnected"}

PUSH Plugin Status:

PULL Plugins Status - PROBING:

Documentation

Overview

Package statuscheck defines the status report API for other CN-Infra plugins and implements the health status aggregator/exporter. Health status is collected from other plugins through the plugin status report API and aggregated and exported/exposed via ETCD or a REST API.

The API provides only two functions, one for registering the plugin for status change reporting and one for reporting status changes.

To register a plugin for providing status reports, use Register() function:

statuscheck.Register(PluginID, probe)

If probe is not nil, statuscheck will periodically probe the plugin state through the provided function. Otherwise, it is expected that the plugin itself will report state updates through ReportStateChange():

statuscheck.ReportStateChange(PluginID, statuscheck.OK, nil)

The default status of a plugin after registering is Init.

Index

• type AgentStatusReader
• type Deps
• type Plugin
  • func (p *Plugin) AfterInit() error
  • func (p *Plugin) Close() error
  • func (p *Plugin) GetAgentStatus() status.AgentStatus
  • func (p *Plugin) Init() error
  • func (p *Plugin) Register(pluginName core.PluginName, probe PluginStateProbe)
  • func (p *Plugin) ReportStateChange(pluginName core.PluginName, state PluginState, lastError error)
• type PluginState
• type PluginStateProbe
• type PluginStatusWriter

Types

type AgentStatusReader

type AgentStatusReader interface {
	// GetAgentStatus return current global operational state of the agent.
	GetAgentStatus() status.AgentStatus
}

AgentStatusReader allows to lookup agent status by other plugins

type Deps

type Deps struct {
	Log        logging.PluginLogger       //inject
	PluginName core.PluginName            //inject
	Transport  datasync.KeyProtoValWriter //inject optional
}

Deps is here to group injected dependencies of plugin to not mix with other plugin fields.

type Plugin

type Plugin struct {
	Deps
	// contains filtered or unexported fields
}

Plugin struct holds all plugin-related data.

func (*Plugin) AfterInit

func (p *Plugin) AfterInit() error

AfterInit is called by the Agent Core after all plugins have been initialized.

func (*Plugin) Close

func (p *Plugin) Close() error

Close is called by the Agent Core when it's time to clean up the plugin.

func (*Plugin) GetAgentStatus

func (p *Plugin) GetAgentStatus() status.AgentStatus

GetAgentStatus return current global operational state of the agent.

func (*Plugin) Init

func (p *Plugin) Init() error

Init is the plugin entry point called by the Agent Core.

func (*Plugin) Register

func (p *Plugin) Register(pluginName core.PluginName, probe PluginStateProbe)

Register a plugin for status change reporting.

func (*Plugin) ReportStateChange

func (p *Plugin) ReportStateChange(pluginName core.PluginName, state PluginState, lastError error)

ReportStateChange can be used to report a change in the status of a previously registered plugin.

type PluginState

type PluginState string

PluginState is a data type used to describe the current operational state of a plugin.

const (
	// Init state means that the initialization of the plugin is in progress.
	Init PluginState = "init"
	// OK state means that the plugin is healthy.
	OK PluginState = "ok"
	// Error state means that some error has occurred in the plugin.
	Error PluginState = "error"
)

type PluginStateProbe

type PluginStateProbe func() (PluginState, error)

PluginStateProbe defines parameters of a function used for plugin state probing.

type PluginStatusWriter

type PluginStatusWriter interface {
	// put registers a plugin for status change reporting.
	Register(pluginName core.PluginName, probe PluginStateProbe)

	// ReportStateChange can be used to report a change in the status of a previously registered plugin.
	ReportStateChange(pluginName core.PluginName, state PluginState, lastError error)
}

PluginStatusWriter allows to register & write plugin status by other plugins