Debugging

Tools, log channels, and workflow for diagnosing issues in redis-server.

Logs

redis-server writes to a single text log. The file path comes from the logfile directive (empty string means stdout). The verbosity is controlled by loglevel debug|verbose|notice|warning|nothing. By default it logs at notice. Inside the code, the macros are in src/server.h:

#define LL_DEBUG    0
#define LL_VERBOSE  1
#define LL_NOTICE   2
#define LL_WARNING  3
#define LL_NOTHING  4

void serverLog(int level, const char *fmt, ...);   /* src/server.c */

Every log line goes through serverLog. There is also serverLogRaw (no role/PID prefix), serverLogFromHandler (signal-safe), and serverLogObjectDebugInfo for dumping object internals.

The watchdog

watchdog-period (configured in milliseconds) installs a SIGALRM handler that fires if the main thread fails to advance the event loop within the period. The handler dumps the call stack of all threads to the log via src/threads_mngr.c. This is the canonical way to find latency culprits in production. Implementation: watchdogScheduleSignal() and friends in src/server.c; the cross-thread stack capture in src/threads_mngr.c.

INFO

INFO is the main runtime introspection command. The reply is grouped by section:

Section	What it tells you
server	Version, build id, mode (standalone / cluster / sentinel), OS, arch, uptime.
clients	Connected clients, max input buffer size, blocked clients.
memory	used_memory, fragmentation, allocator stats, per-DB key counts.
persistence	RDB/AOF state, last save, last error, child PIDs.
stats	Total commands processed, evictions, key hits/misses, expirations.
replication	Role, replicas, lag, backlog size, master link state.
cpu	User/system CPU time.
commandstats	Per-command call count and latency.
latencystats	Latency distribution histograms (uses hdr_histogram).
cluster	Cluster mode flag and short cluster info.
keyspace	Per-DB key/expire/avg-TTL counts.

The dispatcher is genRedisInfoString() in src/server.c. To add a section, append to that function and document the keys.

DEBUG

DEBUG is the kitchen-sink command for troubleshooting. The implementation is in src/debug.c. Notable subcommands:

• DEBUG OBJECT <key> — dump encoding, refcount, serializedlength.
• DEBUG SLEEP <seconds> — block the main thread; useful for testing client timeouts.
• DEBUG JMAP — dump jemalloc stats (when built with jemalloc).
• DEBUG SEGFAULT / DEBUG PANIC — force a crash; tests crash recovery.
• DEBUG RELOAD — save RDB then load it; round-trips the dataset.
• DEBUG LOADAOF — re-load AOF.
• DEBUG SLEEP-AFTER-FORK-SECONDS — slow down the BGSAVE child.
• DEBUG SET-ACTIVE-EXPIRE 0/1 — toggle the active-expiration cron.
• DEBUG STRINGMATCH-LEN — exercise the glob matcher.
• DEBUG STACK-TRACE — dump all thread stacks (uses threads_mngr.c).
• DEBUG CHANGE-REPL-ID, DEBUG SDSLEN, DEBUG QUICKLIST-PACKED-THRESHOLD, …

Most are deliberately undocumented in user-facing docs. They are for debugging the server, not for application code.

LATENCY

Latency monitoring (src/latency.c) records spikes in operations that exceed latency-monitor-threshold ms. Subcommands:

• LATENCY LATEST — most recent per-event latency.
• LATENCY HISTORY <event> — past spikes.
• LATENCY GRAPH <event> — ASCII spark line.
• LATENCY DOCTOR — heuristic recommendations.
• LATENCY HISTOGRAM — histogram (RESP3 reply).

SLOWLOG

The slowlog (src/slowlog.c) is a ring buffer of commands that exceeded slowlog-log-slower-than microseconds. SLOWLOG GET 10 returns the last 10 with timestamps and the originating client.

MONITOR and CLIENT TRACKINGINFO

MONITOR makes the server stream every command it sees back to the client. Useful for live debugging but it slows the server significantly.

CLIENT TRACKINGINFO returns the client-side caching state. CLIENT LIST lists every connected client with their query buffer size, pending output, last command, and idle time.

Crash handlers

If redis-server crashes, the SIGSEGV/SIGBUS/SIGFPE handlers in src/debug.c print:

• The signal info and current command.
• The full call stack (via backtrace / addr2line if available).
• Register dump on supported architectures.
• Memory test results (memtest) if crash-memcheck-enabled yes.
• The INFO payload.
• A "fast memory test" derived from src/memtest.c.

The output ends with the logo and a notice about crash-log-enabled. If the crash log is disabled the handlers re-raise the signal so the OS can dump core.

Memory test mode

redis-server --test-memory <megabytes> runs the same memory test that the crash handler invokes (src/memtest.c). Useful for ruling out flaky RAM during persistent issues.

Running under gdb / lldb

gdb --args ./src/redis-server ./redis.conf
(gdb) handle SIGPIPE nostop noprint pass
(gdb) run

SIGPIPE is normal in Redis (clients close sockets); telling gdb to ignore it makes interactive debugging tolerable.

To attach to a running server:

gdb -p $(pidof redis-server)

A few common breakpoints:

• processCommand — every command goes through it.
• addReplyError — every error reply.
• freeClient — every disconnect.
• expireIfNeeded — every key access that touches expiration.
• serverCron — the periodic callback.

Asserts

serverAssert(cond) and serverAssertWithInfo(client, obj, cond) are the project's assertion macros. They live in src/server.h (declared) and src/debug.c (implementation). On failure they call _serverAssert* which logs the assertion, dumps the client/object that triggered it, and aborts. The assertion log includes the call stack like a crash.

serverPanic is the same path triggered manually.

Replication and cluster debugging

Command	Purpose
INFO replication	Master/replica state and offsets.
CLUSTER INFO	Cluster state, nodes, current epoch.
CLUSTER NODES	Per-node view including IP/port and slot ranges.
CLUSTER LINKS	TCP link state for cluster-bus connections (Redis 7+).
CLUSTER SHARDS	Master/replica grouping.
CLUSTER COUNT-FAILURE-REPORTS	How many nodes have flagged a peer.
DEBUG CLUSTERLINK	Force-close a cluster link to test reconnect.

For replication issues, repl-diskless-sync-delay, repl-backlog-size, client-output-buffer-limit replica, and repl-disable-tcp-nodelay are the usual suspects.

Sentinel debugging

SENTINEL CKQUORUM <master>, SENTINEL DEBUG, and SENTINEL FAILOVER <master> are the live levers. The implementation is in src/sentinel.c. The Sentinel log uses a slightly different format than the main server log; lines are prefixed with # Sentinel ....