{
  "docVersion": 1,
  "id": "blog-hotkey-0001",
  "name": "Hot shard — one key melts one machine",
  "purpose": "A perfectly balanced hash ring loses to a zipfian workload: one celebrity key routes 95% of traffic to shard 3. Mitigations: near-cache for reads, key salting for writes, bounded-load rebalancing, whale isolation.",
  "nodes": {
    "traffic": {
      "type": "users",
      "label": "1M readers",
      "x": 20,
      "y": 300,
      "runtime": "zipfian — one post is viral"
    },
    "router": {
      "type": "lb",
      "label": "Shard Router",
      "x": 290,
      "y": 300,
      "runtime": "consistent hashing",
      "notes": "The hash is perfect. The workload isn't — hashing spreads KEYS evenly, not the traffic OF one key."
    },
    "cache": {
      "type": "cache",
      "label": "Hot-key Cache",
      "x": 610,
      "y": 80,
      "color": "green",
      "runtime": "mitigation 1 · absorbs reads",
      "patterns": [
        "replicated"
      ],
      "notes": "Detect top-K keys, serve them from memory with TTL jitter and stampede protection. Readers never reach shard 3."
    },
    "s1": {
      "type": "database",
      "label": "Shard 1",
      "x": 940,
      "y": 100,
      "color": "green",
      "runtime": "cpu 2%"
    },
    "s2": {
      "type": "database",
      "label": "Shard 2",
      "x": 940,
      "y": 300,
      "color": "green",
      "runtime": "cpu 3%  ·  +salted key #0..#7",
      "notes": "Mitigation 2: the hot key's WRITES are split into key#0..#15, hashed across every shard; reads merge the pieces."
    },
    "s3": {
      "type": "database",
      "label": "Shard 3",
      "x": 940,
      "y": 500,
      "color": "red",
      "runtime": "cpu 100% — MELTING",
      "notes": "Owns the celebrity key. Adding shards changes nothing: this key still hashes here."
    }
  },
  "edges": {
    "e1": {
      "from": "traffic",
      "to": "router",
      "fromSide": "right",
      "toSide": "left",
      "label": "reads + writes",
      "animated": true
    },
    "e2": {
      "from": "router",
      "to": "s1",
      "fromSide": "right",
      "toSide": "left",
      "label": "2%"
    },
    "e3": {
      "from": "router",
      "to": "s2",
      "fromSide": "right",
      "toSide": "left",
      "label": "3%"
    },
    "e4": {
      "from": "router",
      "to": "s3",
      "fromSide": "right",
      "toSide": "left",
      "label": "95% — ONE key",
      "color": "red",
      "animated": true,
      "flowSpeed": "fast"
    },
    "e5": {
      "from": "router",
      "to": "cache",
      "fromSide": "top",
      "toSide": "left",
      "label": "hot-key reads served here",
      "color": "green",
      "style": "dashed"
    },
    "e6": {
      "from": "cache",
      "to": "s3",
      "fromSide": "right",
      "toSide": "top",
      "label": "misses only · ~1%",
      "style": "dashed"
    }
  },
  "boxes": {
    "b1": {
      "x": 900,
      "y": 20,
      "w": 320,
      "h": 620,
      "label": "hash ring — perfectly balanced by KEY COUNT",
      "color": "blue",
      "opacity": 0.04
    }
  },
  "texts": {
    "t1": {
      "x": 20,
      "y": 480,
      "text": "the trap: 'just add shards' — a perfect hash\nputs each KEY on one shard, so the key that\ncarries 30% of all traffic puts 30% of all\ntraffic on one machine. forever.",
      "color": "red",
      "size": 12
    },
    "t2": {
      "x": 20,
      "y": 620,
      "text": "the mitigation ladder:\n1. cache the hot key (kills read heat)\n2. salt the key: write key#0..#15, merge on read (kills write heat)\n3. bounded-load hashing / range split (caps any shard at c×avg)\n4. isolate the whale: dedicated shard or cell + per-tenant quota",
      "color": "green",
      "size": 12
    }
  },
  "meta": {
    "createdAt": "2026-07-16T09:00:00.000Z",
    "modifiedAt": "2026-07-16T09:00:00.000Z"
  }
}