A shorter timeout makes a failure detector wrong more often

# /// script
# requires-python = ">=3.10"
# ///
# Copyright (c) 2026 Aayush Sharma · SPDX-License-Identifier: MIT
# https://thedataengineering.com/lab-code/LICENSE.txt
"""A shorter timeout makes a failure detector wrong more often.

A node heartbeats every 100 ms over a network that is usually fast and
sometimes very slow. The monitor suspects the node whenever no heartbeat has
arrived within the timeout. Measured: false suspicions per heartbeat for a
range of timeouts, and the time to detect a real crash.
"""
import argparse, json, random

p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
p.add_argument("--interval-ms", type=float, default=100, help="Heartbeat interval.")
p.add_argument("--slow-share", type=float, default=0.05, help="Share of heartbeats delayed 100-700 ms (the rest take 1-20 ms).")
p.add_argument("--timeouts", type=lambda s: [float(v) for v in s.split(",")], default=[150, 200, 300, 500, 700, 1000, 3000, 10000],
               help="Timeouts to try, in ms, comma-separated.")
p.add_argument("--beats", type=int, default=100_000, help="Heartbeats per timeout.")
p.add_argument("--crashes", type=int, default=1000, help="Simulated crashes per timeout, for the detection time.")
p.add_argument("--seed", type=int, default=0, help="Random seed.")
p.add_argument("--json", help="Also write the results to this JSON file.")
args = p.parse_args()
random.seed(args.seed)

def delay():
    return random.uniform(1, 20) if random.random() >= args.slow_share else random.uniform(100, 700)

def false_suspicions(timeout):
    last_arrival, count = 0.0, 0
    for i in range(1, args.beats + 1):
        arrival = i * args.interval_ms + delay()
        if arrival - last_arrival > timeout:
            count += 1
        last_arrival = max(last_arrival, arrival)
    return count / args.beats

def detection_time(timeout):
    """The node crashes at a random moment; the monitor notices `timeout` after the last heartbeat arrived."""
    total = 0.0
    for _ in range(args.crashes):
        crash = random.uniform(0, args.interval_ms)          # time since the last heartbeat was sent
        last_arrival = delay()                                # that heartbeat's arrival, relative to its send
        total += max(last_arrival + timeout - crash, 0)
    return total / args.crashes

rows = []
for t in args.timeouts:
    fs, det = false_suspicions(t), detection_time(t)
    rows.append({"timeout_ms": t, "false_suspicion_pct": fs * 100, "detect_ms": det})
    print(f"timeout {t:>6.0f} ms: false suspicions {fs:8.3%} of heartbeats   real crash detected after {det:7.0f} ms")

if args.json:
    with open(args.json, "w") as f:
        json.dump({"tables": {"timeouts": rows}}, f)