API Design

Production at Scale · Simulator 03

Consistent hashing & hot keys

Consistent hashing places nodes on a ring so adding or removing one remaps only 1/(N+1) of keys — instead of nearly everything. But with few virtual nodes per server, a lucky cluster of ring points can concentrate load. Drag the sliders to see how vnodes smooth the distribution, and watch what a single hot key does to the busiest node. This is the model behind the load-balancing lesson, made live.

InteractiveDrag the slidersModels rel-08

Each bar is one node's share of total load. The red bar is the hottest node. The dashed line marks average load (1/N). A hot key adds extra load to whichever node owns it.

What's happening — the math

Keys are hashed onto a ring. Each node owns vnodes equally spaced points; a key goes to the next point clockwise. Adding a node only steals keys from its immediate neighbours:

# Remap fraction when adding 1 node to a cluster of N
remap_consistent  ≈  1 / (N + 1)    # only the new node's ring neighbours move
remap_modulo      ≈  (N) / (N + 1)  # nearly everything remaps with hash % N

# Load imbalance (max / avg) improves with more virtual nodes
imbalance  ∝  1 / √vnodes           # std-dev of arc lengths shrinks with more points

# Hot key: one key carries hot% of all traffic; it lands on one node
hot_node_load  =  (node_key_share + hot%) / total_load

With 1 vnode per node the ring is bumpy — one arc might be 3× the average. With 150 vnodes the worst node rarely exceeds 1.2× average. The hot-key problem is orthogonal: no amount of vnodes helps if a single object (a viral video, a trending product) is fetched millions of times — that key always lands on one node. The fix is key-level sharding or application-level replication.

✅ Try this

1. Set N = 5, vnodes = 1 → imbalance is often 2–4×; one node dominates. 2. Raise vnodes to 150 → bars level out, imbalance drops below 1.2×. 3. Now add hotKey = 40% with N = 10, vnodes = 150 → one bar turns red and towers over the rest, even though hashing is otherwise perfect. 4. Raise N from 5 → 6 and watch "keys remapped" — it's always close to 1/(N+1) regardless of vnodes.

⚠️ Modeled, not measured

This is a first-principles model using 2000 sample keys with a deterministic integer hash. Real consistent-hashing libraries (e.g. ketama, Amazon Dynamo) use cryptographic hashes and may differ in exact distribution. The hot-key load is additive and goes to a fixed node for illustration; in production the hot key's node is unpredictable. Treat the numbers as illustrative.

Sources & further reading