Skip to content
Golang package for gossip based membership and failure detection
Go Other
  1. Go 99.5%
  2. Other 0.5%
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci ci: switch to using circleci (#203) Oct 7, 2019
internal/retry unflake some tests using the retry library and update some stale comm… Nov 25, 2019
test Only setup subnet on Mac OS X Sep 29, 2013
.gitignore Adding a gitignore file Sep 9, 2013
LICENSE Initial commit Sep 9, 2013
Makefile build: replicate some makefile changes from consul/serf and bump the … Nov 25, 2019
README.md build: replicate some makefile changes from consul/serf and bump the … Nov 25, 2019
alive_delegate.go Fix comment for NotifyAlive function (#146) Mar 12, 2019
awareness.go Adds a raw health score accessor. Jun 3, 2016
awareness_test.go Adds a raw health score accessor. Jun 3, 2016
broadcast.go Various changes to improve the cpu impact of TransmitLimitedQueue in … Dec 19, 2018
broadcast_test.go broadcast layer can now notify when a message is fully gossiped out Oct 2, 2013
config.go Allow a dead node's name to be taken by a new node (#189) May 15, 2019
conflict_delegate.go Adding support for a ConflictDelegate Feb 3, 2014
delegate.go Cleans up some formatting. Feb 23, 2017
event_delegate.go First pass at supporting meta data updates Jan 27, 2014
go.mod update miekg/dns to v1.1.26 (#214) Feb 13, 2020
go.sum update miekg/dns to v1.1.26 (#214) Feb 13, 2020
integ_test.go Unflake a bunch of tests. Oct 25, 2018
keyring.go Expose a method to validate a gossip encryption key before use. Jun 29, 2016
keyring_test.go Standardize 'primary key' in error messages Apr 9, 2014
logging.go Adds logging helper functions. Dec 16, 2015
logging_test.go
memberlist.go introduce new state: stateLeft (#213) Jan 31, 2020
memberlist_test.go
merge_delegate.go Allow returning custom error for merge delegate Feb 22, 2015
mock_transport.go Adds a basic network-free transport and some tests. Feb 23, 2017
net.go unflake some tests using the retry library and update some stale comm… Nov 25, 2019
net_test.go unflake some tests using the retry library and update some stale comm… Nov 25, 2019
net_transport.go added comments to the backoff delay constants in net_transport Dec 17, 2018
ping_delegate.go Adds a direct TCP fallback ping piplined with the UDP indirect pings. Jun 2, 2015
queue.go Various changes to improve the cpu impact of TransmitLimitedQueue in … Dec 19, 2018
queue_test.go Various changes to improve the cpu impact of TransmitLimitedQueue in … Dec 19, 2018
security.go Formatting adjustments Apr 3, 2014
security_test.go Rounded out keyring tests Apr 4, 2014
state.go introduce new state: stateLeft (#213) Jan 31, 2020
state_test.go introduce new state: stateLeft (#213) Jan 31, 2020
suspicion.go Use time.Since instead of time.Now().Sub Nov 9, 2017
suspicion_test.go Simplifies state logic by allowing zero values for k. May 31, 2016
tag.sh
todo.md Adding long-term todo list Oct 8, 2013
transport.go Update transport.go Nov 16, 2017
transport_test.go ci: switch to using circleci (#203) Oct 7, 2019
util.go Slightly speed up the node list shuffle using rand.Shuffle directly. Oct 25, 2018
util_test.go Adds support for joins to raw IPv6 addresses. Nov 10, 2017
z_test.go Unflake a bunch of tests. Oct 25, 2018

README.md

memberlist GoDoc CircleCI

memberlist is a Go library that manages cluster membership and member failure detection using a gossip based protocol.

The use cases for such a library are far-reaching: all distributed systems require membership, and memberlist is a re-usable solution to managing cluster membership and node failure detection.

memberlist is eventually consistent but converges quickly on average. The speed at which it converges can be heavily tuned via various knobs on the protocol. Node failures are detected and network partitions are partially tolerated by attempting to communicate to potentially dead nodes through multiple routes.

Building

If you wish to build memberlist you'll need Go version 1.2+ installed.

Please check your installation with:

go version

Usage

Memberlist is surprisingly simple to use. An example is shown below:

/* Create the initial memberlist from a safe configuration.
   Please reference the godoc for other default config types.
   http://godoc.org/github.com/hashicorp/memberlist#Config
*/
list, err := memberlist.Create(memberlist.DefaultLocalConfig())
if err != nil {
	panic("Failed to create memberlist: " + err.Error())
}

// Join an existing cluster by specifying at least one known member.
n, err := list.Join([]string{"1.2.3.4"})
if err != nil {
	panic("Failed to join cluster: " + err.Error())
}

// Ask for members of the cluster
for _, member := range list.Members() {
	fmt.Printf("Member: %s %s\n", member.Name, member.Addr)
}

// Continue doing whatever you need, memberlist will maintain membership
// information in the background. Delegates can be used for receiving
// events when members join or leave.

The most difficult part of memberlist is configuring it since it has many available knobs in order to tune state propagation delay and convergence times. Memberlist provides a default configuration that offers a good starting point, but errs on the side of caution, choosing values that are optimized for higher convergence at the cost of higher bandwidth usage.

For complete documentation, see the associated Godoc.

Protocol

memberlist is based on "SWIM: Scalable Weakly-consistent Infection-style Process Group Membership Protocol". However, we extend the protocol in a number of ways:

  • Several extensions are made to increase propagation speed and convergence rate.
  • Another set of extensions, that we call Lifeguard, are made to make memberlist more robust in the presence of slow message processing (due to factors such as CPU starvation, and network delay or loss).

For details on all of these extensions, please read our paper "Lifeguard : SWIM-ing with Situational Awareness", along with the memberlist source. We welcome any questions related to the protocol on our issue tracker.

You can’t perform that action at this time.