Gossip cadence
이 콘텐츠는 아직 번역되지 않았습니다.
Cluster membership propagates via gossip — every
gossipIntervalMs, each member pushes its membership view to
one random reachable peer, which merges it and sends nothing
back. After a few rounds, the cluster converges.
const clusterOptions = ClusterOptions.create() .withHost(host) .withPort(port) .withSeeds(seeds) .withGossipIntervalMs(1_000);Cluster.join(system, clusterOptions); // defaultThe default is 1 second. Most clusters never need to change it.
What it controls
Section titled “What it controls”| Lower (e.g. 250 ms) | Default (1 s) | Higher (e.g. 5 s) |
|---|---|---|
| Faster convergence | Balanced | Slower convergence |
| More gossip messages | Modest traffic | Less traffic |
| Failure verdicts spread sooner | Standard | Failure verdicts spread later |
Gossip spreads a failure verdict; it does not make one. Each
node’s failure detector decides on its own tick, every
actor-ts.cluster.failure-detector.heartbeat-interval, from what
it has heard from each peer, and a lower gossip interval only gets
that verdict to the other nodes sooner. To detect failures
sooner, tune the failure detector
instead.
Concretely:
- A 5-node cluster at 1 s gossip → typical convergence after a join: 2-3 seconds.
- At 250 ms gossip: ~700 ms.
- At 5 s: ~10-15 seconds.
When to lower
Section titled “When to lower”Reduce below 1 second when:
- Latency-sensitive failover — singleton or sharding patterns where leader-change should propagate in sub-second. 500 ms is reasonable; 250 ms is aggressive.
- Small cluster (≤5 nodes) — gossip volume stays manageable.
- Quiet network — no other constraints; faster is fine.
When to raise
Section titled “When to raise”Increase above 1 second when:
- Large cluster (20+ nodes) — gossip volume grows O(N²) in the worst case across the cluster. 5 s slows convergence proportionally but reduces network noise significantly.
- Bandwidth-constrained network — cross-region or cross-WAN clusters where chatty gossip is wasteful.
- Stable cluster — rarely changes; faster gossip doesn’t help.
The bandwidth math
Section titled “The bandwidth math”Per-node gossip bandwidth roughly:
gossip_size × (1 / gossipIntervalMs) × peers_per_roundPer-cluster:
N × gossip_size × (1 / gossipIntervalMs)Where:
- gossip_size is ~100-500 bytes per member in the view. In a 10-node cluster, gossip messages run ~1-2 KB.
- peers_per_round is 1 (one random peer per tick).
- N = cluster size.
For a 50-node cluster at default 1 s gossip:
50 × ~5 KB × 1/s = 250 KB/s aggregateNegligible on a LAN. On a high-latency WAN at 10 ms RTT, each gossip round adds 10 ms of in-flight time — converges slower than you’d hope.
Interaction with other timings
Section titled “Interaction with other timings”Most of the cluster’s periodic work runs on timers of its own, so gossip cadence paces less than it may seem:
| Operation | Paced by | What gossip does for it |
|---|---|---|
Convergence after join | gossipIntervalMs | Direct — slower gossip = slower up. |
Promotion to up (leader actions) | gossipIntervalMs | Direct — it runs on every gossip tick, see below. |
| Unreachable detection | actor-ts.cluster.failure-detector.heartbeat-interval | Spreads the verdict to the other nodes. A gossip frame is a sign of life for the peer that sent it, not for the members it names, and carries no last-seen times. |
| Reaping unreachable members | actor-ts.cluster.failure-detector.heartbeat-interval | Nothing — the reaper is that same detector tick. |
| Sharding rebalance | actor-ts.sharding.rebalance-interval | Spreads the membership changes the coordinator reacts to. |
| DistributedPubSub topic propagation | actor-ts.cluster.pub-sub.gossip-interval (1 s) | Nothing — the mediator gossips on its own timer. |
| Receptionist service registry | actor-ts.cluster.receptionist.gossip-interval (1 s) | Nothing — the receptionist gossips on its own timer. |
A slower gossipIntervalMs slows how fast membership news
travels — joins, promotions and the verdicts each node’s detector
reaches — and nothing else in this table. Detection, rebalancing
and the two registries keep their own cadence; tune them through
their own keys. How the detector hears from a peer is on the
failure-detector page.
What does ride the gossip tick
Section titled “What does ride the gossip tick”Leader actions do. At the start of every gossip tick, before
that tick’s push, the leader promotes joining and weakly-up
members to up (once actor-ts.cluster.minimum-members-before-up
allows), and it does the same again after merging each gossip frame
it accepts. A promotion made on the tick leaves with that tick’s
push, so gossipIntervalMs is also how quickly a new member
reaches up. There is no separate leader-actions interval.
Every periodic cluster timer — gossip, heartbeats, failure
detection, tombstone pruning and the optional
actor-ts.cluster.publish-stats-interval sample — fires its first
tick one full interval after the node starts, never at once. Seed
contact is the exception: the first attempt is made at start, and
only the retries wait for actor-ts.cluster.seed-retry-interval.
Recommended values
Section titled “Recommended values”| Cluster size | Network | Recommended gossipIntervalMs |
|---|---|---|
| 3-5 nodes | LAN | 250-500 ms |
| 5-15 nodes | LAN | 1 s (default) |
| 15-50 nodes | LAN | 1-2 s |
| 50+ nodes | LAN | 2-5 s |
| Cross-region | WAN | 2-5 s |
| Latency-sensitive | LAN | 250-500 ms |
Where to next
Section titled “Where to next”- Cluster overview — what gossip carries.
- Joining and seeds — how the first gossip round bootstraps a member.
- Failure detector — its own heartbeat loop and detection tick, and what a frame from a peer counts for.
- Failure-detector tuning — the complementary tuning knob.
- Configuration — the HOCON key for this setting.
