--- title: "Redis HOTKEYS sample ratio and duration" description: "Size Redis 8.6 HOTKEYS sampling and duration from detectable load, top-K limits, and the open sampled-total scaling bug." canonical_url: "https://fanout.sh/blog/redis-hotkeys-sample-ratio-duration" md_url: "https://fanout.sh/blog/redis-hotkeys-sample-ratio-duration.md" last_updated: "2026-10-11" access: "public" --- # Redis HOTKEYS sample ratio and duration Size Redis 8.6 HOTKEYS sampling and duration from detectable load, top-K limits, and the open sampled-total scaling bug. - Author: Suraj Gaud - Published: 2026-10-11 - Track: System design - Access: Public - Tags: Redis, hot keys, sampling, observability, top-K, capacity planning Redis HOTKEYS sample ratio and duration decide which expensive keys the server can see before the tracking session ends. A large sample ratio lowers overhead, but it can leave a short or moderate hot-key burst with too little evidence. The settings are not independent. A one-in-100 sample over 30 seconds gives a 50-request-per-second key about 15 observations on average. The same key gives only five observations when the duration is 10 seconds. Choose the pair from the lowest load worth detecting and the longest acceptable reaction time. Then check whether top-K truncation and the returned metric scale preserve the evidence you expected. ## Redis HOTKEYS sample ratio and duration Redis Open Source 8.6 added the server-side[HOTKEYS START command](https://redis.io/docs/latest/commands/hotkeys-start/). It can rank keys by CPU time, network bytes, or both during a tracking session. The SAMPLE argument is a ratio, not a percentage. SAMPLE 100 means each eligible key access is sampled with probability one divided by 100, or 1%. DURATION sets how many seconds the tracking session runs before it stops automatically. With no duration, tracking continues until HOTKEYS STOP is called. COUNT chooses K for the top-K structures. SLOTS can restrict collection to named hash slots in cluster mode. The command is marked admin, slow, and dangerous in the Redis reference. Treat it as an operator tool with a measured overhead budget, not as an unreviewed default on every shard. Fanout's[hot-key hysteresis guide](/blog/hot-key-detection-hysteresis-database)covers the controller that acts after detection. The question here is narrower: how much evidence reaches that controller. ## Turn the sample ratio into expected observations Let q be the key's command rate in requests per second, T the tracking duration in seconds, and r the SAMPLE ratio. The key receives q times T commands during the session. Because each command is sampled with probability one divided by r, its expected sample count is q times T divided by r. Call that expected count m. Rearranging the expression gives a planning threshold: q equals m times r divided by T. Suppose an operator wants at least 25 samples on average before trusting a ranking. With SAMPLE 100 and DURATION 30, the minimum planned rate is 25 times 100 divided by 30, or about 83 requests per second. Shorten the duration to 10 seconds and the threshold rises to 250 requests per second. Extend it to 60 seconds and it falls to about 42 requests per second. This does not guarantee that a key appears. Sampling is random, and the top-K structure can still exclude it. The formula only sizes the evidence budget before those other filters apply. It also counts commands rather than cost. One sampled command can contribute far more CPU time or bytes than another, which is why Redis ranks CPU and network work instead of raw command frequency alone. ## Calculate the chance of seeing no sample Expected count is useful, but a detector can miss a key completely. Under independent sampling, the probability of zero samples is one minus one divided by r, raised to the number of commands. For quick planning, that probability is close to e raised to minus m, where m is the expected sample count. Take SAMPLE 100 and DURATION 30. A key at five requests per second receives 150 commands and produces 1.5 samples on average. Its approximate probability of producing no sample is e to the minus 1.5, or 22.3%. Almost one tracking run in five can miss the key entirely under this simplified model. A 50-request-per-second key produces 15 samples on average. Its zero-sample probability is about 0.00003%, so total invisibility is no longer the main risk. A 500-request-per-second key produces 150 samples on average. For that key, ranking accuracy, cost attribution, and reaction delay matter more than whether any sample arrives. Real requests are bursty and sampling may interact with execution paths. Replay production-shaped traffic rather than treating the independent model as proof. The calculation still catches a bad configuration early. A detector cannot respond to a two-second burst if its sample ratio expects less than one observation during those two seconds. ## DURATION is a fixed session, not a sliding window HOTKEYS START accumulates evidence for one tracking session. DURATION stops that session after the named number of seconds. It does not describe a continuously sliding window that forgets old work one second at a time. A key that dominates the first half of a 60-second run can remain in the final ranking after its traffic falls. Longer sessions improve the expected sample count and can stabilize rankings. They also mix older and newer load, which delays recognition when the hot set moves. Shorter sessions react sooner but restart with less evidence. If an external loop launches repeated sessions, its launch interval and any gap between sessions become part of detection delay. Fanout's[detection-window threshold worksheet](/blog/cache-hot-key-detection-window-threshold)connects that delay to shard headroom and queue growth. Use a short session for incident triage when current load matters. Use a longer session when the goal is to find sustained cost that survives ordinary bursts. If automatic mitigation depends on the result, preserve state across runs outside Redis. A top-K snapshot alone does not provide promotion dwell, demotion dwell, or cooldown. Record collection start time and duration with every result. Two rankings are not comparable when one covers 10 seconds and the other covers 10 minutes. ## COUNT and METRICS create two rankings The required METRICS argument accepts CPU, NET, or both. These views can disagree for sound reasons. A small value with expensive computation can rank high by CPU and low by bytes. A large cached response can rank high by network use while consuming little command CPU. When both metrics are enabled, treat them as separate top-K populations. A key that misses COUNT 10 in the CPU list may still appear in the network list. COUNT is not a hotness threshold. It limits how many keys the structure returns. The eleventh key disappears even if it exceeds the capacity boundary that matters to the shard. Start with K larger than the number of keys an operator expects to investigate. Then compare the weakest returned entry with a resource threshold. The busiest key is not automatically dangerous. A shard at 20% utilization can tolerate a larger share than a shard already near its latency-constrained ceiling. Fanout's[peak-load guide for hot keys](/blog/consistent-hash-peak-load-with-hot-keys)shows why average ring balance cannot answer this question. Keep aggregate shard CPU and network measurements beside the ranking. Top-K identifies candidates; shard headroom decides whether they require action. ## Read sampled totals on one scale The[HOTKEYS GET command](https://redis.io/docs/latest/commands/hotkeys-get/)returns the ranked keys and collection metadata. Sampled collection creates an extra accounting requirement: numerator and denominator must use the same scale. An[open Redis issue](https://github.com/redis/redis/issues/15837)reports that SAMPLE n leaves per-key CPU and network totals near one divided by n of the all-command totals printed beside them. The issue reproduces the behavior on Redis 8.10.2 and an unstable build. With SAMPLE 10, the sum of one key's reported cost was about 10% of the all-command total in a one-key workload. The report also says standalone mode does not expose the matching sampled denominator, even though the server maintains it. That prevents a direct per-key share calculation from the returned fields. The issue was still open when this draft was written. Version-pin the behavior you test and check the issue before turning a sampled field into a percentage. Do not divide sampled per-key cost by an unsampled fleet total and call the result CPU share. Either use SAMPLE 1, verify a fixed release with corrected scaling, or retain a matching sampled denominator in the measurement path. Sampling can still rank keys usefully because multiplying every sampled weight by the same ratio does not change their order. The absolute share is the part that becomes unsafe when scales differ. Document whether a dashboard shows raw sampled cost, an expanded estimate, or an exact unsampled total. The label should make that choice visible. ## Measure detector cost before increasing coverage Lowering the sample ratio increases observations and work. Extending duration increases the time that work remains active. Redis exposes hot-key tracker memory and CPU time in the[INFO hotkeys section](https://redis.io/docs/latest/commands/info/). Capture those fields with request latency and shard CPU during a canary session. Sweep SAMPLE under the same production-shaped trace. Compare detector CPU, memory, p99 command latency, expected samples near the decision threshold, and stability of the top-K result. Then sweep DURATION. Include a moving hot set so a long session cannot look accurate merely because the same key stays hot for the whole test. Use slots to narrow the experiment when one cluster shard is suspect. Do not assume slot filtering is available on a standalone server. Start with CPU and NET together during diagnosis. If continuous use is justified later, keep only the metric that maps to the protected resource unless both rankings lead to different actions. Redis HOTKEYS sample ratio and duration are ready when the lowest actionable key produces enough observations before the response deadline, the tracker stays inside its overhead budget, and every percentage compares values on one scale. --- This representation contains public Fanout content only. Protected Pro lessons, account data, billing, checkout, and pricing are not included. Browse the public content map: https://fanout.sh/sitemap.md