12. Operations and Performance
Redis rarely fails loudly. More often it gets slower, runs out of memory, or loses a replica, and nobody notices until users do. This chapter covers the tools that make those problems visible (INFO, the slow log, the latency monitor, MONITOR, CLIENT LIST, Prometheus), the techniques that make Redis faster (benchmarking, finding big and hot keys, avoiding O(N) commands, kernel and network tuning), and the practices that keep it running in production (Kubernetes, configuration, upgrades, migrations, disaster recovery, capacity planning). It ends with modules, the mechanism that adds new commands and data types to the server.
All examples in this chapter were run against Redis Open Source 8.10.3 (the official redis:8.10 Docker image, with the 7.2 to 8.6 images for version comparisons), redis_exporter 1.97.0, and a 12-core development machine running Linux under WSL2, with clients in containers on the same Docker network. Treat the numbers as orders of magnitude, not as benchmarks for your hardware.
<a id="121-monitoring-and-diagnostics"></a>
12.1 Monitoring and Diagnostics
Redis reports almost everything about its own state through a handful of commands. This subchapter covers what each one tells you, what it costs to run, and how to turn its output into dashboards and alerts.
INFO Command Sections
A running Redis server is a black box: one process, one port, no web console. Before you can tune or troubleshoot anything, you need numbers: how much memory is used, how many clients are connected, whether the last snapshot succeeded, how often reads find their key. INFO returns all of them as plain text, one field:value pair per line, grouped into sections. It is the car's dashboard: one glance shows speed, fuel and temperature, and almost every monitoring tool for Redis (including the Prometheus exporter later in this subchapter) is built on it.
Sections
redis-cli INFO # default sections
redis-cli INFO memory # one section
redis-cli INFO memory stats # several sections (Redis 7.0+)
redis-cli INFO all # all sections except those added by modules
redis-cli INFO everything # all sections, including modules (e.g. search_*)
| Section | In default INFO | What it answers | Fields to know |
|---|---|---|---|
server | Yes | Which build, since when, how configured | redis_version, uptime_in_seconds, config_file, io_threads_active |
clients | Yes | Who is connected | connected_clients, blocked_clients, maxclients, client_recent_max_output_buffer, pubsub_clients |
memory | Yes | Where memory goes | used_memory, used_memory_rss, used_memory_peak, mem_fragmentation_ratio, maxmemory, maxmemory_policy, mem_clients_normal |
persistence | Yes | Are snapshots and AOF healthy | rdb_last_bgsave_status, rdb_changes_since_last_save, aof_last_write_status, loading |
threads (8.0+) | Yes | Load per I/O thread | io_thread_N:clients=...,reads=...,writes=... |
stats | Yes | Traffic and events since startup | total_commands_processed, instantaneous_ops_per_sec, keyspace_hits, keyspace_misses, evicted_keys, expired_keys, rejected_connections, latest_fork_usec, total_error_replies |
replication | Yes | Role and replication health | role, connected_slaves, master_link_status, master_repl_offset |
cpu | Yes | CPU time consumed | used_cpu_sys, used_cpu_user, used_cpu_sys_main_thread |
hotkeys (8.6+) | Yes | Results of a running HOTKEYS session (chapter 8.4) | Empty when no tracking is active |
modules | Yes | Loaded modules | module:name=search,ver=... |
commandstats | No | Calls and time per command | cmdstat_get:calls=...,usec=...,usec_per_call=...,rejected_calls=...,failed_calls=... |
errorstats | Yes | Error replies by prefix | errorstat_ERR:count=6, errorstat_WRONGTYPE:count=... |
latencystats | No | Latency percentiles per command | latency_percentiles_usec_get:p50=...,p99=...,p99.9=... |
cluster | Yes | Cluster mode on or off | cluster_enabled |
keyspace | Yes | Keys per database | db0:keys=200305,expires=0,avg_ttl=0 |
keysizes (8.0+) | Yes | Histogram of key sizes per type | db0_distrib_strings_sizes:64=200000, db0_distrib_lists_items:2K=1 |
The version notes were checked by listing the sections of INFO everything on each image: threads and keysizes appear in 8.0 (absent in 7.4), hotkeys in 8.6 (absent in 8.4).
Counters, gauges and rates
Most fields fall into two groups, and they must be read differently:
| Kind | Examples | How to read it |
|---|---|---|
| Gauge: a value right now | used_memory, connected_clients, blocked_clients, mem_fragmentation_ratio | Compare with a limit (maxmemory, maxclients) |
| Counter: a total since startup | total_commands_processed, keyspace_hits, evicted_keys, expired_keys, rejected_connections | Take two samples and divide the difference by the time between them |
A counter that says evicted_keys:1200000 means nothing by itself: the instance may have been up for a year. What matters is whether it grows now. Counters reset at restart and with CONFIG RESETSTAT.
Derived metrics worth computing
hit ratio = keyspace_hits / (keyspace_hits + keyspace_misses) (deltas, for caches)
memory usage = used_memory / maxmemory (when maxmemory > 0)
fragmentation = used_memory_rss / used_memory (= mem_fragmentation_ratio)
client headroom = connected_clients / maxclients
The fragmentation ratio needs care. A ratio well above 1.5 on a large dataset means memory is wasted in fragments (chapter 5.3); a ratio below 1 means part of Redis has been swapped out, which is much worse. On small instances the ratio is meaningless, because the fixed cost of the process dominates. The test instance with 32 MB of data reported:
used_memory_human:31.79M
used_memory_rss_human:58.44M
mem_fragmentation_ratio:1.85 <- not a problem: 26 MB of fixed process overhead (modules, allocator arenas)
Reading INFO from code
import time
import redis
r = redis.Redis(host="localhost", port=6379, decode_responses=True)
def sample():
# INFO is parsed by redis-py into a dict of ints, floats and strings
stats = r.info("stats")
mem = r.info("memory")
return time.monotonic(), stats, mem
t1, s1, _ = sample()
time.sleep(10)
t2, s2, mem = sample()
elapsed = t2 - t1
hits = s2["keyspace_hits"] - s1["keyspace_hits"] # deltas, not totals
misses = s2["keyspace_misses"] - s1["keyspace_misses"]
ops = (s2["total_commands_processed"] - s1["total_commands_processed"]) / elapsed
print(f"ops/s: {ops:,.0f}")
print(f"hit ratio: {hits / max(hits + misses, 1):.1%}")
print(f"evictions/s: {(s2['evicted_keys'] - s1['evicted_keys']) / elapsed:.1f}")
if mem["maxmemory"]:
print(f"memory used: {mem['used_memory'] / mem['maxmemory']:.1%} of maxmemory")
INFO itself is cheap: it reads counters the server already keeps. Polling it every few seconds is normal. INFO everything on a server with many search indexes is larger, so scrape it less often.
Key Takeaways
INFOwith no argument returns the default sections.commandstatsandlatencystatsneedINFO allor an explicit section name, and module sections needINFO everything.- Distinguish gauges (read the value) from counters (read the rate of change between two samples).
- Compute hit ratio, memory usage against
maxmemory, fragmentation and client headroom. Read the fragmentation ratio only on large datasets. - Recent versions added
threads,keysizes(8.0) andhotkeys(8.6).
Practice
- (Beginner) Run
redis-cli INFOon an idle instance and on one underredis-benchmarkload. List five fields that changed and say whether each is a gauge or a counter.- (Intermediate) Extend the Python script so it prints the top five commands by total time from
INFO commandstatsover the 10-second window (difference ofusecbetween samples), and test it while a benchmark runsHSETandLRANGEtraffic.- (Interview) "Our dashboard shows
mem_fragmentation_ratioat 0.7 on one node. Is this good news?" Hint: work out what RSS lower thanused_memoryphysically means for the process.
SLOWLOG
Users complain that "Redis is slow sometimes". Is it the network, the client, or a command that takes too long on the server? Because Redis executes commands on one main thread (chapter 5.1), a single slow command delays every other client. The slow log answers one precise question: which commands took longer than a threshold to execute. It is like a stopwatch on the chef in a one-cook kitchen. It measures how long each dish took to cook, not how long the order waited in line.
What is measured
The duration is the execution time of the command on the server, from the moment it starts running to the moment its reply is ready. It does not include network transfer, time spent waiting in the queue behind other commands, or the time a blocking command (such as BLPOP) spends waiting for data.
client ──network──► [ queue ] ──► [ execute ] ──► [ write reply ] ──network──► client
└ SLOWLOG ┘
Configuration
| Directive | Default | Meaning |
|---|---|---|
slowlog-log-slower-than | 10000 | Threshold in microseconds (10 ms). 0 logs every command, a negative value disables the log |
slowlog-max-len | 128 | Entries kept in memory; the oldest are dropped |
slowlog-entry-max-argc | 32 | Arguments stored per entry (configurable in 8.10; a fixed constant in 8.6 and earlier) |
slowlog-entry-max-string-len | 128 | Bytes stored per argument (same) |
A 10 ms threshold is generous for a server whose typical command takes a few microseconds. Many teams use 1 to 5 ms and raise slowlog-max-len to 1,000 or more, since each entry costs only a few hundred bytes.
redis-cli CONFIG SET slowlog-log-slower-than 1000 # 1 ms
redis-cli CONFIG SET slowlog-max-len 1024
Reading entries
127.0.0.1:6379> SLOWLOG GET 2
1) 1) (integer) 5 <- entry id (keeps increasing, even after SLOWLOG RESET)
2) (integer) 1794316096 <- Unix timestamp when the command ran
3) (integer) 48822 <- execution time in microseconds (48.8 ms)
4) 1) "KEYS" <- command and arguments (possibly truncated)
2) "*"
5) "127.0.0.1:48002" <- client address
6) "" <- client name (CLIENT SETNAME)
2) ...
127.0.0.1:6379> SLOWLOG LEN
(integer) 10
127.0.0.1:6379> SLOWLOG RESET
OK
The entries recorded on the test instance (200,305 keys, one hash with 200,000 fields, one sorted set with 50,000 members) show what a typical slow log catches:
| Command | Execution time |
|---|---|
DEBUG POPULATE 200000 | 125.8 ms |
COPY catalog:index c3 (200,000-field hash) | 84.6 ms |
KEYS * (200,305 keys) | 48.8 ms |
HGETALL catalog:index | 26.8 ms |
DEL of a 200,000-field hash | 12.8 ms |
ZRANGE leaderboard 0 -1 WITHSCORES (50,000 members) | 4.0 ms |
SCAN cursor COUNT 1000 | 1.0 to 1.9 ms per call |
UNLINK of the same 200,000-field hash | below 1 ms, not logged |
Slow log counters in INFO (Redis 8.10)
Redis 8.10 also counts slow log entries in INFO, so you can alert on them without polling SLOWLOG GET. Neither field exists in 8.6:
# INFO stats
slowlog_commands_count:1
slowlog_commands_time_ms_max:125.77
slowlog_commands_time_ms_sum:125.77
# INFO commandstats
cmdstat_keys:calls=1,usec=48822,usec_per_call=48822.00,...,slowlog_count=1,slowlog_time_ms_sum=48.82,slowlog_time_ms_max=48.82
Collecting the slow log from code
The log lives in memory and holds only the last slowlog-max-len entries, so a collector should poll it regularly and remember the last id it has seen:
from collections import Counter
import redis
r = redis.Redis(decode_responses=True)
last_seen_id = -1
def collect():
global last_seen_id
entries = r.slowlog_get(1024) # newest first
new = [e for e in entries if e["id"] > last_seen_id]
if new:
last_seen_id = new[0]["id"]
by_command = Counter()
for e in new:
cmd = e["command"] # "KEYS *" as a single string in redis-py
name = cmd.split(" ", 1)[0].upper()
by_command[name] += e["duration"] # microseconds
print(f'{e["duration"] / 1000:8.1f} ms {e["client_address"]:<22} {cmd[:80]}')
return by_command
print(collect().most_common(5))
Limits of the slow log
- A command that takes 0.5 ms but runs 20,000 times per second costs far more than one 50 ms
KEYSper hour. The slow log only shows the second. UseINFO commandstats(totalusecper command) for the aggregate view. - It does not explain latency caused by forks, swapping or the network. Those are covered by the latency monitor (next topic).
- Arguments are stored as sent. A password passed as an argument to a custom command or a script could end up in the log, readable by anyone allowed to run
SLOWLOG GET.
Key Takeaways
- The slow log records commands whose execution exceeded
slowlog-log-slower-thanmicroseconds (default 10 ms), excluding network and queueing time. - Lower the threshold to 1 to 5 ms and raise
slowlog-max-lenin production. Poll the log and remember the last entry id. - Redis 8.10 adds slow log counters to
INFO statsandINFO commandstats, and makes argument truncation configurable. - Combine it with
INFO commandstatsto catch commands that are individually fast but expensive in total.
Practice
- (Beginner) Set
slowlog-log-slower-thanto 0, run ten different commands, and read them back withSLOWLOG GET. Then set it to 1000 and create a command that gets logged (hint:DEBUG POPULATEwithenable-debug-command local, thenKEYS *).- (Intermediate) Fill a hash with 500,000 fields and compare the slow log entries of
HGETALL,HSCANwithCOUNT 1000,DELandUNLINK. Explain whyUNLINKdoes not appear.- (Interview) "p99 latency seen by our application is 40 ms, but the slow log with a 5 ms threshold is empty. Where would you look next?" Hint: list everything between the client's
send()andrecv()that the slow log does not measure.
LATENCY Monitoring
The slow log covers only command execution, but latency spikes also come from forks for snapshots, fsync on a slow disk, expiring or evicting large keys, and a noisy hypervisor. Redis has three separate tools, all called "latency", that look at the problem from different angles:
| Tool | Since | Measures | Use it to answer |
|---|---|---|---|
Latency monitor (LATENCY LATEST/HISTORY/DOCTOR) | 2.8.13 | Internal events (commands, forks, fsync, expiry, eviction) slower than a threshold | "What inside Redis caused the spike at 14:02?" |
Per-command latency tracking (INFO latencystats, LATENCY HISTOGRAM) | 7.0 | Distribution of execution time per command | "What is the p99 of GET on the server?" |
Client-side probes (redis-cli --latency, --intrinsic-latency) | 2.x | Round trip seen by a client, and the host's own scheduling noise | "Is the delay in Redis, the network or the machine?" |
The latency monitor
It is disabled by default (latency-monitor-threshold 0). Once enabled, any internal event slower than the threshold (in milliseconds) is recorded under an event name, with up to 160 samples per event (at most one per second).
redis-cli CONFIG SET latency-monitor-threshold 100 # record events of 100 ms or more
| Event name | Source |
|---|---|
command, fast-command | Slow commands (fast-command for those flagged O(1) or O(log N)) |
fork | The fork() call for BGSAVE, AOF rewrite or full sync (chapter 6.1) |
aof-fsync-always, aof-write, aof-write-pending-fsync | AOF disk writes waiting on a slow disk |
expire-cycle, eviction-cycle, eviction-del | Active expiry and eviction loops that ran too long |
active-defrag-cycle | Active defragmentation |
Two DEBUG SLEEP calls (300 ms and 150 ms) on the test server produced:
127.0.0.1:6379> LATENCY LATEST
1) 1) "command" <- event name
2) (integer) 1794315978 <- time of the latest sample
3) (integer) 150 <- latest latency in ms
4) (integer) 300 <- maximum ever recorded
127.0.0.1:6379> LATENCY HISTORY command
1) 1) (integer) 1794315977
2) (integer) 300
2) 1) (integer) 1794315978
2) (integer) 150
127.0.0.1:6379> LATENCY DOCTOR
Dave, I have observed latency spikes in this Redis instance. You don't mind talking about it, do you Dave?
1. command: 2 latency spikes (average 225ms, mean deviation 75ms, period 0.50 sec). Worst all time event 300ms.
I have a few advices for you:
- Check your Slow Log to understand what are the commands you are running which are too slow to execute. ...
- Deleting, expiring or evicting (because of maxmemory policy) large objects is a blocking operation. ...
- I detected a non zero amount of anonymous huge pages used by your process. ...
LATENCY DOCTOR (with its 2001: A Space Odyssey greeting) turns the samples into advice. Treat its output as a checklist, not a diagnosis. On this host, transparent huge pages were [always], and Redis had already disabled them for its own process (disable-thp yes, so /proc/<pid>/status showed THP_enabled: 0), yet 2 MB of huge pages allocated earlier during startup were enough to trigger the THP advice. LATENCY GRAPH <event> draws an ASCII chart and LATENCY RESET clears the samples.
Per-command latency tracking
Since Redis 7.0, latency-tracking yes (the default) keeps a histogram of the execution time of every command. INFO latencystats shows selected percentiles (latency-tracking-info-percentiles, default 50 99 99.9), and LATENCY HISTOGRAM returns the whole distribution:
# INFO latencystats
latency_percentiles_usec_get:p50=0.001,p99=1.003,p99.9=2.007
latency_percentiles_usec_keys:p50=49020.927,p99=49020.927,p99.9=49020.927
127.0.0.1:6379> LATENCY HISTOGRAM get
1) "get"
2) 1) "calls"
2) (integer) 100000
3) "histogram_usec"
4) 1) (integer) 1 2) (integer) 98732 <- 98,732 calls took at most 1 µs
3) (integer) 2 4) (integer) 99331 <- cumulative: 99,331 at most 2 µs
...
17) (integer) 264 18) (integer) 100000 <- all within 264 µs
These numbers are server-side execution only: sub-microsecond GETs here, while the client measured around 200 µs per request over the network.
Client-side probes
# Round trip from this client, continuously (min/max/avg in ms)
redis-cli -h cache.internal --latency
# Same, but a new line every 15 seconds, to see how latency changes over time
redis-cli -h cache.internal --latency-history -i 15
# Run ON the Redis host: how long does the OS keep a busy process from running?
redis-cli --intrinsic-latency 30
# 47478857 total runs (avg latency: 0.0632 microseconds / 63.19 nanoseconds per run).
# Worst run took 68480x longer than the average latency. <- 68480 x 63 ns ≈ 4.3 ms
--intrinsic-latency does not talk to Redis at all: it spins in a loop and records the longest gap. A 4.3 ms worst case on this WSL2 machine means no Redis instance on it can promise better than about 4 ms at the extreme tail. On a good bare-metal host the worst case is usually well under 1 ms; noisy virtual machines can show tens of milliseconds.
A triage path
client sees slow requests
│
├─ redis-cli --latency from the same host as the client: also slow?
│ no → client side (pool exhausted, GC pauses, DNS, TLS handshakes)
│ yes ↓
├─ SLOWLOG / INFO commandstats: slow or very frequent commands? → fix commands (12.2)
├─ LATENCY LATEST: fork, aof-fsync, expire-cycle, eviction events? → persistence, big keys, memory
├─ --intrinsic-latency on the server host: large worst case? → host or hypervisor
└─ none of the above → network (12.2)
Key Takeaways
- Enable the latency monitor in production (
latency-monitor-threshold, in ms, for example 50 or 100). It records forks, fsyncs, expiry and eviction, not only commands. INFO latencystatsandLATENCY HISTOGRAMgive per-command server-side percentiles. They exclude network and queueing time.--latencymeasures what a client sees;--intrinsic-latencymeasures the host's baseline noise and must run on the server host.- Use
LATENCY DOCTORas a checklist and verify its claims.
Practice
- (Beginner) Enable the latency monitor with a 50 ms threshold, trigger a spike with
DEBUG SLEEP 0.2(needsenable-debug-command local), and read it withLATENCY LATEST,LATENCY HISTORY commandandLATENCY GRAPH command.- (Intermediate) Load 2 GB of data, run
BGSAVEa few times, and check whether aforkevent appears. Compare its value withlatest_fork_usecinINFO stats.- (Interview) "The application sees 30 ms spikes every 5 minutes. How do you find out whether Redis causes them?" Hint: a regular period suggests a scheduled activity. Check
saverules, AOF rewrites, the latency monitor'sforkevent, and the client host.
MONITOR Command and Its Costs
When you need to know exactly what an application sends to Redis (which keys, in which order, how many times per page load), MONITOR streams every command the server processes to the client that asked for it. It is the equivalent of a wiretap: perfect visibility, and expensive enough that you should not leave it running.
Output format
$ redis-cli MONITOR
OK
1794316642.876738 [0 127.0.0.1:40760] "SET" "greeting" "hello"
1794316642.979478 [0 127.0.0.1:40776] "AUTH" "(redacted)" "(redacted)"
1794316643.197888 [0 127.0.0.1:40800] "EVAL" "return redis.call('GET', KEYS[1])" "1" "greeting"
1794316643.198021 [0 lua] "GET" "greeting" <- command run by a script
1794316643.320420 [0 127.0.0.1:40808] "MULTI"
1794316643.321545 [0 127.0.0.1:40808] "INCR" "n"
1794316643.321633 [0 127.0.0.1:40808] "EXEC"
1794316643.454154 [0 127.0.0.1:40816] "HELLO" "3" "AUTH" "(redacted)" "(redacted)"
└ Unix time └ db └ client address └ command and arguments
In the same session, a CONFIG GET maxmemory was not printed at all: administrative commands are left out, and credentials in AUTH and HELLO are replaced with (redacted). Everything else is shown in full, including the values your application stores. MONITOR belongs to the @admin and @dangerous ACL categories, so ordinary application users cannot run it (chapter 11.1).
Cost 1: throughput
For every command, the server formats a text line and appends it to the output buffer of every monitoring client. Measured with redis-benchmark (1,000,000 requests, 50 clients, pipelines of 16):
| Scenario | SET req/s | SET p50 | GET req/s | GET p50 |
|---|---|---|---|---|
No MONITOR | 757,576 | 0.88 ms | 874,126 | 0.70 ms |
Two MONITOR clients | 371,609 | 1.94 ms | 436,300 | 1.66 ms |
Throughput halved and median latency doubled. Without pipelining the client was the bottleneck and the drop was smaller (93,414 to 81,466 SET/s, p50 0.26 to 0.43 ms), but the extra work on the main thread is the same.
Cost 2: memory, when the monitor cannot keep up
MONITOR clients belong to the normal class of client-output-buffer-limit, whose default is normal 0 0 0: no limit. If the monitoring client reads slower than the server produces (a slow terminal, a pipe to a stuck process, a far-away laptop), the output buffer grows without bound inside Redis. A redis-cli MONITOR | sleep 600 (which stops reading after the pipe fills) while a benchmark ran 1,000,000 SETs with 100-byte values:
127.0.0.1:6379> CLIENT LIST
id=445 ... flags=O ... oll=8180 omem=167722720 tot-mem=167725024 ... cmd=monitor
└ 8,180 queued reply blocks, 160 MB of output buffer
# INFO memory
used_memory_human:192.08M <- was 32 MB before the benchmark
mem_clients_normal:167725024
127.0.0.1:6379> CLIENT KILL ID 445
(integer) 1 <- used_memory back to 32 MB
On a server close to maxmemory, a forgotten MONITOR can trigger evictions or OOM errors for the real workload.
Using it safely
# Always time-box it and write to a local file, so the client keeps up
timeout 10 redis-cli MONITOR > /tmp/monitor.txt
# Then analyze offline: most frequent commands and key prefixes
awk '{print $4}' /tmp/monitor.txt | sort | uniq -c | sort -rn | head
awk '{print $5}' /tmp/monitor.txt | cut -d: -f1 | sort | uniq -c | sort -rn | head
Alternatives that cost less: INFO commandstats for per-command counts, SLOWLOG for slow commands, HOTKEYS (8.6+) or --hotkeys for frequently accessed keys (chapter 8.4), and client-side instrumentation (OpenTelemetry spans in the application) for per-request traces.
Key Takeaways
MONITORshows every command with timestamp, database and client, including script-generated commands. Admin commands are omitted and credentials redacted, but data values are visible.- It can halve throughput, and a slow monitoring client can accumulate hundreds of megabytes of unbounded output buffer.
- Use it only for short, time-boxed sessions on non-critical instances, writing to a local file. Kill forgotten monitors (
flags=OinCLIENT LIST).
Practice
- (Beginner) Run
timeout 5 redis-cli MONITORwhile you use an application or a client library, and identify how many commands one high-level operation sends (for example a page load or asave()in an ORM).- (Intermediate) Reproduce the output-buffer growth with
redis-cli MONITOR | sleep 600and a benchmark. Then setclient-output-buffer-limit normal 64mb 32mb 10and repeat. What happens to the monitor, and what could this setting break for ordinary clients?- (Interview) "A developer wants to leave
MONITORrunning permanently on production to feed an audit log. What do you tell them?" Hint: compare the costs measured here with alternatives such as ACL logs, keyspace notifications and application-level audit events.
CLIENT LIST and CLIENT KILL
Many Redis incidents are really client incidents: a connection leak that exhausts maxclients, a worker stuck on a blocking command, a slow consumer whose output buffer eats memory, a forgotten MONITOR. CLIENT LIST shows one line per connection with everything the server knows about it, and CLIENT KILL closes the ones that should not be there.
Reading a client line
id=31 addr=127.0.0.1:46910 laddr=127.0.0.1:6379 fd=22 name= age=0 idle=0 flags=N db=0 sub=0 psub=0
ssub=0 multi=-1 watch=0 qbuf=26 qbuf-free=20448 argv-mem=10 multi-mem=0 rbs=16384 rbp=16384 obl=0
oll=0 omem=0 omem-shared=0 omem-unshared=0 tot-mem=38170 events=r cmd=client|list user=default
redir=-1 resp=2 lib-name= lib-ver= io-thread=0 tot-net-in=26 tot-net-out=0 tot-cmds=0 read-events=1
avg-pipeline-len-sum=1 avg-pipeline-len-cnt=1
| Field | Meaning | Look for |
|---|---|---|
id | Unique, increasing connection id | Use it with CLIENT KILL ID (never reused) |
addr / laddr | Client address / local address it connected to | Which host or pod owns the connection |
name, lib-name, lib-ver | Set by CLIENT SETNAME and CLIENT SETINFO (clients send the library automatically) | Unnamed connections are hard to trace: name them |
age / idle | Seconds since connect / since last command | High idle on many connections: leaked or oversized pools |
flags | N normal, O monitor, S replica, M primary, P Pub/Sub, x in MULTI, b blocked, t tracking | Unexpected O or long-lived b |
db, user | Selected database and ACL user | Who is doing what |
sub, psub, ssub | Channel, pattern and shard channel subscriptions | |
qbuf | Query buffer: unread input | Large values: a huge command arriving, or a client sending faster than processed |
oll, omem | Output list length and output buffer bytes | Slow readers: replies waiting to be sent |
tot-mem | Total memory used by this connection | Sort by it to find the heaviest clients |
cmd | Last command executed | |
tot-net-in, tot-net-out, tot-cmds | Traffic and commands for this connection | Noisy clients |
Filters narrow the list: CLIENT LIST TYPE normal|master|replica|pubsub and CLIENT LIST ID 31 32. CLIENT INFO shows the current connection only.
Finding the problem connections
from collections import Counter
import redis
r = redis.Redis(decode_responses=True)
clients = r.client_list() # list of dicts, one per connection
# Who holds the connections? Group by source host and library
by_host = Counter((c["addr"].rsplit(":", 1)[0], c.get("lib-name", "")) for c in clients)
for (host, lib), n in by_host.most_common(10):
print(f"{n:6} connections from {host:<16} {lib}")
# Heaviest connections by memory, and long-idle connections
for c in sorted(clients, key=lambda c: int(c["tot-mem"]), reverse=True)[:5]:
print(f'id={c["id"]} addr={c["addr"]} flags={c["flags"]} omem={c["omem"]} cmd={c["cmd"]}')
idle = [c for c in clients if int(c["idle"]) > 3600 and "S" not in c["flags"]]
print(f"{len(idle)} connections idle for more than an hour")
Killing connections
CLIENT KILL ID 445 # one connection, by id (safest)
CLIENT KILL ADDR 10.0.3.17:52144 # by client address
CLIENT KILL LADDR 10.0.0.5:6379 # everything connected to one listener
CLIENT KILL USER reporting # every connection of an ACL user (after a credential leak)
CLIENT KILL TYPE pubsub # by type: normal, master, replica, pubsub
CLIENT KILL MAXAGE 86400 # connections older than one day
CLIENT KILL TYPE normal SKIPME yes # filters combine with AND; SKIPME no would kill this connection too
These are the filters accepted by Redis 8.10 (COMMAND DOCS client|kill): ID, ADDR, LADDR, TYPE, USER, SKIPME and MAXAGE. The reply is the number of connections closed. Note that MONITOR clients count as normal: in the tests above, CLIENT KILL TYPE normal SKIPME yes closed both monitors.
Killing a connection is not a fix: a well-behaved client reconnects immediately. It is a way to stop damage now (free memory, release maxclients) while you fix the client.
Settings that protect the server from clients
| Setting | Default | Effect |
|---|---|---|
maxclients | 10000 (also limited by the process file descriptor limit) | New connections beyond this get ERR max number of clients reached and rejected_connections grows |
timeout | 0 (never) | Close connections idle for this many seconds (not replicas, the link to the primary, Pub/Sub subscribers or blocked clients) |
client-output-buffer-limit | normal 0 0 0, replica 256mb 64mb 60, pubsub 32mb 8mb 60 | Disconnect clients whose output buffer exceeds a hard limit, or a soft limit for N seconds |
maxmemory-clients | 0 (off) | Since 7.0: evict the clients using the most memory when all clients together exceed this limit (bytes or % of maxmemory) |
tcp-keepalive | 300 | Detect dead peers (crashed hosts) at the TCP level |
CLIENT NO-EVICT on exempts a connection (for example an admin session) from maxmemory-clients.
Key Takeaways
CLIENT LISTshows per-connection age, idle time, flags, buffers, memory, user and library. Name your connections so they can be traced.- Look for high
omem/oll(slow readers), unexpectedOflags (monitors), and many idle connections from one host (pool leaks). CLIENT KILLacceptsID,ADDR,LADDR,TYPE,USER,SKIPMEandMAXAGE. Killing stops damage but does not fix the client.- Protect the server with
maxclients,timeout, output buffer limits andmaxmemory-clients.
Practice
- (Beginner) Open three
redis-clisessions, give each a name withCLIENT SETNAME, and find them inCLIENT LIST. Put one intoBLPOP empty 0and identify the flag that shows it is blocked.- (Intermediate) Write a script that opens 200 connections from a pool and never closes them, then use the Python snippet to find them by host and library. Configure
timeoutso they are closed automatically, and verify withCLIENT LIST.- (Interview) "
connected_clientson our primary climbs from 800 to 10,000 within an hour after each deployment, then new connections fail. How do you investigate?" Hint: groupCLIENT LISTbyaddrhost,lib-nameandage, and think about connection pools created per request.
Metrics Export with Prometheus
Reading INFO by hand helps during an incident, but monitoring means collecting metrics all the time, keeping their history, drawing them on dashboards and alerting on them. Prometheus is the most common tool for this in cloud-native environments. It works by pulling: every 15 or 30 seconds it sends an HTTP request to a /metrics endpoint and stores the numbers it gets back. Redis does not speak HTTP, so a small translator sits in between: the exporter.
┌──────────┐ INFO, CONFIG GET, ┌────────────────┐ GET /metrics ┌────────────┐ ┌─────────┐
│ Redis │◄─ SLOWLOG, LATENCY ──│ redis_exporter │◄───────────────│ Prometheus │──►│ Grafana │
│ :6379 │ │ :9121 │ every 15 s │ + alerts │ └─────────┘
└──────────┘ └────────────────┘ └────────────┘
The de facto standard is oliver006/redis_exporter, which works with Redis, Valkey and Redis Cluster. It can run as a sidecar next to each Redis (one exporter per instance) or as one exporter for many instances, where Prometheus passes the target in the URL (/scrape?target=redis://host:6379).
Running it
docker run -d --name redis-exporter -p 9121:9121 \
-e REDIS_USER=exporter -e REDIS_PASSWORD="$EXPORTER_PW" \
oliver006/redis_exporter:latest --redis.addr=redis://redis.internal:6379
curl -s localhost:9121/metrics | grep -E '^redis_(up|memory_used_bytes|connected_clients) '
# redis_connected_clients 1
# redis_memory_used_bytes 4.7412552e+07
# redis_up 1
A least-privilege ACL user for the exporter
The exporter needs only read-only introspection commands. These rules were found by starting from +ping +info, scraping, and adding each command reported in ACL LOG until no denial remained (exporter 1.97.0, default options):
ACL SETUSER exporter on >long-random-password
+ping +info +client|setname +command|info +config|get
+latency|histogram +latency|latest +slowlog|get +slowlog|len
With this user the exporter returned 502 metric lines and ACL LOG stayed empty. Options that inspect keys (--check-keys, --count-keys) need key permissions and more commands.
Metrics that matter
| Metric | Type | Use |
|---|---|---|
redis_up | Gauge | 0 when the exporter cannot reach Redis |
redis_memory_used_bytes, redis_memory_max_bytes | Gauge | Memory pressure (max is 0 when maxmemory is unset) |
redis_mem_fragmentation_ratio | Gauge | Fragmentation or swapping |
redis_connected_clients, redis_config_maxclients, redis_blocked_clients | Gauge | Connection headroom |
redis_commands_processed_total | Counter | Throughput with rate() |
redis_commands_total{cmd}, redis_commands_duration_seconds_total{cmd} | Counter | Calls and time per command (from commandstats) |
redis_latency_percentiles_usec{cmd,quantile} | Gauge | Server-side p50/p99/p99.9 per command (from latencystats) |
redis_keyspace_hits_total, redis_keyspace_misses_total | Counter | Hit ratio |
redis_evicted_keys_total, redis_expired_keys_total | Counter | Eviction pressure, expiry volume |
redis_rejected_connections_total | Counter | maxclients reached |
redis_rdb_last_bgsave_status, redis_aof_last_write_status | Gauge | 1 = OK, 0 = failed |
redis_master_link_up | Gauge | On replicas: link to the primary |
redis_connected_slaves, redis_slowlog_length, redis_slowlog_last_id | Gauge | Replica count, slow log activity |
redis_db_keys{db}, redis_db_keys_expiring{db} | Gauge | Key counts |
Counters are exported as running totals. Always wrap them in rate() or increase() in queries.
Prometheus scrape configuration and alert rules
# prometheus.yml
scrape_configs:
- job_name: redis
scrape_interval: 15s
static_configs:
- targets: ["redis-exporter-cache:9121", "redis-exporter-sessions:9121"]
# redis-alerts.yml
groups:
- name: redis
rules:
- alert: RedisDown
expr: redis_up == 0
for: 1m
labels: {severity: critical}
- alert: RedisMemoryHigh
# Only meaningful when maxmemory is set (redis_memory_max_bytes > 0)
expr: redis_memory_used_bytes / (redis_memory_max_bytes > 0) > 0.90
for: 10m
labels: {severity: warning}
- alert: RedisEvicting
# Fine for an LRU cache by design; a problem for sessions, queues or locks
expr: rate(redis_evicted_keys_total[5m]) > 0
for: 5m
labels: {severity: warning}
- alert: RedisClientsNearLimit
expr: redis_connected_clients / redis_config_maxclients > 0.8
for: 5m
- alert: RedisRejectingConnections
expr: increase(redis_rejected_connections_total[5m]) > 0
- alert: RedisPersistenceFailing
expr: redis_rdb_last_bgsave_status == 0 or redis_aof_last_write_status == 0
for: 1m
labels: {severity: critical}
- alert: RedisReplicaLinkDown
expr: redis_master_link_up == 0
for: 2m
- alert: RedisCacheHitRatioLow
expr: |
rate(redis_keyspace_hits_total[10m])
/ (rate(redis_keyspace_hits_total[10m]) + rate(redis_keyspace_misses_total[10m])) < 0.8
for: 30m
What to put on a dashboard
A first Redis dashboard needs about eight panels: availability (redis_up, role), throughput (rate(redis_commands_processed_total[1m])), latency (p99 per top command), memory (used vs max, fragmentation), evictions and expirations, connections (connected, blocked, rejected), hit ratio, and persistence/replication status. Community Grafana dashboards for this exporter exist, but build alerts on what your workload needs: an eviction is routine for a cache and an incident for a job queue.
Key Takeaways
- Prometheus pulls metrics over HTTP, so Redis needs an exporter.
oliver006/redis_exporter(port 9121) translatesINFO,commandstats,latencystats, the slow log and the configuration into metrics. - Give the exporter its own ACL user with read-only introspection commands only.
- Alert on availability, memory against
maxmemory, evictions (where they matter), client headroom, rejected connections, persistence failures and replica links. - Use
rate()on every counter, and choose thresholds per workload.
Practice
- (Beginner) Start Redis, the exporter and Prometheus with Docker Compose, open the Prometheus UI, and plot
rate(redis_commands_processed_total[1m])whileredis-benchmarkruns.- (Intermediate) Create the
exporterACL user above but remove+config|get. Scrape again, find the denial inACL LOG, and list which metrics disappeared.- (Interview) "Design alerting for a Redis deployment that hosts both a cache and a background job queue on separate instances. Which alerts differ between the two?" Hint: compare what evictions, hit ratio, memory growth and persistence failures mean for each workload.
<a id="122-performance-tuning"></a>
12.2 Performance Tuning
A single Redis instance can serve hundreds of thousands of requests per second, but only if the workload, the data model, the operating system and the network cooperate. This subchapter shows how to measure performance honestly, find the keys and commands that hold it back, and tune the host and the network around the server.
Benchmarking with redis-benchmark
"How fast is Redis?" has no single answer. The same server delivered 13,000 or 1,400,000 GETs per second in the tests below, depending only on how the client sent them. Before sizing a deployment, comparing configurations, or blaming Redis for a slow application, you need numbers measured with a load that looks like yours. redis-benchmark, shipped with every Redis installation, is the quickest way to get them.
How it works
redis-benchmark opens -c connections (default 50) and sends -n requests in total (default 100,000) for each test. Each connection waits for a reply before sending the next request, unless -P pipelines several requests per round trip. At the end it prints requests per second and latency percentiles.
# Default suite (PING, SET, GET, INCR, LPUSH, ... , MSET), quiet output: one line per test
redis-benchmark -h redis.internal -q
# Selected tests, more requests, CSV with percentiles
redis-benchmark -h redis.internal -t set,get -n 1000000 --csv
# Realistic keys and values: 1,000,000 distinct keys (-r), 512-byte values (-d)
redis-benchmark -t set,get -n 1000000 -r 1000000 -d 512 -q
# Any command: __rand_int__ is replaced by a random number in [0, -r)
redis-benchmark -n 200000 -r 100000 ZADD lb __rand_int__ m:__rand_int__
redis-benchmark -n 200000 -r 100000 HSET user:__rand_int__ name alice
| Option | Meaning |
|---|---|
-c <n> | Parallel connections (default 50) |
-n <n> | Total requests per test (default 100,000) |
-P <n> | Pipeline n requests per round trip (default 1) |
-d <bytes> | Value size for SET/GET (default 3 bytes) |
-r <n> | Random keys in a space of n; without it, every request uses the same key |
-t <list> | Only these tests |
--threads <n> | Generate load from several client threads (needed when one client core saturates) |
--cluster | Benchmark a Redis Cluster (hashes keys to the right nodes) |
-s <socket> | Unix socket instead of TCP |
--tls, --user, -a | TLS and authentication |
--csv, -q | Machine-readable or one-line output |
Same server, very different numbers
GET against Redis 8.10 in the same container (no network), then from another container over the Docker network:
| Client setup | Path | Requests/s | p50 |
|---|---|---|---|
| 1 connection | loopback TCP | 13,146 | 0.063 ms |
| 1 connection | Unix socket | 14,403 | 0.055 ms |
| 1 connection | Docker network | 11,490 | 0.063 ms |
| 50 connections | loopback TCP | 121,051 | 0.199 ms |
| 50 connections | Unix socket | 138,581 | 0.183 ms |
50 connections, -P 16 | loopback TCP | 1,237,624 | 0.495 ms |
50 connections, -P 16 | Unix socket | 1,404,494 | 0.431 ms |
With one connection, the time per request is dominated by the round trip, not by Redis. More connections overlap round trips, and pipelining (chapter 4.3) amortizes them, multiplying throughput by 100. Latency per request rises at the same time, because each request waits behind others in the pipeline. Report throughput and latency together, always with the client setup that produced them.
Value size and command type matter too: SET with 3-byte values reached 118,483 req/s, with 10,000-byte values 92,039 req/s. ZADD into one sorted set with random members reached 109,709 req/s, HSET into random hashes 125,549 req/s (50 connections, no pipelining).
Common mistakes
| Mistake | Effect | Fix |
|---|---|---|
No -r | All SETs and GETs hit one key, literally named key:__rand_int__ (it showed up in --keystats on the test server) | Use -r with a realistic keyspace size |
| Default 3-byte values | Measures protocol overhead, not your data | Use -d close to your typical value size |
| Benchmark and server on the same small host | Both compete for CPU; results are pessimistic or noisy | Run the client on another machine in the same network, or pin CPUs |
| One client process saturating one core | You measure the client's limit | Add --threads, or run several benchmark processes |
| Running against production | Writes test keys, consumes capacity, may trigger evictions | Use a dedicated instance with production-like configuration |
| Comparing runs with different persistence settings | appendfsync always vs everysec changes write latency drastically (chapter 6.2) | Keep configuration identical, change one variable at a time |
| Short runs | Warm-up and noise dominate | Run for at least tens of seconds, repeat 3 times, report the median |
When redis-benchmark is not enough
redis-benchmark runs one test at a time with uniform random keys. Real traffic mixes reads and writes, and some keys are much more popular than others. memtier_benchmark (from Redis Ltd., open source) supports read/write ratios, Gaussian key distributions and test durations:
# 10 reads per write, 512-byte values, keys concentrated around the middle of the range
memtier_benchmark -s redis.internal -p 6379 --protocol=redis \
--threads=4 --clients=50 --test-time=60 \
--ratio=1:10 --data-size=512 \
--key-pattern=G:G --key-minimum=1 --key-maximum=1000000
The most faithful benchmark is your own application's traffic: replay captured requests against a staging server, or load-test the application and watch Redis metrics (12.1).
Key Takeaways
- Throughput depends mostly on concurrency (
-c) and pipelining (-P): the same server gave 13 thousand to 1.4 millionGETs per second. - Always use
-rand a realistic-d. Without-r, every request hits one key. - Report throughput together with latency percentiles and the exact client setup.
- Benchmark on a dedicated instance, from a separate host, and change one variable at a time. Use
memtier_benchmarkor application load tests for realistic mixes.
Practice
- (Beginner) Run
redis-benchmark -t get -n 300000with-c 1,-c 50and-c 50 -P 16, and record requests per second and p50. Explain each jump in one sentence.- (Intermediate) Benchmark
SETwith-d 100,-d 1000,-d 10000and-d 100000, with and withoutappendonly yesandappendfsync always. Plot requests per second against value size for both configurations.- (Interview) "A vendor's benchmark says Redis does 1.5 million operations per second. Our service gets 20,000. Is something wrong?" Hint: list the parameters that produce the vendor's number (pipelining, value size, network, number of connections) and compare them with how your service talks to Redis.
Finding Big Keys and Hot Keys
Chapter 8.4 explained why big keys (one key with millions of elements or megabytes of data) and hot keys (one key receiving a large share of all requests) hurt, and how to redesign them. This topic is about finding them in a running system, before they cause an incident. The two problems look alike from the outside (latency spikes, one overloaded node) but need different tools: big keys are a property of the data, hot keys a property of the traffic.
| Big key | Hot key | |
|---|---|---|
| Definition | Very large value or very many elements | Very large share of requests |
| Typical symptom | Slow commands in SLOWLOG, spikes on DEL/expiry, one cluster node with much more memory | One cluster node with much higher CPU and ops/s, network saturation |
| Found by inspecting | The keyspace (SCAN, MEMORY USAGE, RDB files) | The traffic (LFU counters, HOTKEYS, MONITOR samples, client metrics) |
Big keys: the keyspace scanners
redis-cli has three scanning modes. All use SCAN, so they do not block the server, but they do add load. On a busy server, slow them down with -i (seconds of sleep per 100 SCAN calls).
redis-cli --bigkeys # largest key per type by element count (string: by length)
redis-cli --memkeys # largest key per type by bytes (MEMORY USAGE)
redis-cli --keystats # top keys by memory, plus size percentiles and per-type totals
redis-cli --memkeys -i 0.01 # gentler on production
On the test dataset (200,000 small strings, a 200,000-field hash, a 50,000-member sorted set, a 3,000-item list, 300 small sets and one 500 KB string):
--bigkeys: Biggest list found "biglist" has 3000 items
Biggest hash found "catalog:index" has 200000 fields
Biggest string found "html:home" has 500000 bytes
Biggest zset found "leaderboard" has 50000 members
--memkeys: Biggest list found "biglist" has 9041 bytes
Biggest hash found "catalog:index" has 9923596 bytes
Biggest string found "html:home" has 524316 bytes
Biggest zset found "leaderboard" has 4256686 bytes
Element counts and bytes are different measures. The 3,000-item list takes about 3 bytes per item (a compact encoding, chapter 5.2), while the sorted set takes about 85 bytes per member (skiplist plus hash table). Use --bigkeys to find keys that make O(N) commands slow, and --memkeys to find keys that fill memory or unbalance a cluster.
--keystats (redis-cli 7.4+) adds the distribution, which tells you whether one outlier or a whole class of keys is the problem:
--- Top size per type ---
hash "catalog:index" is 9.46M
zset "leaderboard" is 4.06M
string "html:home" is 512.03K
Key size Percentile Total keys
-------- ---------- -----------
141B 50.0736% 100300
142B 99.9975% 200300 <- 99.99% of keys are tiny
8.83K 99.9985% 200302
4.06M 99.9995% 200304
9.46M 100.0000% 200305 <- two outliers
INFO keysizes (8.0+) keeps power-of-two histograms of element counts per type at no scanning cost, so it is suitable for continuous monitoring:
# Keysizes
db0_distrib_strings_sizes:64=200000 <- 200,000 strings of 64 to 127 bytes
db0_distrib_lists_items:2K=1 <- one list with 2,048 to 4,095 items
For very large datasets, scanning a production server may take too long. The alternative is offline: download a snapshot with redis-cli --rdb /tmp/dump.rdb (it runs a full sync, chapter 7.1) and analyze the file on another machine.
Hot keys: following the traffic
| Tool | Requirement | Notes |
|---|---|---|
redis-cli --hotkeys | An LFU maxmemory-policy (allkeys-lfu or volatile-lfu) | Scans keys and reads their OBJECT FREQ counters |
HOTKEYS START ... / GET / STOP | Redis 8.6+ | Tracks CPU time and network bytes per key, no LFU needed (chapter 8.4) |
MONITOR sample | Short time window | Count key frequencies offline (12.1); expensive |
| Cluster metrics | Per-node instantaneous_ops_per_sec | A node with far more ops than its peers usually owns a hot key |
| Application metrics | Instrumented client | The best source: counts per key prefix at the caller |
Without an LFU policy, --hotkeys refuses to run:
Error: ERR An LFU maxmemory policy is not selected, access frequency not tracked. ...
With allkeys-lfu, after 20,000 reads of session:7, 3,000 of session:42 and 300 of session:99:
$ redis-cli --hotkeys
hot key found with counter: 73 keyname: "session:7"
hot key found with counter: 36 keyname: "session:42"
hot key found with counter: 11 keyname: "session:99"
The counter is logarithmic, not a hit count: 20,000 reads gave 73, 3,000 gave 36. A difference of 37 points means two orders of magnitude, so read the counters as a ranking, not as a ratio. They also decay over time (lfu-decay-time), so they reflect recent traffic (chapter 5.3).
Fixing hot keys (summary)
| Technique | When it fits |
|---|---|
Client-side caching (CLIENT TRACKING, chapter 8.1) or a short in-process cache | Read-heavy keys that change rarely |
| Read from replicas | Reads tolerate slightly stale data |
Replicate the key: product:42:{0..7}, write all copies, read a random one | Very hot read keys in a cluster (copies land on different slots) |
Split counters: INCR views:42:{n} with random n, sum on read | Very hot write keys |
| Coalesce requests in the application | Many identical concurrent reads (request collapsing) |
Key Takeaways
- Big keys are found by scanning data (
--bigkeysfor element counts,--memkeysfor bytes,--keystatsfor distributions,INFO keysizescontinuously, offline RDB analysis for huge datasets). - Hot keys are found by observing traffic (
--hotkeyswith an LFU policy,HOTKEYSon 8.6+, per-node ops in a cluster, application metrics). - LFU counters are logarithmic and decay: use them for ranking.
- Scanners use
SCANand do not block, but add load. Throttle them with-ion busy servers.
Practice
- (Beginner) Create a dataset with
DEBUG POPULATEplus one 1,000,000-member set and one 2 MB string. Run--bigkeys,--memkeysand--keystats, and explain why the rankings differ.- (Intermediate) Switch to
allkeys-lfu, generate skewed traffic withredis-benchmarkagainst three keys at different rates, and compare--hotkeyswithHOTKEYS START METRICS 1 CPUon Redis 8.6+. Which tool would you rather use in production, and why?- (Interview) "In our 6-shard cluster, one primary runs at 95% CPU while the others are at 20%. Memory is balanced. What do you suspect and how do you confirm it?" Hint: balanced memory rules out one kind of problem. Think about per-node ops, the slots of the busiest keys and how to measure traffic per key.
Avoiding O(N) Commands
Redis is fast because almost every command touches a small, fixed amount of data. Commands whose cost grows with the size of the data, O(N), break that promise: on a small development dataset they take microseconds, in production they take hundreds of milliseconds, and because commands run one at a time (chapter 5.1), every other client waits. It is like a single checkout lane where one customer decides to pay for 10,000 items one by one.
The usual suspects, measured
From the slow log of the test server and a 1,000,000-key instance (Redis 8.10):
| Command | Data | Time | Blocks all clients for |
|---|---|---|---|
FLUSHALL (synchronous) | 1,000,000 keys with TTLs | 706.6 ms | 0.7 s |
FLUSHALL ASYNC | same | 0.15 ms | almost nothing, memory freed in a background thread |
KEYS * | 200,305 keys | 48.8 ms | |
HGETALL | 200,000 fields | 26.8 ms | plus time to send 4 MB to the client |
DEL | 200,000-field hash | 12.8 ms | |
UNLINK | same | < 1 ms | |
ZRANGE 0 -1 WITHSCORES | 50,000 members | 4.0 ms |
Commands to watch and their alternatives
| Risky command | Grows with | Safer alternative |
|---|---|---|
KEYS pattern | All keys in the database | SCAN with MATCH and COUNT (chapter 2.1), or maintain an index set |
HGETALL, SMEMBERS, LRANGE 0 -1, ZRANGE 0 -1 | Elements in the key | HSCAN/SSCAN/ZSCAN, ranged reads with LIMIT, or HMGET of the fields you need |
DEL of a large collection, FLUSHALL, FLUSHDB | Elements freed | UNLINK, FLUSHALL ASYNC, or lazyfree-lazy-user-del yes / lazyfree-lazy-user-flush yes |
| Expiry or eviction of a large key | Elements freed | lazyfree-lazy-expire yes, lazyfree-lazy-eviction yes; avoid big keys |
SUNION, SINTER, SDIFF, ZUNIONSTORE, ZINTERSTORE | Total elements in the inputs | Bound input sizes, run on a replica, or precompute incrementally |
SORT | Elements, times log N, plus GET patterns | Keep data pre-sorted in a sorted set |
LINDEX, LINSERT, LREM, LPOS on long lists | Position or length | Use a hash or sorted set when you need random access |
ZREMRANGEBYSCORE over a wide range | Elements removed | Trim in small batches, often |
| Lua scripts and functions that loop over keys or elements | Whatever they loop over | Process in chunks, from the client, with SCAN |
DEBUG RELOAD, SAVE | The whole dataset | BGSAVE |
All five lazyfree-* options are no by default in Redis 8.10 (checked with CONFIG GET lazyfree*). Turning on lazyfree-lazy-user-del makes every DEL behave like UNLINK, which is a simple, low-risk improvement for most deployments.
Checking complexity before shipping
The documentation of every command states its complexity, and COMMAND DOCS returns it from the server:
127.0.0.1:6379> COMMAND DOCS smembers
1) "smembers"
2) ...
5) "complexity"
6) "O(N) where N is the set cardinality."
Iterating instead of fetching everything
import redis
r = redis.Redis(decode_responses=True)
# Bad: one command returns 200,000 fields and blocks the server for ~27 ms
# fields = r.hgetall("catalog:index")
# Good: many short commands, other clients run in between
total = 0
for field, value in r.hscan_iter("catalog:index", count=1000):
total += int(value)
# Delete a big collection without blocking
r.unlink("catalog:index")
# Delete keys by pattern without KEYS: SCAN in batches, UNLINK each batch
batch = []
for key in r.scan_iter(match="tmp:*", count=1000):
batch.append(key)
if len(batch) == 500:
r.unlink(*batch)
batch.clear()
if batch:
r.unlink(*batch)
Preventing O(N) commands with ACLs
Instead of trusting every developer to remember, remove the worst commands from application users (chapter 11.1):
ACL SETUSER app on >app-pass ~app:* +@all -@dangerous
@dangerous includes KEYS, SORT, FLUSHALL, FLUSHDB and MONITOR (checked with ACL CAT dangerous). Commands like HGETALL cannot be banned without breaking legitimate uses on small keys, so pair ACLs with slow log alerts (12.1) and big-key scans.
Key Takeaways
- O(N) commands are harmless on small data and dangerous on large data, because one slow command blocks every client.
- Replace
KEYSwithSCAN, whole-collection reads with*SCANor ranged reads,DELwithUNLINK,FLUSHALLwithFLUSHALL ASYNC. - Enable
lazyfree-lazy-user-del(and the expiry/eviction variants) to move freeing into background threads. All are off by default. - Check complexity with
COMMAND DOCS, block the worst commands with ACLs, and watch the slow log.
Practice
- (Beginner) Create a set with 1,000,000 members. Time
SMEMBERS,SSCANwithCOUNT 1000(one call),DELandUNLINKwith the slow log at threshold 0.- (Intermediate) Write a script that deletes all keys matching
session:*from a 1,000,000-key database usingSCANandUNLINKin batches. Runredis-cli --latencyduring the deletion, then repeat withKEYSplusDELand compare the worst latency.- (Interview) "A nightly job computes
ZUNIONSTOREover 30 daily leaderboards with 2 million members each, and the API times out every night at 02:00. Propose three fixes." Hint: consider where the command runs, how big its inputs are, and whether the result could be maintained incrementally.
Linux Kernel Tuning (THP, overcommit)
Redis spends most of its life in user space, but a few kernel settings decide whether background saves succeed, whether latency stays flat during snapshots, and whether the server accepts all the connections you configured. Redis checks several of them at startup and prints a warning when they are wrong. Chapter 6.1 explained the mechanics of fork() and copy-on-write. This topic is the checklist.
The checklist
| Setting | Recommended | Why | Redis warns at startup? |
|---|---|---|---|
vm.overcommit_memory | 1 | With 0, the kernel may refuse fork() for BGSAVE, AOF rewrite and full syncs when memory looks tight, even though copy-on-write needs far less | Yes |
| Transparent Huge Pages | madvise or never (Redis also sets disable-thp yes for itself) | 2 MB pages make copy-on-write copy 512 times more memory per write and cause latency spikes | Yes, if it cannot disable THP for its process |
vm.swappiness | Low (1), and size memory so Redis never swaps | A swapped-out page turns a microsecond command into a millisecond disk read | No (check mem_fragmentation_ratio < 1) |
net.core.somaxconn | ≥ tcp-backlog (default 511) | The kernel silently caps the accept queue; connection bursts get dropped | Yes |
Open files (ulimit -n, LimitNOFILE) | ≥ maxclients + 32 | Each client is a file descriptor | Yes, and lowers maxclients |
net.ipv4.tcp_max_syn_backlog | ≥ tcp-backlog for very bursty connects | Pending handshakes queue | No |
The warning texts, taken from the 8.10 binary:
WARNING Memory overcommit must be enabled! Without it, a background save or replication may fail
under low memory condition. ... To fix this issue add 'vm.overcommit_memory = 1' to /etc/sysctl.conf
and then reboot or run the command 'sysctl vm.overcommit_memory=1' for this to take effect.
WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn
is set to the lower value of 128.
You requested maxclients of 10000 requiring at least 10032 max file descriptors.
Applying the settings
# /etc/sysctl.d/99-redis.conf
sudo tee /etc/sysctl.d/99-redis.conf <<'EOF'
vm.overcommit_memory = 1
vm.swappiness = 1
net.core.somaxconn = 1024
net.ipv4.tcp_max_syn_backlog = 1024
EOF
sudo sysctl --system
# THP: check, then set for the running kernel
cat /sys/kernel/mm/transparent_hugepage/enabled # "always [madvise] never" is fine
echo madvise | sudo tee /sys/kernel/mm/transparent_hugepage/enabled
# Make it permanent: kernel parameter transparent_hugepage=madvise, or a systemd unit at boot
# /etc/systemd/system/redis.service.d/limits.conf
[Service]
LimitNOFILE=65535
THP in practice
With disable-thp yes (the default; the option is present in the 6.2.24, 7.0 and later images tested), the server calls prctl(PR_SET_THP_DISABLE) on itself, so a host left at [always] is less harmful than it used to be. On the WSL2 test host, /sys/kernel/mm/transparent_hugepage/enabled was [always], and the Redis process showed THP_enabled: 0 in /proc/<pid>/status. Still, /proc/<pid>/smaps contained 2 MB of AnonHugePages allocated during startup, and LATENCY DOCTOR complained about them. Setting the host to madvise removes the question entirely.
Containers and managed platforms
vm.* settings and THP are not namespaced: a container sees and uses the host's values and cannot change them. On Docker hosts and Kubernetes nodes, set them on the node (node configuration, a privileged DaemonSet, or the cloud provider's node settings). net.core.somaxconn is namespaced and can be set per pod, but Kubernetes treats it as an "unsafe" sysctl that must be allowed on the kubelet first. On the WSL2 test host the container saw vm.overcommit_memory = 1 and somaxconn = 4096 from the host, so Redis printed neither warning.
CPU placement
On large multi-socket machines, keep Redis and its memory on one NUMA node, and keep the child process of BGSAVE away from the main thread's core. Redis has settings for this (all empty by default): server-cpulist, bio-cpulist, aof-rewrite-cpulist and bgsave-cpulist.
server-cpulist 0-3 # main thread and I/O threads
bio-cpulist 4 # background I/O (lazy free, fsync, close)
bgsave-cpulist 5-7 # fork children for RDB
aof-rewrite-cpulist 5-7
Key Takeaways
- Set
vm.overcommit_memory = 1, THP tomadviseornever, low swappiness,somaxconn≥tcp-backlog, and a file descriptor limit abovemaxclients. - Read the startup log: Redis warns about overcommit, THP, the TCP backlog and file descriptors.
- In containers,
vm.*and THP come from the host: fix them on the node, not in the pod. - On big hosts, consider NUMA placement and the
*-cpulistsettings to separate the main thread from fork children.
Practice
- (Beginner) On a Linux VM, read
vm.overcommit_memory, the THP mode,somaxconnandulimit -n, then startredis-serverand match each startup warning to one of them. Fix them all and restart until the log is clean.- (Intermediate) On a test VM with 4 GB RAM, load 2.5 GB of data and set
vm.overcommit_memory = 2(strict). RunBGSAVE, read the error in the log and theMISCONFbehavior on writes, then restore the setting.- (Interview) "We run Redis on Kubernetes and the pod logs show the overcommit warning. The developer added
sysctl -w vm.overcommit_memory=1to the container's entrypoint, and it fails. Why, and what is the right fix?" Hint: which kernel settings are namespaced, and who owns the node?
Network Latency Optimization
For a typical Redis command the server spends about a microsecond executing it, while the request and reply take tens or hundreds of microseconds to cross the network. On a fast LAN the network is most of the latency; across availability zones or regions it is almost all of it. Network optimization for Redis therefore has two goals: make each round trip shorter, and make fewer of them.
Where the time goes
GET user:42 from an application server, same availability zone
client lib ──► kernel ──► NIC ──► switch(es) ──► NIC ──► kernel ──► Redis (≈1 µs) ──► ... back
|<--------------------------- round trip: typically 100-500 µs ------------------------------>|
Throughput of ONE connection without pipelining = 1 / RTT (RTTs below are illustrative, except loopback)
RTT 0.07 ms (loopback) → ~14,000 req/s (measured: 13,146)
RTT 0.5 ms (same AZ) → 2,000 req/s
RTT 1.5 ms (cross-AZ) → ~670 req/s
RTT 70 ms (cross-region) → ~14 req/s
Making fewer round trips
| Technique | Round trips for 100 reads | Chapter |
|---|---|---|
100 GETs, one after another | 100 | |
One MGET with 100 keys | 1 | 2.2 |
| Pipeline of 100 commands | 1 (or a few, depending on buffers) | 4.3 |
| Lua script or function doing the logic server-side | 1 | 4.4 |
| Client-side cache hit | 0 | 8.1 |
Multi-key commands and pipelines are the biggest single improvement for chatty code. The benchmark above went from 121,051 to 1,237,624 GETs per second with -P 16.
Making each round trip shorter
| Measure | Effect |
|---|---|
| Put clients and Redis in the same availability zone (and Redis replicas near the readers) | Cross-zone round trips are typically several times longer than in-zone ones, and major clouds bill cross-zone traffic |
| Use Unix sockets when the client runs on the same host | 10 to 15% more throughput than loopback TCP in the tests above (14,403 vs 13,146 req/s with one connection; 1,404,494 vs 1,237,624 pipelined) |
| Reuse connections (pools) | A new TCP connection costs a handshake; a new TLS connection several round trips plus CPU (chapter 10.2) |
| Keep replies small | HGETALL of 200,000 fields sends megabytes; fetch only needed fields |
| Avoid overloaded hosts and noisy neighbors | Check --intrinsic-latency on the server host (12.1) |
Use io-threads when the main thread is busy with socket I/O | Helps with many connections and large replies (chapter 5.1) |
Redis sets TCP_NODELAY on client sockets, so Nagle's algorithm does not delay small replies. Most client libraries do the same on their side. If a client library lets you configure it, keep it enabled.
Measuring the network part
# From the application host: round trip including network
redis-cli -h redis.internal --latency-history -i 10
# From the Redis host itself: round trip without the network
redis-cli --latency
# Server-side execution time only
redis-cli INFO latencystats | grep -E 'usec_(get|set):'
The difference between the first and second measurement is the network. The difference between the second and the third is the server's own networking stack and event loop. In the tests, the server spent about 1 µs on a GET (latencystats), while a single client measured 63 µs at p50 over loopback and the Docker network.
TLS
TLS adds CPU for encryption and extra round trips at connection time. With long-lived pooled connections the steady-state cost is mostly CPU (chapter 11.2 measured it). Avoid patterns that open a new TLS connection per request, such as serverless functions without connection reuse.
Key Takeaways
- Network round trips, not Redis execution, dominate latency. One connection without pipelining can do at most 1/RTT requests per second.
- Reduce round trips with multi-key commands, pipelining, scripts and client-side caching.
- Shorten them by co-locating clients and Redis in the same zone, using Unix sockets on the same host, and reusing connections.
- Measure from the client host, from the server host and from
latencystatsto split network time from server time.
Practice
- (Beginner) Compute the maximum requests per second of one non-pipelined connection for RTTs of 0.1 ms, 1 ms and 50 ms. Then measure your own RTT with
redis-cli --latencyand compare it withredis-benchmark -c 1.- (Intermediate) Write a script that reads 1,000 keys with individual
GETs, withMGET, and with a pipeline. Run it from the Redis host and from another machine, and explain how the gap between the three methods changes with RTT.- (Interview) "Our API makes 40 Redis calls per request and has a p99 of 80 ms. The Redis server's p99 per command is 50 µs. Where is the time going, and what would you change first?" Hint: multiply round trips by RTT, and look for calls that could be batched or removed.
<a id="123-production-deployment"></a>
12.3 Production Deployment
Running Redis on a laptop takes one command. Running it for years, through node failures, upgrades, growth and mistakes, takes planning. This subchapter covers deployment on Kubernetes, keeping configuration under control, upgrading safely, moving data between servers, preparing for disasters and sizing for growth.
Deploying on Kubernetes
Kubernetes was designed first for stateless services: if a pod dies, start another one anywhere. Redis is stateful. Its data lives in memory and on disk, replicas and cluster nodes know each other by address, and a restart may mean loading gigabytes. Running Redis on Kubernetes works well, but only if the manifests account for identity, storage, memory accounting, probes and shutdown.
Options
| Approach | What you manage | Good for |
|---|---|---|
StatefulSet written by you | Everything: config, replication, failover (with Sentinel or Cluster) | Simple single instances, full control, learning |
| Helm chart | Values file; the chart creates StatefulSets, Services, Sentinel or Cluster | Fast start with replication or Sentinel |
| Operator (for example Redis Enterprise Operator, commercial; OT-Container-Kit redis-operator, open source) | Custom resources (RedisCluster, RedisReplication); the operator handles scaling, failover and upgrades | Many instances, day-2 automation |
| Managed service outside the cluster | Nothing but the client config | Teams that do not want to operate Redis |
Bitnami's charts were for years the most common choice. In 2025 Bitnami (now part of Broadcom) changed how its container images are distributed, moving the free catalog to a legacy repository that no longer gets updates. Check where a chart's images come from and whether they are still patched before adopting any chart or operator.
Why StatefulSet
A StatefulSet gives each pod a stable name (redis-0, redis-1), a stable DNS name through a headless Service (redis-0.redis-headless.<namespace>.svc.cluster.local), and its own PersistentVolumeClaim that follows the pod when it is rescheduled. A Deployment gives none of these.
A single-instance StatefulSet
apiVersion: v1
kind: ConfigMap
metadata:
name: redis-config
data:
redis.conf: |
port 6379
dir /data
appendonly yes
appendfsync everysec
# About 60-75% of the container memory limit: leave room for fork copy-on-write,
# client buffers and fragmentation (the fork child is in the same cgroup)
maxmemory 2800mb
maxmemory-policy noeviction
# Reached only through the Service; authentication via ACL users
protected-mode no
aclfile /etc/redis-acl/users.acl
---
apiVersion: v1
kind: Secret
metadata:
name: redis-acl
stringData:
users.acl: |
user default off
user app on >change-me-app-password ~app:* +@all -@dangerous
user probe on >change-me-probe-password +ping +info
---
apiVersion: v1
kind: Service
metadata:
name: redis-headless
spec:
clusterIP: None # headless: one DNS record per pod
selector: {app: redis}
ports: [{name: redis, port: 6379}]
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: redis
spec:
serviceName: redis-headless
replicas: 1
selector:
matchLabels: {app: redis}
template:
metadata:
labels: {app: redis}
spec:
terminationGracePeriodSeconds: 120 # time to finish the final save on SIGTERM
securityContext: {runAsUser: 999, runAsGroup: 999, fsGroup: 999} # "redis" user of the image
containers:
- name: redis
image: redis:8.10.3 # pin an exact version
# "args", not "command": "command" would replace the image's entrypoint script,
# which is what loads the bundled modules (search, JSON, time series, probabilistic)
args: ["redis-server", "/etc/redis/redis.conf"]
ports: [{name: redis, containerPort: 6379}]
env:
- name: REDISCLI_AUTH
value: change-me-probe-password # better: valueFrom a Secret
resources:
requests: {cpu: "1", memory: 4Gi}
limits: {memory: 4Gi} # requests = limits for memory: no overcommit by the scheduler
startupProbe: # loading a large dataset can take minutes
exec:
command: ["sh", "-c", "redis-cli --user probe ping | grep -q PONG"]
periodSeconds: 5
failureThreshold: 120 # up to 10 minutes
readinessProbe:
exec:
command: ["sh", "-c", "redis-cli --user probe ping | grep -q PONG"]
periodSeconds: 5
livenessProbe: # lenient: a busy server is not a dead server
exec:
command: ["sh", "-c", "redis-cli --user probe ping | grep -q PONG"]
periodSeconds: 10
timeoutSeconds: 5
failureThreshold: 6
volumeMounts:
- {name: data, mountPath: /data}
- {name: config, mountPath: /etc/redis}
- {name: acl, mountPath: /etc/redis-acl}
volumes:
- name: config
configMap: {name: redis-config}
- name: acl
secret: {secretName: redis-acl}
volumeClaimTemplates:
- metadata: {name: data}
spec:
accessModes: [ReadWriteOnce]
resources:
requests: {storage: 20Gi}
Details that matter:
- Probes must check the reply, not the exit code.
redis-cliexits with code 0 even when the server answers with an error such asLOADINGorNOAUTH(verified on 8.10:redis-cli FOOexits 0). Only a refused connection gives a non-zero code. Hence thegrep -q PONG. - Memory limits include more than the dataset. The kernel counts RSS of the main process and of the fork child created by
BGSAVEor AOF rewrites, which share the pod's cgroup. Ifmaxmemoryis close to the limit, the pod is OOM-killed during the first snapshot under write load (chapter 5.3). - Shutdown. On
SIGTERM, Redis waits up toshutdown-timeout(default 10 s) for lagging replicas, then saves an RDB ifsavepoints are configured (shutdown-on-sigterm default).terminationGracePeriodSecondsmust be longer than that save, or Kubernetes sendsSIGKILLhalfway through. - Kernel settings come from the node (12.2):
vm.overcommit_memoryand THP must be set on the node pool.
Replication, Sentinel and Cluster on Kubernetes
Pod IP addresses change on every restart, so Redis components must use DNS names:
| Setup | Settings |
|---|---|
| Replicas | replicaof redis-0.redis-headless.<ns>.svc.cluster.local 6379; set replica-announce-ip to the pod's DNS name if Sentinel must report names |
| Sentinel | sentinel resolve-hostnames yes and sentinel announce-hostnames yes (Redis 6.2+) |
| Cluster | cluster-announce-hostname <pod DNS name> and cluster-preferred-endpoint-type hostname (Redis 7.0+), so CLUSTER SHARDS and redirects carry names (chapter 10.2) |
Per-pod values come from the downward API, because Kubernetes expands $(VAR) in args:
env:
- name: POD_NAME
valueFrom: {fieldRef: {fieldPath: metadata.name}}
args:
- redis-server
- /etc/redis/redis.conf
- --cluster-announce-hostname
- $(POD_NAME).redis-headless.redis.svc.cluster.local
- --cluster-preferred-endpoint-type
- hostname
Spread primaries and replicas across nodes and zones with pod anti-affinity or topology spread constraints, and add a PodDisruptionBudget (maxUnavailable: 1) so that node drains do not take down a primary and its replica at the same time.
Key Takeaways
- Use a
StatefulSet(directly, through a Helm chart or through an operator) for stable names and per-pod volumes. Check that chart images are maintained. - Set
maxmemorywell below the container memory limit, because fork children and buffers count against the same cgroup. - Probes must check for
PONG, use a startup probe for long loads, and keep liveness lenient. GiveSIGTERMenough grace time to save. - Use DNS names everywhere (
replicaof, Sentinel hostname options,cluster-announce-hostname), spread pods across nodes and zones, and protect them with aPodDisruptionBudget.
Practice
- (Beginner) Deploy the StatefulSet above on a local cluster (kind or minikube), write some keys, delete the pod, and check that the data survives because of the PVC.
- (Intermediate) Change the probes to use only the exit code of
redis-cli ping, setuser default offwithout giving the probe credentials, and observe what Kubernetes reports. Then fix it and explain the difference.- (Interview) "Our Redis pod has a 4 GB limit and
maxmemory 3800mb. It runs fine for days, then gets OOM-killed a few minutes after a traffic peak. Explain." Hint: what process starts after enough writes, and which cgroup does it belong to?
Configuration Management
Over time, a Redis server's configuration drifts: someone runs CONFIG SET during an incident, a teammate edits the file on one node, a new replica is built from an old template. Months later nobody knows which settings are actually in force, and a restart silently undoes an important change. Configuration management means having one source of truth (usually a file in version control) and making the running servers match it.
The layers
redis.conf (and files it includes) ─┐
command-line arguments ─┼─► configuration at startup ─► CONFIG SET at runtime ─► CONFIG REWRITE
(later layers override earlier ones) ┘ (lost on restart) (writes runtime values back to the file)
| Layer | Example | Persists across restart? |
|---|---|---|
| Config file | maxmemory 100mb | Yes |
include | include /etc/redis/local.conf (directives after the include override it, earlier ones are overridden) | Yes |
| Command-line | redis-server /etc/redis.conf --port 6380 | Only if the same command is used |
CONFIG SET | CONFIG SET maxmemory 200mb | No, unless followed by CONFIG REWRITE |
What can change at runtime
Most parameters can be changed with CONFIG SET, and since Redis 7.0 several at once, atomically: if one value is invalid, none is applied.
127.0.0.1:6379> CONFIG SET maxmemory 200mb hz 20
OK
127.0.0.1:6379> CONFIG SET maxmemory 300mb hz abc
(error) ERR CONFIG SET failed (possibly related to argument 'hz') - argument couldn't be parsed into an integer
127.0.0.1:6379> CONFIG GET maxmemory
1) "maxmemory"
2) "209715200" <- still 200mb: the whole command was rejected
Tested on 8.10:
| Parameter | CONFIG SET result |
|---|---|
maxmemory, maxclients, port, bind | Allowed (changing port or bind moves the listener immediately) |
io-threads, databases, cluster-enabled, unixsocket, daemonize, enable-debug-command | can't set immutable config: needs a restart |
dir (and other protected configs) | can't set protected config unless enable-protected-configs allows it (chapter 11.2) |
CONFIG REWRITE and its surprises
CONFIG REWRITE rewrites the main config file so that it reflects the running configuration. It keeps comments and order where it can and appends the rest. A test with a main file that includes /data/local.conf (which sets maxmemory-policy allkeys-lru), after CONFIG SET maxmemory 200mb hz 20:
port 6379
protected-mode no
# app settings
maxmemory 200mb <- updated in place
include /data/local.conf
# Generated by CONFIG REWRITE
hz 20
latency-tracking-info-percentiles 50 99 99.9
maxmemory-policy allkeys-lru <- copied from the included file
save 3600 1
save 300 100
save 60 10000
dir "/data"
user default on nopass sanitize-payload ~* &* +@all
loadmodule /usr/local/lib/redis/modules//redisbloom.so <- from the Docker entrypoint's arguments
...
Three consequences:
- Values from included files are copied after the
includeline, so later edits to the included file no longer take effect. - Command-line arguments (here, the
--loadmoduleoptions added by the official image's entrypoint) become part of the file. - Defaults that were implicit (
saverules) become explicit.
If configuration is managed by a tool (Ansible, Puppet, a Helm values file, a Kubernetes ConfigMap, which is read-only anyway), avoid CONFIG REWRITE and treat CONFIG SET as a temporary measure that must be copied into the source of truth.
Keeping secrets out of the main file
Redis does not expand environment variables in its config file. Keep passwords out of version control by putting them in a separate file mounted from a secret store, and include it, or use an aclfile:
# redis.conf (in Git)
include /etc/redis/secrets.conf # mounted from a secret store, not in Git
aclfile /etc/redis/users.acl # ACL users, also mounted as a secret
Detecting drift
import redis
DESIRED = { # rendered from the same source as the config file
"maxmemory": str(3 * 1024**3),
"maxmemory-policy": "allkeys-lru",
"appendonly": "yes",
"slowlog-log-slower-than": "5000",
"latency-monitor-threshold": "100",
}
def drift(host):
r = redis.Redis(host=host, decode_responses=True)
actual = r.config_get("*") # dict of every parameter
return {k: (v, actual.get(k)) for k, v in DESIRED.items() if actual.get(k) != v}
for host in ["redis-a.internal", "redis-b.internal"]:
for key, (want, have) in drift(host).items():
print(f"{host}: {key} is {have!r}, expected {want!r}")
Run it on a schedule and after every incident, and alert on any difference.
Key Takeaways
- Keep one source of truth (a versioned file or template). Treat
CONFIG SETas temporary until it is copied there. - Multi-parameter
CONFIG SETis atomic. Some parameters are immutable (io-threads,databases,cluster-enabled, ...) and need a restart; protected ones are blocked by default. CONFIG REWRITEcopies included values, command-line arguments and implicit defaults into the main file. Avoid it when a tool manages the file.- Keep secrets in included or ACL files from a secret store, and detect drift by comparing
CONFIG GET *with the desired state.
Practice
- (Beginner) Start Redis with a config file, change
maxmemoryandhzwith oneCONFIG SET, restart the server, and check which values survived. Repeat withCONFIG REWRITEbefore the restart.- (Intermediate) Reproduce the
includesurprise: putmaxmemory-policyin an included file, runCONFIG REWRITE, then change the included file and restart. Which value wins, and why?- (Interview) "During an incident, an engineer raised
maxmemoryon all primaries withCONFIG SET. Two weeks later, after a routine restart, evictions started again. How would you prevent this class of problem?" Hint: single source of truth, drift detection, and a runbook step after every runtime change.
Upgrades and Version Migration
New Redis versions bring performance improvements, new commands and security fixes, and every release line eventually stops receiving patches. Upgrading is unavoidable. Because the whole dataset lives in one process, the upgrade has to replace that process without losing data and with as little downtime as possible. The tool for this is replication: start the new version next to the old one, let it copy the data, and move traffic over.
Compatibility rules
The on-disk format (RDB) is versioned, and a server can load files and replication streams from older versions but not from newer ones. The first bytes of an RDB file carry the version:
| Redis | RDB format |
|---|---|
| 7.2 | REDIS0011 |
| 7.4, 8.0, 8.2, 8.4 | REDIS0012 |
| 8.6 | REDIS0013 |
| 8.10 | REDIS0015 |
(Read from files saved by each official image: head -c 9 dump.rdb.)
| Direction | Result (tested) |
|---|---|
| 8.10 replica of a 7.2 primary | Works: Loading RDB produced by version 7.2.17, sync finished |
| 7.2 replica of an 8.10 primary | Fails: Can't handle RDB format version 15, and the replica flushes its own data before failing, then retries forever |
MIGRATE from 7.2 to 8.10 | Works |
MIGRATE (or DUMP/RESTORE) from 8.10 to 7.2 | Fails: ERR DUMP payload version or checksum are wrong |
Two practical rules follow: upgrade replicas before primaries, and a downgrade is not possible once the new version has written its own format. The rollback plan is the backup taken just before the upgrade, which loses every write made since then.
Rolling upgrade with replication
before step 1 step 2 step 3
P(7.4) ── R(7.4) P(7.4) ── R(8.10) R(7.4) ── P(8.10) P(8.10) ── R(8.10)
upgrade the replica switch roles upgrade the old primary
(restart with new binary) (FAILOVER, Sentinel, (it is now a replica)
or CLUSTER FAILOVER)
A coordinated switch with the FAILOVER command (Redis 6.2+), tested on 8.10: run on the primary, it pauses writes, waits until the replica has caught up, swaps roles, and redirects itself to replicate from the new primary.
# on the old primary
127.0.0.1:6379> FAILOVER TIMEOUT 5000
OK
127.0.0.1:6379> ROLE
1) "slave" ... # the old primary is now a replica
# on the new primary
127.0.0.1:6379> INFO replication
role:master
connected_slaves:1
A trap follows from the compatibility rules: after the switch, the old primary (still on the old version) replicates from the new one through a partial resync, which sends commands, not an RDB, so it looks healthy. The first full resync breaks it. In a test, a Redis Stack 7.4 server demoted by FAILOVER kept master_link_status:up until its link was cut with a small backlog; the forced full resync then logged Flushing old data and Can't handle RDB format version 15, and left it with DBSIZE 0. Upgrade the former primary right after the switch, and do not count it as a fallback.
With Sentinel, SENTINEL FAILOVER <name> does the same; with Cluster, CLUSTER FAILOVER on each upgraded replica (chapter 7). In a cluster, upgrade one shard at a time and watch error rates between steps.
Upgrade checklist
- Read the release notes of every version between the current and the target: removed options (for example
io-threads-do-reads, gone in Redis 8), changed defaults, deprecated commands, new reserved command names. - Check client libraries and modules against the new version in a staging environment, with production-like data loaded from a recent snapshot.
- Run your benchmark and integration tests against staging (12.2, chapter 10.3).
- Take and verify a backup right before the upgrade (6.3), and write down the rollback decision point.
- Upgrade replicas, verify
master_link_status:upand the offsets, then switch roles, then upgrade the former primaries. - Watch error rates, latency, memory and
INFO errorstatsfor at least a day before upgrading the next environment.
Key Takeaways
- Newer servers read older RDB files and replication streams; older servers reject newer ones (and a 7.2 replica flushes its data before failing).
- Upgrade replicas first, switch roles with
FAILOVER, Sentinel orCLUSTER FAILOVER, then upgrade the former primary. - A demoted old-version primary survives only partial resyncs: the next full resync flushes it. Upgrade it immediately.
- Downgrades are not possible after the new version writes data. The rollback plan is a pre-upgrade backup.
- Read every release note in between, test clients and modules in staging, and upgrade one shard or environment at a time.
Practice
- (Beginner) Run
redis:7.4as primary andredis:8.10as its replica in Docker. Check the replica's log for the RDB version line, then useFAILOVERon the primary and verify the roles.- (Intermediate) Try the reverse (a 7.4 replica of an 8.10 primary), write down every log line, and check
DBSIZEon the old replica before and after. Then write the runbook step that prevents this from happening by mistake.- (Interview) "You must upgrade a 12-shard Redis Cluster from 7.2 to 8.10 during business hours without downtime. Describe the plan and the rollback strategy." Hint: replica-first per shard,
CLUSTER FAILOVER, client behavior during failovers, and what "rollback" can mean when downgrades are impossible.
Data Migration Between Instances
Data has to move between Redis servers more often than one might expect: to a bigger machine, from self-hosted to a managed service, from a standalone instance to a cluster, between regions, or out of a shared instance into a dedicated one. The right method depends on how much data there is, whether writes can stop, whether the source and target can talk to each other, and which commands the target allows.
Methods
| Method | How | Downtime | Limitations |
|---|---|---|---|
| Replication | REPLICAOF source 6379 on the target, then promote | Seconds (cutover only) | Target must accept REPLICAOF (many managed services do not); target version ≥ source |
| RDB file | BGSAVE (or redis-cli --rdb file) on the source, copy, start the target with it | Writes since the snapshot are lost unless stopped | One-shot; version rule applies |
MIGRATE / DUMP + RESTORE | Copy key by key, with SCAN | None if writes are handled, or a write freeze | Slow for huge datasets; target version ≥ source; big keys block both servers |
redis-cli --cluster import | Copies keys from a standalone instance into a cluster | Write freeze for consistency | Uses MIGRATE internally |
| External tools (RIOT, RedisShake) | Snapshot plus live replication stream, or SCAN-based copy | Minutes to none | Extra moving parts; check version support |
| Application dual-write | Write to both, backfill, then switch reads | None | Application changes; consistency is the application's job |
Replication-based migration and cutover
Tested on 8.10: a fresh instance became a replica of a 200,305-key primary, completed the full sync and refused writes as expected:
redis-cli -h new REPLICAOF old.internal 6379
redis-cli -h new INFO replication | grep -E 'master_link_status|master_sync_in_progress'
# master_link_status:up
# master_sync_in_progress:0
redis-cli -h new DBSIZE
# (integer) 200305
redis-cli -h new SET x 1
# (error) READONLY You can't write against a read only replica.
The cutover:
1. CLIENT PAUSE 30000 WRITE on old (Redis 6.2+: reads continue, writes wait)
2. compare master_repl_offset (old) with slave_repl_offset (new) until equal
3. REPLICAOF NO ONE on new (it becomes a writable primary)
4. switch clients to new (DNS, service discovery, config reload)
5. CLIENT UNPAUSE on old, then make it read-only or shut it down
If the old and new servers can be primary and replica of each other directly, FAILOVER (previous topic) automates steps 1 to 3.
Getting a snapshot remotely
redis-cli --rdb asks the server for a replication snapshot (REPLCONF rdb-only) and saves it locally, without access to the server's file system:
$ redis-cli -h old.internal --rdb /tmp/dump.rdb
sending REPLCONF rdb-only 1
SYNC sent to master, writing bytes of bulk transfer until EOF marker to '/tmp/dump.rdb'
Transfer finished with success after 10626997 bytes
Key-by-key copy with DUMP and RESTORE
When replication is not available (for example, the target is a managed service that blocks REPLICAOF), a script can copy keys with their TTLs:
import redis
src = redis.Redis(host="old.internal") # bytes in, bytes out: no decoding
dst = redis.Redis(host="new.example.com", ssl=True, password="...")
BATCH = 500
copied = 0
keys = []
def flush(batch):
# Read DUMP payloads and TTLs for a whole batch in one round trip
p = src.pipeline(transaction=False)
for k in batch:
p.dump(k)
p.pttl(k)
res = p.execute()
w = dst.pipeline(transaction=False)
for k, payload, ttl in zip(batch, res[0::2], res[1::2]):
if payload is None: # key expired or deleted meanwhile
continue
# ttl: -1 = no expiry -> 0 for RESTORE; replace=True makes reruns idempotent
w.restore(k, ttl if ttl > 0 else 0, payload, replace=True)
w.execute()
return len(batch)
for key in src.scan_iter(count=1000):
keys.append(key)
if len(keys) == BATCH:
copied += flush(keys)
keys.clear()
if keys:
copied += flush(keys)
print(f"copied {copied} keys")
This copies a snapshot that is consistent per key, not across keys, and writes made during the copy may be missed. Either freeze writes, or run it once, switch with a short freeze, and re-copy recently changed keys (tracked by the application or by keyspace notifications). Big keys are copied in one RESTORE, which blocks the target for as long as it takes to rebuild them.
Key Takeaways
- Prefer replication: near-zero downtime, consistent, simple. Cut over with
CLIENT PAUSE WRITE, offset comparison andREPLICAOF NO ONE, or withFAILOVER. redis-cli --rdbdownloads a snapshot remotely. RDB files andDUMPpayloads load only on the same or a newer version.- Key-by-key copies with
SCAN,DUMP,PTTLandRESTORE ... REPLACEwork everywhere, but are not consistent across keys and need a plan for concurrent writes. - For live migrations into services that block replication, consider tools such as RIOT or RedisShake, or dual writes in the application.
Practice
- (Beginner) Migrate 100,000 keys from one container to another with
REPLICAOF, measure how long the full sync takes, and perform the cutover steps by hand.- (Intermediate) Run the DUMP/RESTORE script while a
redis-benchmarkwrites random keys to the source. Count the keys that differ afterwards (compareDBSIZEand sample values) and design a fix.- (Interview) "Move 300 GB from a self-hosted Redis 7.2 into a managed Redis 8 service that does not allow
REPLICAOF, with less than one minute of write downtime." Hint: a snapshot import plus a change stream (keyspace notifications, a tool that reads the replication stream, or dual writes), then a short freeze to drain the tail.
Disaster Recovery Planning
Replication and automatic failover (chapter 7) protect against a server crashing. They do not protect against a FLUSHALL typed in the wrong terminal, an application bug that overwrites every session, a compromised server, or the loss of a whole region. All of these spread to every replica within milliseconds. Disaster recovery (DR) is the plan for these cases: what can go wrong, how much data you may lose, how long you may be down, and the tested steps to come back.
Two numbers that define the plan
| Term | Question | Example target |
|---|---|---|
| RPO (Recovery Point Objective) | How much recent data may be lost? | "At most 1 hour of cache data", "at most 1 second of sessions" |
| RTO (Recovery Time Objective) | How long may the service be unavailable? | "15 minutes" |
The targets come from the business, not from Redis. A pure cache that can be rebuilt from the database may have an RPO of "everything" and an RTO of "as long as the database survives the cold cache". A Redis that is the system of record for orders needs much more.
Scenarios and what covers them
| Scenario | Persistence (AOF/RDB) | Replicas + failover | Backups off the host | Cross-region copy |
|---|---|---|---|---|
| Process crash | Yes | Yes | Yes | Yes |
| Host or disk lost | No | Yes | Yes | Yes |
| Availability zone lost | No | If replicas are in another zone | Yes | Yes |
| Region lost | No | No | If stored in another region | Yes |
FLUSHALL, bad bulk write, application bug | No (AOF may help, see below) | No: replicated instantly | Yes, to the last backup | No: replicated too |
| Server compromised, data encrypted or wiped | No | No | Yes, if attackers cannot reach backups | No |
The FLUSHALL row is the one teams forget. With AOF, a FLUSHALL is recorded as a command at the end of the file. If you stop the server before the next AOF rewrite, you can remove that last command from the AOF and restart (chapter 6.2). Once the rewrite has happened, only a backup helps.
Building blocks
- Backups (chapter 6.3): scheduled RDB copies, verified, kept in another location with retention rules, and protected from deletion (separate credentials, object lock or immutable storage).
- Verification: a backup that has never been loaded is a hope.
redis-check-rdbvalidates the structure and checksum:
$ redis-check-rdb /backups/dump-2026-11-10T0300.rdb
...
[offset 10626997] Checksum OK
[offset 10626997] \o/ RDB looks OK! \o/
[info] 200305 keys read
$ redis-check-rdb truncated.rdb
--- RDB ERROR DETECTED ---
- Restore time: loading is a large part of RTO. On the test machine, an RDB with 1,000,000 keys (40 MB on disk, 157 MB in memory) loaded in 1.25 seconds (
DB loaded from disk: 1.250 seconds), roughly 800,000 keys per second. Measure your own: time grows with the number of keys and with the cost of rebuilding structures and search indexes. - Cross-region: a replica in another region (asynchronous, so the RPO is the replication lag), or backups copied to another region. Active-Active (chapter 7.4) is the commercial option for writes in several regions.
- Prevention: ACL users without
@dangerousfor applications (12.2, chapter 11), separate credentials per environment so a script cannot run against production by mistake.
A runbook template
DR RUNBOOK: sessions-redis (system of record for user sessions)
Targets: RPO 1 h (hourly RDB backups to object storage, other region), RTO 30 min
A. Accidental data loss (FLUSHALL, bad bulk write)
1. Stop writes: scale the API to 0 or set it to maintenance mode
2. If AOF is on and no rewrite happened since: stop Redis, remove the bad command from the
AOF tail, start Redis (see chapter 6.2). Otherwise go to step 3.
3. Pick the last backup BEFORE the incident; run redis-check-rdb on it
4. Start a new instance from it (staging-sized test first if time allows)
5. Point clients to it, re-enable writes, announce the data loss window
B. Region loss
1. Promote the replica in region B: REPLICAOF NO ONE
2. Update DNS / service discovery for region B
3. Rebuild replicas in region B; later rebuild region A from region B
Owner: platform on-call. Last drill: 2026-10-15, restore took 11 min.
Drills
Schedule restore drills (quarterly, for example): restore the latest backup into a fresh instance, measure the time, compare key counts and a sample of values with production, and update the runbook with what went wrong. The drill is also the only reliable way to discover missing permissions, expired credentials or backups that silently stopped months ago.
Key Takeaways
- Replication protects against failures of machines, not against mistakes:
FLUSHALLand bad writes are replicated instantly. Only backups (and sometimes the AOF tail) bring data back. - Define RPO and RTO per Redis deployment, from the business impact, then choose persistence, replicas, backup frequency and cross-region copies to meet them.
- Verify backups with
redis-check-rdb, store them where an attacker or a script cannot delete them, and measure restore time. - Write a runbook per scenario and test it with regular drills.
Practice
- (Beginner) Take an RDB backup of a test instance, run
FLUSHALL, and restore the backup into a new container. Measure the total time from "incident" to "data back".- (Intermediate) With
appendonly yes, write data, runFLUSHALL, stop the server immediately, and recover the data by editing the AOF (chapter 6.2). Then repeat, but runBGREWRITEAOFbefore stopping. What changed?- (Interview) "Our Redis cluster has replicas in three availability zones and automatic failover. Management asks whether we still need backups. What do you answer?" Hint: list failure modes that replicas do not cover, and give a concrete example for each.
Capacity Planning
Redis keeps the whole dataset in memory, so running out of capacity is not a slow degradation: a full server starts evicting keys or refusing writes (depending on maxmemory-policy), and a saturated main thread adds latency to every request. Capacity planning estimates how much memory, CPU, network and connections a workload needs today, how fast that grows, and when to scale (vertically or by sharding, chapter 7.4) before the limit is reached.
Memory: per-key cost, measured
Memory is the first limit for most deployments, and the overhead per key is larger than the raw size of keys and values. On Redis 8.10, 1,000,000 string keys with ~14-byte names and 100-byte values (DEBUG POPULATE 1000000 session 100):
| Measurement | Value |
|---|---|
| Raw data (key + value) | ~114 bytes per key |
used_memory growth | 165 bytes per key (157 MB total) |
| Same keys with a TTL on each | 187 bytes per key (+22 bytes for the expiry) |
MEMORY USAGE session:123456 | 145 bytes (excludes part of the main hash table overhead) |
used_memory_rss (process) | 187 MB, fragmentation ratio 1.17 |
Small values have proportionally large overhead. Collections of small elements in compact encodings (chapter 5.2) are cheaper per element: the 3,000-item list in 12.2 used about 3 bytes per item.
Estimating from a sample
The reliable way to size a dataset is to load a representative sample and measure, or to measure an existing dataset by key prefix:
import random
from collections import defaultdict
import redis
r = redis.Redis(decode_responses=True)
SAMPLE = 20_000
bytes_by_prefix = defaultdict(int)
count_by_prefix = defaultdict(int)
# Take the first SAMPLE keys returned by SCAN: hash-table order is effectively random
for i, key in enumerate(r.scan_iter(count=1000)):
if i >= SAMPLE:
break
prefix = key.split(":", 1)[0]
bytes_by_prefix[prefix] += r.memory_usage(key, samples=5) or 0 # MEMORY USAGE, sampled for collections
count_by_prefix[prefix] += 1
total_keys = r.dbsize()
sampled = sum(count_by_prefix.values())
for prefix in sorted(bytes_by_prefix, key=bytes_by_prefix.get, reverse=True):
share = count_by_prefix[prefix] / sampled
avg = bytes_by_prefix[prefix] / count_by_prefix[prefix]
est = avg * share * total_keys
print(f"{prefix:<20} {share:6.1%} of keys avg {avg:8.0f} B ~{est / 2**20:8.1f} MB")
MEMORY USAGE slightly underestimates (it excludes part of the global hash table), so add 10 to 15% to its totals, or prefer the used_memory growth measured while loading a sample.
From dataset size to server size
memory needed per instance
= dataset (used_memory at the projected size)
× fragmentation allowance (1.1 - 1.5, measured: mem_fragmentation_ratio)
+ replication backlog (repl-backlog-size, default 1 MB; often raised to hundreds of MB)
+ client buffers (output buffers of replicas, Pub/Sub and slow clients)
+ copy-on-write headroom during BGSAVE / AOF rewrite (measured: rdb_last_cow_size;
up to the whole dataset under heavy writes)
+ operating system and other processes
Example: 40 GB projected dataset, fragmentation 1.2, 512 MB backlog, 1 GB buffers,
CoW headroom 30% of the dataset
= 40 × 1.2 + 0.5 + 1 + 12 = 61.5 GB → a 64 GB machine is tight; 96 GB or 2 shards of 32 GB data
Set maxmemory to the dataset budget (not the machine size), and alert well before it is reached (12.1).
CPU, network and connections
| Resource | How to estimate | Rule of thumb for headroom |
|---|---|---|
| Main thread CPU | Peak ops/s × cost per command, measured with your commands (12.2); used_cpu_user_main_thread rate | Keep the main thread under ~50-70% at peak, so spikes and forks have room |
| Network | Peak ops/s × (average request + reply size) | Example: 100,000 ops/s × 2 KB = 200 MB/s ≈ 1.6 Gbit/s, more than many cloud instances sustain |
| Connections | Application instances × pool size per instance (+ replicas, monitoring) | Stay well under maxclients and the file descriptor limit |
| Disk (with persistence) | RDB size (smaller than memory, here 40 MB for 157 MB in memory) × retained copies; AOF size between rewrites | Fast local disks for AOF with everysec/always |
Planning for growth
- Record the current peak values monthly:
used_memory, ops/s, network throughput, connections. - Fit a growth trend (or use business forecasts: users, sessions, catalog size).
- Compute when each resource reaches its threshold (for example 70% of
maxmemory, 60% main-thread CPU). - Start the scaling project (bigger instance, more shards, splitting workloads) early enough to finish before that date. Resharding a large cluster or migrating instances takes weeks of preparation, not hours.
Key Takeaways
- Measure per-key memory with your own data: 165 bytes per small string key (187 with a TTL) on Redis 8.10, far more than the raw bytes.
- Size servers for dataset × fragmentation plus backlog, client buffers and copy-on-write headroom, not for the dataset alone.
- Estimate CPU, network and connections from peak traffic, and keep headroom on the single main thread.
- Track growth monthly and start scaling before thresholds are reached; sharding and migrations take time.
Practice
- (Beginner) Load 1,000,000 keys with values of 20, 100 and 1,000 bytes (three runs) and compute bytes per key from
used_memory. Plot overhead as a percentage of raw data size.- (Intermediate) Run the sampling script on a dataset with three key prefixes of different types (strings, small hashes, large sorted sets), compare its estimate with
used_memory, and explain the difference.- (Interview) "Product expects 3x users next year. Today Redis uses 18 GB on a 32 GB machine at 40% main-thread CPU. What do you plan?" Hint: project each resource separately, include CoW and fragmentation headroom, and consider which limit is reached first and whether it calls for a bigger machine or for sharding.
<a id="124-extending-redis"></a>
12.4 Extending Redis
When the built-in commands and Lua scripts are not enough, Redis can load native code that adds new commands and data types. This subchapter covers the modules API, how modules are loaded and operated, how to write a small module, and the modules that ship with Redis 8.
Redis Modules API
Sooner or later, some teams need something Redis does not do: a data type that does not exist (a JSON document, a probabilistic filter, a search index), a command that must run faster than a Lua script, or logic that reacts to events inside the server. Before Redis 4.0 (2017), the only option was to fork Redis and patch its C source, then maintain that fork forever. Modules solve this. A module is a shared library (.so file) that the server loads into its own process. It talks to Redis only through a stable C API defined in one header file, redismodule.h, so the same module keeps working across Redis versions.
Think of Redis as a game console and modules as cartridges: the console defines the slot and the rules, and a cartridge can add whole new games without anyone opening the console. The flip side of the analogy also holds: a faulty cartridge can crash the console.
┌──────────────────────── redis-server process ────────────────────────┐
│ core: event loop, keyspace, replication, persistence, ACL │
│ ▲ │
│ │ RedisModule_* API (redismodule.h, ~400 functions in 8.10) │
│ ┌─────┴──────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐ │
│ │ search.so │ │ rejson.so │ │ bloom.so │ │ your .so │ │
│ └────────────┘ └──────────────┘ └─────────────┘ └──────────────┘ │
└──────────────────────────────────────────────────────────────────────┘
same address space: a crash in any module crashes Redis
What a module can do
| Capability | Main API functions | Example in the wild |
|---|---|---|
| New commands (with subcommands, docs, ACL categories) | RedisModule_CreateCommand, CreateSubcommand, SetCommandInfo, AddACLCategory | JSON.SET, FT.SEARCH |
| New data types, saved in RDB and AOF | RedisModule_CreateDataType, ModuleTypeSetValue (with save, load, rewrite, free, defrag callbacks) | ReJSON-RL (the type behind JSON.*) |
| Access keys directly | OpenKey, StringDMA, StringSet, list/hash/zset/stream key APIs | Fast commands on built-in types |
| Call existing commands | RedisModule_Call (like redis.call in Lua) | Simple compositions |
| Blocking commands and background work | BlockClient, UnblockClient, ThreadSafeContextLock | Long queries without blocking the main thread |
| React to events | SubscribeToKeyspaceEvents, SubscribeToServerEvent, AddPostNotificationJob | Indexes updated when a hash changes (the Query Engine) |
| Timers, forks, configs | CreateTimer, Fork, RegisterStringConfig/RegisterNumericConfig | bf-error-rate, search-workers in CONFIG GET |
| Custom authentication | RegisterAuthCallback (Redis 7.2+) | External identity providers |
| Replication control | ReplicateVerbatim, Replicate | Choose what replicas and the AOF receive |
Two levels of API
- High-level:
RedisModule_Call(ctx, "INCRBY", "sl", key, 5)runs a normal Redis command and returns a reply object, likeredis.callin Lua. Simple and safe, but every call goes through the full command machinery (lookup, argument parsing, reply building). - Low-level:
RedisModule_OpenKeyreturns a handle to the key, and functions such asStringDMA(direct memory access to a string value) orZsetAddchange it in place. More code, much faster.
Memory is either managed by hand (RedisModule_Free...) or automatically: after RedisModule_AutoMemory(ctx), keys, strings and replies created during the command are released when it returns.
Modules, Lua scripts and functions compared
| Lua scripts / functions (chapter 4.4) | Modules | |
|---|---|---|
| Language | Lua | C (or Rust, C++, Zig through bindings) |
| Deployment | Sent by clients (EVAL) or loaded as libraries (FUNCTION LOAD) | A file on the server's disk, loaded at startup or with MODULE LOAD |
| New data types | No | Yes |
| Background threads, timers, events | No | Yes |
| Safety | Sandboxed; a script error returns an error | Not sandboxed; a bug can crash the server or corrupt memory |
| Speed (measured below) | 4.24 µs per call for a small read-modify-write | 1.05 µs for the same logic |
| Availability on managed services | Almost everywhere | Usually only the provider's own module list |
The measurement comes from the module in "Writing a Custom Module" (a capped increment) and an equivalent Lua script, both called 4.3 million times. INFO commandstats reported usec_per_call of 1.05 for the module, 4.24 for EVALSHA, and 0.22 for a plain INCRBY on the same keys: a module beats Lua by 4x but still costs more than a native command.
Key Takeaways
- Modules are shared libraries loaded into the Redis process. They use the stable C API in
redismodule.h(Redis 4.0+). - They can add commands, data types, background work, event handlers, timers, configs and authentication methods.
RedisModule_Callis simple; the low-level key API is faster.- Modules run without a sandbox: they are fast and powerful, and a bug can take the whole server down. Prefer Lua scripts or functions when they are enough.
Practice
- (Beginner) Run
MODULE LISTandINFO modulesonredis:8.10. For each module, find one command it adds (COMMAND LIST FILTERBY MODULE <name>) and one configuration parameter it registers.- (Intermediate) Read
redismodule.hfor Redis 8.10 and list the functions you would need for a command that blocks the client, does work in a background thread, and replies when done. Sketch the control flow.- (Interview) "We need a rate limiter with sliding windows that handles 500,000 checks per second on one Redis node. Lua script or module?" Hint: compare per-call cost, operational constraints (managed services, deployment, crash risk) and whether the logic needs features Lua does not have.
Loading and Managing Modules
A module only helps if it is loaded the same way, in the same version, on every server that might see its commands or data: primaries, replicas, and any server that restores a backup. Most module incidents come from a server that lacks a module the others have.
Ways to load a module
# redis.conf: loaded at every startup, with optional arguments for the module
loadmodule /usr/local/lib/redis/modules/redisbloom.so
loadmodule /opt/redis/modules/capcounter.so
# Command line (this is how the official Docker image loads its bundled modules)
redis-server /etc/redis/redis.conf --loadmodule /opt/redis/modules/capcounter.so
# At runtime: blocked by default (enable-module-command no)
127.0.0.1:6379> MODULE LOAD /data/capcounter.so
(error) ERR MODULE command not allowed. If the enable-module-command option is set to "local", you can
run it from a local connection, otherwise you need to set this option in the configuration file, and then
restart the server.
# With enable-module-command local, from a loopback connection
127.0.0.1:6379> MODULE LOAD /data/capcounter.so
OK
# Redis 7.0+: pass module configuration values and arguments explicitly
127.0.0.1:6379> MODULE LOADEX /path/module.so CONFIG some-param 42 ARGS arg1 arg2
enable-module-command accepts no (default), local (loopback and Unix socket only) and yes. Keep it at no in production: loading native code at runtime is the final step of several real attacks (chapter 11.2).
Inspecting modules
# INFO modules
module:name=bf,ver=81001,api=1,filters=0,usedby=[],using=[],options=[handle-io-errors]
module:name=vectorset,ver=1,api=1,filters=0,usedby=[],using=[],options=[handle-io-errors|handle-repl-async-load]
module:name=search,ver=81001,api=1,filters=0,usedby=[],using=[ReJSON],options=[handle-io-errors]
module:name=timeseries,ver=81001,api=1,filters=0,usedby=[],using=[],options=[handle-io-errors]
module:name=capcounter,ver=1,api=1,filters=0,usedby=[],using=[],options=[]
module:name=ReJSON,ver=81000,api=1,filters=0,usedby=[search],using=[],options=[handle-io-errors]
ver=81001 means 8.10.1. using and usedby show dependencies: the Query Engine (search) uses JSON to index JSON documents. Modules register their settings as normal configuration parameters:
127.0.0.1:6379> CONFIG GET bf-error-rate
1) "bf-error-rate"
2) "0.01"
127.0.0.1:6379> CONFIG GET search-workers
1) "search-workers"
2) "12"
Unloading
MODULE UNLOAD <name> works only for modules that do not own data. Tested on 8.10:
127.0.0.1:6379> MODULE UNLOAD capcounter
OK
127.0.0.1:6379> MODULE UNLOAD bf
(error) ERR Error unloading module: the module exports one or more module-side data types, can't unload
In practice, removing or upgrading a module means restarting the server (or, without downtime, replacing it through a replica as in 12.3).
What happens when a server lacks a module (tested)
| Situation | Result |
|---|---|
loadmodule points to a missing file at startup | Can't load module from /modules/capcounter.so: server aborting: the server does not start |
| A replica without the module receives a module command through replication | The replica logs == CRITICAL == This replica is sending an error to its master: 'unknown command 'CAP.INCR' ...', keeps master_link_status:up, and silently diverges from its primary |
| A replica without a module data type receives an RDB containing it | The RDB file contains module data I can't load: no matching module type 'ReJSON-RL', and the replica process exits |
| A restore from backup on a server without the module | Same as the previous row: the RDB cannot be loaded |
The second row is the most dangerous, because nothing looks broken: replication is "up", but a failover would promote a replica with different data.
Operational rules
- Load the same modules, in the same versions, on all primaries, replicas and restore targets. Include module files in your configuration management and container images.
- Upgrade modules like the server: replicas first, then fail over (12.3). Check the module's release notes for format changes.
- Keep
enable-module-command no, store modules in directories only root can write, and give no ACL user theMODULEcommand. - Watch the log for
CRITICALmessages from replicas, and alert on them. - Know your image's behavior: the official
redis:8.10image loads its bundled modules through its entrypoint script. Overriding the entrypoint (for exampledocker run --entrypoint redis-server, or a Kubernetescommand:) drops them:MODULE LISTthen shows only the built-invectorset.
Key Takeaways
- Load modules with
loadmodulein the config or--loadmoduleon the command line.MODULE LOAD/LOADEXat runtime requireenable-module-command, which should stayno. MODULE LISTandINFO modulesshow names, versions and dependencies; module settings appear inCONFIG GET.- Modules that own data types cannot be unloaded.
- Every server that may see a module's commands or data needs the module: a replica without it diverges silently (commands) or crashes (data types).
Practice
- (Beginner) Start
redis:8.10normally and with--entrypoint redis-server. CompareMODULE LIST,INFO modules, andused_memory_rss(26.9 MB vs 16.9 MB on the test machine).- (Intermediate) Reproduce the silent divergence: a primary with a custom module and a replica without it. Write a check (script or alert rule) that would detect the situation within minutes.
- (Interview) "After a failover,
JSON.GETreturns errors on the new primary, and some keys seem to be missing. What happened, and how do you prevent it?" Hint: compare the module lists of all nodes, look for module data types in the replication stream, and check how the replica was built.
Writing a Custom Module
The best way to understand the modules API is to write a small module. This one adds CAP.INCR key increment max: it increments an integer like INCRBY, but never beyond a maximum. Doing this from a client needs a GET and a SET inside a transaction or a script. As a module command it is a single atomic step, because commands, including module commands, run on the main thread one at a time.
The source
#include "redismodule.h" /* the only header needed: copy it from the Redis source tree (src/redismodule.h) */
/* CAP.INCR key increment max
* Adds increment to the integer stored at key, but never beyond max.
* Returns the new value. Atomic, because modules run on the main thread. */
static int CapIncr_RedisCommand(RedisModuleCtx *ctx, RedisModuleString **argv, int argc) {
if (argc != 4) return RedisModule_WrongArity(ctx); /* standard "wrong number of arguments" error */
RedisModule_AutoMemory(ctx); /* free keys and strings on return */
long long incr, max;
if (RedisModule_StringToLongLong(argv[2], &incr) != REDISMODULE_OK ||
RedisModule_StringToLongLong(argv[3], &max) != REDISMODULE_OK || incr < 0 || max < 0)
return RedisModule_ReplyWithError(ctx, "ERR increment and max must be non-negative integers");
/* Low-level API: a handle to the key, opened for reading and writing */
RedisModuleKey *key = RedisModule_OpenKey(ctx, argv[1], REDISMODULE_READ | REDISMODULE_WRITE);
int type = RedisModule_KeyType(key);
if (type != REDISMODULE_KEYTYPE_EMPTY && type != REDISMODULE_KEYTYPE_STRING)
return RedisModule_ReplyWithError(ctx, REDISMODULE_ERRORMSG_WRONGTYPE);
long long current = 0;
if (type == REDISMODULE_KEYTYPE_STRING) {
size_t len;
const char *buf = RedisModule_StringDMA(key, &len, REDISMODULE_READ); /* direct access, no copy */
RedisModuleString *s = RedisModule_CreateString(ctx, buf, len);
if (RedisModule_StringToLongLong(s, ¤t) != REDISMODULE_OK)
return RedisModule_ReplyWithError(ctx, "ERR value is not an integer");
}
long long next = (current > max - incr) ? max : current + incr; /* never computes current + incr past max */
if (next < current) next = current; /* value was already above max */
RedisModule_StringSet(key, RedisModule_CreateStringFromLongLong(ctx, next));
RedisModule_ReplicateVerbatim(ctx); /* send the same command to replicas and AOF */
return RedisModule_ReplyWithLongLong(ctx, next);
}
/* Called once when the module is loaded */
int RedisModule_OnLoad(RedisModuleCtx *ctx, RedisModuleString **argv, int argc) {
REDISMODULE_NOT_USED(argv); /* module arguments from loadmodule / MODULE LOAD */
REDISMODULE_NOT_USED(argc);
if (RedisModule_Init(ctx, "capcounter", 1, REDISMODULE_APIVER_1) == REDISMODULE_ERR)
return REDISMODULE_ERR; /* name, module version, API version */
/* flags: writes data, refused when maxmemory is reached (deny-oom), constant time (fast).
* Key positions: first key at argv[1], last key at argv[1], step 1. Cluster routing and
* ACL key checks rely on these numbers. */
if (RedisModule_CreateCommand(ctx, "cap.incr", CapIncr_RedisCommand,
"write deny-oom fast", 1, 1, 1) == REDISMODULE_ERR)
return REDISMODULE_ERR;
return REDISMODULE_OK;
}
Building and loading
# redismodule.h must match (or be older than) the target server's API: use the server's version tag
curl -sO https://raw.githubusercontent.com/redis/redis/8.10.3/src/redismodule.h
gcc -O2 -Wall -Wextra -fPIC -std=gnu99 -shared -o capcounter.so capcounter.c
# Run it in the official image (copy the file in, then start with --loadmodule)
docker create --name rmod redis:8.10 redis-server --loadmodule /data/capcounter.so
docker cp capcounter.so rmod:/data/capcounter.so
docker start rmod
docker logs rmod | grep capcounter
# * Module 'capcounter' loaded from /data/capcounter.so
Testing it (output from Redis 8.10.3)
127.0.0.1:6379> CAP.INCR c 5 12
(integer) 5
127.0.0.1:6379> CAP.INCR c 5 12
(integer) 10
127.0.0.1:6379> CAP.INCR c 5 12
(integer) 12 <- capped
127.0.0.1:6379> CAP.INCR c 1 -3
(error) ERR increment and max must be non-negative integers
127.0.0.1:6379> SET s hello
OK
127.0.0.1:6379> CAP.INCR s 1 5
(error) ERR value is not an integer
127.0.0.1:6379> LPUSH l a
(integer) 1
127.0.0.1:6379> CAP.INCR l 1 5
(error) WRONGTYPE Operation against a key holding the wrong kind of value
127.0.0.1:6379> CAP.INCR c 9223372036854775807 9223372036854775807
(integer) 9223372036854775807 <- no overflow
127.0.0.1:6379> COMMAND INFO cap.incr
1) 1) "cap.incr"
2) (integer) -1 ... <- arity, then flags: write denyoom module fast
Redis adds the module flag by itself. With a replica that also loads the module, CAP.INCR repl:test 7 10 twice on the primary produced 10 on the replica too: ReplicateVerbatim sent the command through the replication stream.
Performance
With 50 connections and pipelines of 16 (redis-benchmark -P 16 -r 1000), on 1,000 random keys:
| Command | Requests/s | usec_per_call (server) |
|---|---|---|
INCRBY (native, no cap) | ~975,000 | 0.22 |
CAP.INCR (module) | ~520,000 | 1.05 |
EVALSHA of the equivalent Lua script | ~184,000 | 4.24 |
The module costs more than INCRBY mainly because it parses the value through a temporary string and replicates the command explicitly. Still, it is four times cheaper than the script.
Going further
- Command metadata:
RedisModule_SetCommandInfoadds arguments, documentation and key specs (forCOMMAND DOCSand cluster-aware clients);RedisModule_SetCommandACLCategoriesputs the command into ACL categories so-@writerules cover it. - Configuration:
RedisModule_RegisterNumericConfigplusRedisModule_LoadConfigsmakescapcounter.default-maxsettable withCONFIG SETandMODULE LOADEX ... CONFIG. - Testing: test through a client (redis-py or the Redis test suite in Tcl) against a server that loads the module, and run the server under AddressSanitizer or Valgrind in CI: memory errors in modules corrupt the server's memory, not just the module's.
- Other languages: the Rust crate
redis-modulewraps the same API with memory safety for module code. RedisJSON is written in Rust.
Key Takeaways
- A module needs
redismodule.h, aRedisModule_OnLoadthat callsRedisModule_Initand registers commands, and command handlers that parse arguments, work on keys and reply. - Command flags (
write,deny-oom,fast, ...) and key positions matter: Redis uses them for OOM handling, ACL key checks, cluster routing andCOMMAND INFO. - Use
AutoMemoryfor simple memory management andReplicateVerbatim(orReplicate) so replicas and the AOF stay consistent. - Measure: a module command can be several times faster than Lua, and still slower than a native command.
Practice
- (Beginner) Build and load
capcounter, then add a second commandCAP.GET keythat returns the value or 0 for a missing key. Register it with thereadonly fastflags.- (Intermediate) Add a module configuration
capcounter.default-max(numeric, registered withRedisModule_RegisterNumericConfig) and makemaxoptional inCAP.INCR. Load the module withMODULE LOADEX ... CONFIG capcounter.default-max 100and change it withCONFIG SET.- (Interview) "Why does a module command have to declare its key positions, and what breaks if they are wrong?" Hint: think about cluster slot checks and redirections, ACL key permissions, and client libraries that route commands by key.
Redis Stack and Bundled Modules
For years, Redis Ltd. developed its most popular capabilities (JSON documents, full-text and vector search, time series, Bloom filters) as separate modules. Installing and matching them by hand was tedious, so in 2022 they were packaged together as Redis Stack: the server plus RediSearch, RedisJSON, RedisTimeSeries, RedisBloom (and, for a while, RedisGraph), distributed as redis-stack-server packages and the redis/redis-stack Docker images, with Redis Insight included. Redis 8.0 (May 2025) made this unnecessary: those capabilities became part of Redis Open Source itself, and vector sets were added as a native data type (chapter 1).
What ships with Redis 8.10
Module (MODULE LIST name) | File in the official image | Provides | Chapter |
|---|---|---|---|
ReJSON | rejson.so | JSON data type and JSON.* commands | 3.5 |
search | redisearch.so | Query Engine: secondary indexes, full-text, vector search (FT.*) | 9.1, 9.2 |
timeseries | redistimeseries.so | Time series (TS.*) | 3.5 |
bf | redisbloom.so | Bloom, Cuckoo, Count-Min Sketch, Top-K, t-digest (BF.*, CF.*, CMS.*, TOPK.*, TDIGEST.*) | 3.2 |
vectorset | none (compiled into the server) | Vector sets (VADD, VSIM, ...) | 9.2 |
Checked in the redis:8.10 image: the four .so files live in /usr/local/lib/redis/modules/, and the entrypoint script adds a --loadmodule argument for each one it finds. vectorset has no path in MODULE LIST because it is built in. The module versions follow the server (8.10.1 modules with server 8.10.3).
Redis Stack vs Redis 8
| Redis Stack (7.x) | Redis Open Source 8.x | |
|---|---|---|
| Packaging | Separate distribution: redis-stack-server, redis/redis-stack images | The standard redis image and packages |
| Modules | Loaded from the Stack's module directory | Bundled; loaded by the image's entrypoint (or built into the binary for vector sets) |
| Versions | Stack version per bundle (e.g. 7.4.0-v1) | Modules versioned with the server |
| Vector sets | No | Yes, native |
| License | Server BSD up to 7.2, RSALv2/SSPLv1 from 7.4; modules RSALv2/SSPLv1 | Tri-license RSALv2 / SSPLv1 / AGPLv3 (chapter 1) |
For new deployments, use Redis 8 directly. An existing Redis Stack 7.x deployment migrates like any upgrade (12.3). Tested: a redis:8.10 replica of a redis/redis-stack-server:7.4.0-v1 primary loaded its RDB (Loading RDB produced by version 7.4.1) with a JSON document, a search index, a Bloom filter and a time series. After FAILOVER, JSON.GET, FT.SEARCH, BF.EXISTS and TS.GET all worked on the new 8.10 primary, and a document added there was found by the index created on 7.4.
Operational notes
- Not every Redis 8 build has the modules. The official Docker image does. In the 8.10.3 source tree, the release tarball contains the module sources and
makebuilds them, but only with a heavier toolchain (the README lists LLVM 21, CMake 3.25 to 3.31.6 and Rust 1.94, installable withmake bootstrap);make build redisbuilds the core only, and a git checkout needsmake modules-updatefirst. Distribution packages may leave the modules out. Always checkMODULE LISTon a new environment before relying onJSON.*orFT.*. - Baseline memory: the bundled modules add memory even when unused. An idle
redis:8.10container used 26.9 MB RSS with them and 16.9 MB without (--entrypoint redis-server).used_memory_startupwent from 0.7 MB to 1.4 MB. - Background threads: the Query Engine starts worker threads (
search-workers, 12 on the 12-core test machine). Account for them when sizing CPU next to the main thread. - Valkey and other forks do not include these modules. Equivalent functionality comes from different projects (
valkey-json,valkey-bloom,valkey-search) with partly different commands (chapter 1). - Managed services decide which modules are available, often in specific versions. Check before designing around a capability.
Key Takeaways
- Redis Stack bundled the JSON, search, time series and probabilistic modules on top of Redis 7.x. Since Redis 8.0, they are part of Redis Open Source and vector sets are native.
- In the official
redis:8.10image,ReJSON,search,timeseriesandbfare loaded from/usr/local/lib/redis/modules/by the entrypoint;vectorsetis built in. - Verify with
MODULE LISTon every environment: source builds, distribution packages, custom entrypoints and forks may lack the modules. - The modules cost baseline memory and threads, and their data types require the same modules on every replica and restore target.
Practice
- (Beginner) Start
redis:8.10, create one JSON document, one time series, one Bloom filter and one vector set, then runTYPEon each key and match the result to the module that owns it.- (Intermediate) Run
redis/redis-stack-server:7.4.0-v1(or another 7.x Stack image) as a primary with JSON and search data, and attach aredis:8.10replica. Verify that indexes and documents are usable on the replica, then fail over withFAILOVERand query again.- (Interview) "Our team wants to use the Query Engine, but production runs on a managed Redis-compatible service. What do you check before writing any code?" Hint: engine and version, which modules and module versions the service offers, command compatibility, and what happens to the data model if you ever need to move to another provider.