README
¶
scuttlebutt is a Go library for distributed cluster membership and failure detection via an efficient reconciliation and flow-control anti-entropy gossip protocol.
The failure detection mechanism is based on the phi accrual failure detector used to mark failing nodes and remove them from the membership.
Usage
// Create scuttlebutt instance with a default LAN configuration
sb, err := scuttlebutt.NewScuttlebutt(scuttlebutt.DefaultLANConfig(), map[string]string{"key1": "value1"})
if err != nil {
panic("Failed to create scuttlebutt instance: " + err.Error())
}
//Join cluster via a seed node
err = sb.Join([]string{"1.2.3.5:9111"})
if err != nil {
panic("Failed to join cluster: " + err.Error())
}
// Get cluster state and check live and dead nodes
for _, node := range sb.State().GetLiveNodes() {
fmt.Printf("Live Node: %s %s\n", node.ID, node.GossipPublicAddress)
}
for _, node := range sb.State().GetDeadNodes() {
fmt.Printf("Dead Node: %s %s\n", node.ID, node.GossipPublicAddress)
}
// scuttlebutt will maintain node membership in the background. Events can be
// used as notifications when members join, leave or update their metadata state.
Failure detector can be configured in order to tune state propagation and convergence times. Higher convergence has a cost of higher bandwidth usage.
For complete documentation, see the associated Godoc.
References
- ScuttleButt paper: https://www.cs.cornell.edu/home/rvr/papers/flowgossip.pdf
- Phi Accrual error detection: https://www.researchgate.net/publication/29682135_The_ph_accrual_failure_detector
Documentation
¶
Overview ¶
scuttlebutt is a library for distributed cluster membership and failure detection via an efficient reconciliation and flow-control anti-entropy gossip protocol.
The failure detection mechanism is based on the phi accrual failure detector used to mark failing nodes and remove them from the membership.
The speed of convergence can be tuned via the phi accrual failure detector.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ChannelEvent ¶
type ChannelEvent struct {
Ch chan<- NodeEvent
}
ChannelEvent is used to receive events, this channel should process events without blocking in a timely manner.
func (*ChannelEvent) NotifyDead ¶
func (c *ChannelEvent) NotifyDead(n Node)
func (*ChannelEvent) NotifyLive ¶
func (c *ChannelEvent) NotifyLive(n Node)
func (*ChannelEvent) NotifyUpdate ¶
func (c *ChannelEvent) NotifyUpdate(n Node)
type Config ¶
type Config struct {
//ID of the cluster this node is part.
ClusterID string
//Unique node definition.
Node Node
//GossipNodes is the number of random nodes gossiping per GossipInterval
GossipNodes int
//Interval between sending gossip messages.
GossipInterval time.Duration
//Address and port to listen on.
ListenAddr string
//See FailureDetectorConfig.
FailureDetectorConfig *FailureDetectorConfig
//Define a custom logger. If Logger is not set it will use os.Stderr
//instead.
Logger *log.Logger
//Events for receiving notifications via callback mechanisms. For Events,
//see the NotifyEvent interface.
Events NotifyEvent
//Control message compression.
EnableCompression bool
//Enable message-level encryption. The value should be either 16, 24, or
//32 bytes to select AES-128, AES-192, or AES-256.
SecretKey []byte
}
func DefaultLANConfig ¶
func DefaultLANConfig() *Config
DefaultLANConfig returns a configuration suitable for most LAN environments. It creates a unique Node ID based on the hostname of the node and a timestamp. It listens to all interfaces on port 9111 and the ClusterID used is "default".
func DefaultWANConfig ¶
func DefaultWANConfig() *Config
DefaultWANConfig returns a configuration suitable for WAN environments based on the DefaultLANConfig.
type FailureDetectorConfig ¶
type FailureDetectorConfig struct {
//The threshold used by the instance that triggers suspicious level.
//Above this threshold value a node is flagged as dead.
//The duration is GossipInterval + AcceptableHeartbeatPause + Threshold_Adjustment
PhiThreshold float64
//Sampling window size
SamplingWindowSize uint
//Minimum standard deviation used in the calculation of phi.
//Too low value might result in too much sensitivity for sudden, but
//normal, deviations in heartbeat inter arrival times.
MinStdDeviation time.Duration
//Number of lost / delayed heartbeat before considering an anomaly.
//This margin is important to be able to survive sudden, occasional pauses
//in heartbeat arrivals, due to for example GC or network drop or instance
//high load.
AcceptableHeartbeatPause time.Duration
//First heartbeat duration used on startup when no previous heartbeat exists.
FirstHeartbeatEstimate time.Duration
//Grace period after which a dead node can be removed from the cluster list.
DeadNodeGracePeriod time.Duration
}
func FailureDetectorDefaultConfig ¶
func FailureDetectorDefaultConfig() *FailureDetectorConfig
FailureDetectorDefaultConfig returns a default config
type Node ¶
type Node struct {
//The name of the node which must be unique in the cluster.
ID string
//Gossip public address to advertise to other cluster members.
GossipPublicAddress string
}
Node represents a node in the cluster
type NodeEvent ¶
type NodeEvent struct {
Event NodeEventType
Node Node
}
NodeEvent is an event related to node activity
type NodeEventType ¶
type NodeEventType int
NodeEventType are the types that can be sent over the ChannelEvent
const ( NodeLive NodeEventType = iota NodeDead NodeUpdate )
type NotifyEvent ¶
type NotifyEvent interface {
//NotifyLive is invoked when a node becomes live
NotifyLive(Node)
//NotifyDead is invoked when a node becomes dead
NotifyDead(Node)
//NotifyUpdate is invoked when a node updates it's meta
NotifyUpdate(Node)
}
NotifyEvent is used to receive notifications about nodes joining, updating their metadata and leaving the cluster.
type Scuttlebutt ¶
type Scuttlebutt struct {
// contains filtered or unexported fields
}
Scuttlebutt is a scuttlebutt instance returned by NewScuttlebutt
func NewScuttlebutt ¶
func NewScuttlebutt(config *Config, metadata map[string]string) (*Scuttlebutt, error)
NewScuttlebutt creates a Scuttlebutt instance based on a provided config
func (*Scuttlebutt) Join ¶
func (sb *Scuttlebutt) Join(seedNodes []string) error
Join is used to join a cluster by contacting all given hosts
func (*Scuttlebutt) Set ¶
func (sb *Scuttlebutt) Set(key, value string) error
Set key-value metadata
func (*Scuttlebutt) Shutdown ¶
func (sb *Scuttlebutt) Shutdown() error
Shutdown will stop all network activity
Source Files