DOCSEARCHbyAlgolia
Submit Docs

hashicorp/memberlist

repository·master·Indexed 26 days ago

https://github.com/hashicorp/memberlist

A Go library for managing cluster membership and node failure detection using a gossip-based protocol. It provides eventually consistent membership, tunable convergence speeds, and robustness against network partitions via 'Lifeguard' extensions. Features include pre-configured settings for LAN, WAN, and local environments, support for custom data via the Delegate interface, and node health tracking through the awareness type.

Tokens
7.6K
Snippets
13
Records
55
Agent score
87%

What's inside memberlist

  1. Migrate from `armon/go-metrics` to `hashicorp/go-metrics`

    master

    Emitting metrics to armon/go-metrics is deprecated. To migrate to hashicorp/go-metrics, follow these steps:

    1. Update libraries that consume armon/go-metrics to consume hashicorp/go-metrics/compat instead (this typically only requires changing import statements).
    2. Update your application's dependencies to versions that use the compatibility layer.
    3. Update your application code:
      • Replace all imports of github.com/armon/go-metrics with github.com/hashicorp/go-metrics.
      • Configure your build system to include the hashicorpmetrics build tag.

    Once the default behavior of the library switches to hashicorp/go-metrics (expected mid-2025), you can remove the hashicorpmetrics build tag.

  2. Configure metrics emission via build tags

    master

    The memberlist library supports emitting metrics through either github.com/armon/go-metrics or github.com/hashicorp/go-metrics. You control which library is used by specifying a Go build tag during compilation.

    • Use the armonmetrics tag to route metrics to armon/go-metrics (this is the default behavior).
    • Use the hashicorpmetrics tag to route metrics to hashicorp/go-metrics.

  3. Initialize memberlist with default configurations

    master

    Memberlist provides three pre-configured *Config objects optimized for different network environments. Use these as a starting point to avoid manual tuning of timeouts and gossip intervals.

    • DefaultLANConfig(): Optimized for local area networks. Uses conservative values for high convergence at the cost of higher bandwidth.
    • DefaultWANConfig(): Optimized for wide area networks. Increases timeouts and intervals to account for higher latency and jitter.
    • DefaultLocalConfig(): Optimized for local loopback environments. Uses very aggressive (short) timeouts and intervals.

  4. Initialize and use memberlist in Go

    master

    To use memberlist, create a new instance using memberlist.Create() with a configuration object (such as memberlist.DefaultLocalConfig()). You can then join an existing cluster by providing a list of known member addresses via the Join() method. Once initialized, memberlist manages membership and failure detection in the background. You can retrieve the current list of cluster members using Members().

    /* 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.

  5. NetTransportConfig

    master

    Configuration struct for initializing a NetTransport.

    FieldTypeDescription
    BindAddrs[]stringA list of IP addresses to bind to for both TCP and UDP communications. At least one address is required.
    BindPortintThe port to listen on for each address in BindAddrs. If 0, a port is automatically assigned.
    Logger*log.LoggerA logger for operator messages.
    MetricLabels[]metrics.LabelOptional labels applied to all metrics emitted by this transport.

  6. Use ChannelEventDelegate to receive events via a channel

    master

    If you prefer receiving membership events through a Go channel rather than direct method calls, use ChannelEventDelegate.

    Initialize the delegate with a write-only channel of type chan<- NodeEvent.

    Warning: You must process events from the channel in a timely manner. The ChannelEventDelegate will block until an event can be sent to the channel, which can stall the memberlist internal processes if the channel buffer is full or the consumer is slow.

  8. Manage node health awareness with the awareness type

    master

    The awareness type manages a metric for tracking the estimated health of a local node. Health is defined by the node's ability to respond in a soft real-time manner.

    Key behaviors:

    • Score Range: The score is constrained between 0 and max - 1.
    • Health Interpretation: Lower values indicate a healthier node; 0 is the minimum (healthiest) value.
    • Timeout Scaling: You can scale durations based on the current health score. Lower health (higher scores) results in longer timeouts.
    • Metrics: Changes to the score are emitted as a gauge metric with the name memberlist.health.score.

  10. Gracefully exit a cluster with Leave()

    master

    Use Leave(timeout time.Duration) to broadcast a leave message to the cluster. This informs other nodes that this node is intentionally exiting, allowing them to update their membership state without waiting for failure detection timeouts.

    This method blocks until the leave message is successfully broadcasted to at least one member of the cluster, or until the specified timeout is reached. It does not shut down the background network listeners; use Shutdown() for that.

  11. Implement NodeAwareTransport for node-specific addressing

    master

    If your transport needs to handle addressing via a structured Address type (which includes an optional node name) rather than just a raw string, implement the NodeAwareTransport interface. This extends the standard Transport interface.

    Additional methods:

    • WriteToAddress(b []byte, addr Address) (time.Time, error)
    • DialAddressTimeout(addr Address, timeout time.Duration) (net.Conn, error)
    type NodeAwareTransport interface {
	Transport
	WriteToAddress(b []byte, addr Address) (time.Time, error)
	DialAddressTimeout(addr Address, timeout time.Duration) (net.Conn, error)
}

  12. Use MockNetwork to simulate memberlist networking

    master

    The MockNetwork type acts as a factory for creating MockTransport instances. It automatically wires these transports together so they can communicate with each other using unique addresses and names, making it ideal for testing or simulating cluster behavior in a single process.

    To use it, initialize a MockNetwork and call NewTransport(name) to generate connected nodes.