Besides deleting a key when it is next accessed, Redis runs a background cycle over keys that carry a time-to-live. Walk through how that cycle decides how much work to do, and why its guarantee is probabilistic rather than exact.

## Why sampling at all Redis executes commands on one thread. An exact sweep would mean either a per-key timer or an ordered structure of deadlines that must be walked to the current time — both add work proportional to the number of expiring keys at unpredictable moments, on the thread that also serves user traffic. Instead Redis uses randomized sampling with a feedback rule, which makes the cost proportional to how much actual garbage exists and hard-caps the time spent per run. ## The algorithm The cycle only ever looks at the *expires* table — the per-database table of keys that carry a TTL. That matters: a database with 50 million keys but 1,000 TTLs costs the same as one with 1,000 keys total. Per iteration, per database: 1. Sample about 20 random keys from the expires table. 2. Delete the ones whose deadline has passed; each deletion propagates a DEL (or UNLINK when `lazyfree-lazy-expire yes`) to replicas and the AOF, and fires the `expired` notification. 3. If more than 25% of that sample was expired, assume the table is still dirty and immediately repeat; otherwise stop for this database. 4. Stop early whenever the run's time budget is exhausted. The 25% rule is the whole design in one line: while garbage density is high the cycle keeps grinding; once density falls below a quarter it yields the thread back to clients. ## Fast and slow passes The **slow** pass runs from `serverCron`, i.e. `hz` times a second (default 10). It is allowed a percentage of CPU time — on the order of 25% of the cron interval — so it can do real work but cannot monopolize the loop. The **fast** pass runs in the event loop's pre-sleep step with a much smaller budget, roughly a millisecond, and with a minimum gap between runs; its job is to keep latency-sensitive reclamation snappy between cron beats. When a run hits its cap rather than reaching the density threshold, Redis increments `expired_time_cap_reached_count` — a direct signal that expiry work is arriving faster than the cycle is permitted to clear it. ## The probabilistic guarantee Because the loop continues while more than a quarter of samples are expired, the steady-state expectation is that fewer than ~25% of keys carrying a TTL are expired-but-unreclaimed at any instant. This is a bound on *memory waste*, not on correctness: correctness comes from the access-path check, which never serves an expired value. It is also an expectation, not a hard limit — a burst of simultaneous deadlines will exceed it briefly. ## Tuning knobs and what they cost - `hz` (default 10) raises cron frequency: more frequent, smaller expiry passes, at some baseline CPU. - `active-expire-effort` (1–10, default 1) scales the sampling size, the density threshold and the time budget. Raising it reclaims memory sooner at the price of more CPU stolen from command processing and higher tail latency. - `lazyfree-lazy-expire yes` moves the *freeing* of large collection values to a background thread, so expiring a hash with millions of fields does not block the loop — the unlink from the keyspace is still done inline. ## Diagnosing it `INFO stats` gives `expired_keys` (a rate to graph) and `expired_time_cap_reached_count` (chronic saturation if it climbs). `LATENCY LATEST` reports an `expire-cycle` event when a pass exceeded the latency threshold — essential because expiry is not a command, so it never appears in SLOWLOG. If memory sits higher than the TTL profile predicts while `expired_time_cap_reached_count` grows, the cycle is behind: raise effort, raise `hz`, or reduce the number of simultaneously expiring keys.