Keeping the single command thread fast.

A Valkey server executes commands on one thread. That is the design, not a limit to fix: a single thread means a command runs to completion with no lock and no other command interleaved, which is what makes one SET or a Lua script atomic. The cost of the design is that the one thread is a shared resource — whatever it spends a millisecond on is a millisecond no command runs.

The committed tuning surface states the premise plainly. The box is a Fly shared-cpu-2x: command execution takes the first vCPU, and the second is reserved for the background helpers — AOF fsync, fork copy-on-write, jemalloc purge, lazy frees, active defrag — so none of that work lands on the command thread.

Memory access is measured in nanoseconds; a disk read is measured in milliseconds. When the kernel swaps a page of the dataset out to disk, the next read of that page pays the disk cost — the source puts the slowdown at roughly 1,000,000×. A single swapped page can be enough to time a client out, and the stall arrives with no warning at the server.

The fix is a kernel setting, not a server setting. vm.swappiness lives in the Linux VM and is set with sysctl — it is not a line in valkey.conf:

The source is specific about the value: 1, not 0. Zero forbids swap entirely, which can turn memory pressure into an OOM kill; one makes swapping extremely unlikely while still letting the kernel swap in a genuine emergency rather than killing the process. The manuscript states the same trade in one line: swappiness is set to its lowest practical value, because a swapped page trades nanoseconds for milliseconds.

Three settings move steady-state work off the command thread and onto the second vCPU.

io-threads 1 on a shared-CPU box. Extra I/O threads busy-wait — they spin rather than sleep, which pins the CPU near 100% and drains a shared machine’s burst balance even while idle. The background helper threads (fsync, jemalloc background purge) sleep between cycles, so they are the right tenants for the second vCPU; the I/O threads are not.

Lazy frees (lazyfree-lazy-*). Freeing a large value is itself work, and done inline it runs on the command thread. The lazy-free settings hand that work to a background thread instead: an eviction, an expiry, a server-side delete, a user DEL, and a FLUSH each return immediately and reclaim the memory off-thread, so a single big delete does not stall the commands behind it.

jemalloc-bg-thread yes. jemalloc’s background purge thread sleeps between cycles and returns unused pages to the OS off the main thread, so reclaiming memory never costs a command.

Valkey uses jemalloc, well-suited to its allocation patterns, with one behaviour to watch. After a large amount of data is deleted, jemalloc retains the freed memory to satisfy future allocations rather than returning it all to the OS — so process RSS reflects peak usage, not the current dataset size. Over time the live objects can scatter across sparse runs, and the allocator works harder to place each new value: fragmentation.

The number to watch is mem_fragmentation_ratio in INFO MEMORY. The source gives three bands:

MEMORY PURGE forces jemalloc to return memory to the OS on demand. Better, the server can keep the ratio near 1 continuously: activedefrag yes relocates live objects out of sparse runs so empty pages are purged. The committed config pairs it with gentle cycle bounds — active-defrag-cycle-min 1 and active-defrag-cycle-max 25 — so defrag never takes more than a small slice of any cycle and the main thread is never starved.

A spike you cannot see is a spike you cannot fix. The committed config turns on three observation surfaces:

One caveat the config calls out: on Valkey 9.1, watch used_active_time_main_thread (via INFO) for true headroom — with I/O threads the raw CPU figure busy-waits near 100% and hides spare capacity, so the main-thread time is the honest number.

A latency spike on a single-threaded store is almost always work that landed on the command thread. Swap is the worst case and the cheapest fix (vm.swappiness=1, in the kernel). Lazy frees, one I/O thread, and the jemalloc background thread keep steady-state work off the thread; active defrag keeps the heap from forcing the allocator to work; and the slow log plus the latency monitor make a spike visible. The next dive turns to durability — AOF, noeviction, and the connection settings that keep a burst of clients from being dropped.