~/blog/redis-7-2-internals/ko.mdx

Redis 7.2.16 내부: 쓰기 한 건에서 장애 조치까지

명령 실행과 자료구조에서 시작해 복제, Sentinel의 투표, Cluster 장애 조치와 슬롯 이동을 소스 함수까지 따라갑니다. 응답을 잃은 MIGRATE, 메모리 축출, Pub/Sub와 ACL도 같은 서버 안에서 연결합니다.

Redis에 SET을 보내고 OK를 받았습니다. 그러면 어디까지 끝난 것일까요? 지금 연결한 서버의 메모리에는 들어갔습니다. 레플리카가 받았는지, 디스크에 남았는지, 다음 장애 조치에서도 살아남는지는 별도로 확인해야 합니다.

이 글에서는 그 쓰기 한 건을 따라갑니다. 명령을 받아 실행하는 경로에서 시작해, 바이트 배열에 값을 넣고, 복제 연결로 보내고, 서버가 끊겼을 때 누가 다음 쓰기 담당자가 되는지 봅니다. 뒤에서는 슬롯을 옮기다가 응답을 잃는 경우까지 이어집니다.

분석 기준은 Redis 7.2.16의 커밋 335554f18caf7bbf6b0ac2b3548133d750f00a1b입니다. 릴리스의 공개 시각은 2026-08-17이고, 표시 날짜는 그다음 주인 2026-08-24로 잡았습니다. 소스 조사와 아래 재현은 2026-10-10에 수행한 검증입니다. 표시 날짜에 실험했다는 기록으로 읽으면 안 됩니다.

현재 redis.io의 설명에는 이후 버전의 기능이 섞일 수 있으므로 구현과 기본값은 이 커밋에 고정했습니다. 그림의 재생은 소스에서 읽은 순서를 편집한 스냅샷입니다. 실제 Redis를 브라우저에서 돌리거나 장애 시간을 예측하지 않습니다.

클라이언트의 SET 명령 검사와 실행 현재 primary의 메모리 비동기 복제 RDB / AOF Sentinel: 외부 감시자 투표 Cluster: 슬롯 담당 primary들의 투표 슬롯 이동: 데이터와 소유권

처음 읽는다면 §1에서 §8까지 순서대로 보시면 됩니다. 운영 중 문제를 찾는다면 복제는 §5, Sentinel은 §7, Cluster는 §9, 슬롯 이동은 §11부터 읽어도 됩니다. 캐시 사용 패턴은 캐시 안내서, listpack의 메모리 측정은 listpack 글, 순위 계산은 skip list 글에서 따로 다룹니다. 이 글의 기준 버전과 그 글들의 기준 버전은 다릅니다.

명령 하나가 실행되기까지

TCP 연결은 명령 자체가 아닙니다. 클라이언트가 보낸 RESP 바이트를 읽고, 명령 이름과 인자 배열로 파싱해야 합니다. networking.c의 readQueryFromClient, processInputBuffer를 따라가면 server.c의 processCommand에 도착합니다.1

processCommand에는 실제 쓰기보다 앞선 문이 여러 개 있습니다. 명령과 인자 수를 확인하고, 인증과 ACL을 검사합니다. Cluster라면 키가 이 노드의 슬롯인지 판단합니다. 메모리 압박과 디스크 오류, 부족한 레플리카, 읽기 전용 레플리카 상태도 여기서 명령을 거절할 수 있습니다. 통과하면 call이 c->cmd->proc(c)를 실행합니다.2

RESP 바이트 입력 버퍼와 argv 명령 / arity 검사 AUTH / ACL 슬롯 라우팅 메모리 / 디스크 / 역할 검사 call: 명령 함수 응답 버퍼 AOF / 복제 전파

읽기와 파싱을 마쳐도 명령이 실행된 것은 아닙니다. RESP가 온전한지와 명령의 인자 수가 맞는지를 구분합니다.

실행 전에 접근 권한, 슬롯 담당자, 쓰기를 받을 수 있는 상태를 확인합니다. MOVED나 NOPERM을 받았다면 자료구조를 수정하는 함수까지 가지 않았을 수 있습니다.

명령 함수가 메모리를 바꾸고 응답을 준비합니다. 전파와 영속화에는 별도 경로가 있으므로 OK를 레플리카와 디스크의 완료 표시로 바꾸어 읽지 않습니다.

MULTI는 명령을 모으고 EXEC에서 실행합니다. 실행 중 다른 일반 클라이언트의 명령이 끼어드는 것과, 앞 명령의 결과를 되돌리는 것은 다른 기능입니다. Redis 트랜잭션에는 SQL식 rollback이 없습니다. 실행 시점의 명령 오류를 무시한 채 “EXEC가 원자적이니 전부 성공했다”고 판단하면 안 됩니다.3

싱글 스레드가 설명하는 것과 설명하지 않는 것

이 버전의 일반 명령 실행은 메인 스레드가 담당합니다. 그래서 하나의 큰 명령이 오래 걸리면 같은 실행 경로를 기다리는 다른 요청에도 영향을 줍니다. 네트워크 왕복을 줄이는 pipelining은 큰 SMEMBERS나 긴 Lua 연산의 서버 실행 비용을 없애지 않습니다.

그렇다고 Redis 프로세스 전체에 스레드가 하나인 것은 아닙니다. io-threads의 기본값은 1이고 io-threads-do-reads는 no입니다. I/O 스레드를 쓰도록 설정하면 소켓 쓰기, 선택적으로 읽기와 파싱을 분담합니다. handleClientsWithPendingReadsUsingThreads는 작업 완료를 기다린 뒤 메인 스레드에서 processPendingCommandAndInputBuffer를 호출합니다. 명령 실행까지 서로 다른 I/O 스레드에 나누는 설정이 아닙니다.4

백그라운드 작업도 따로 있습니다. AOF fsync와 lazy free는 백그라운드 작업을 사용하고, RDB 저장이나 AOF rewrite는 자식 프로세스를 사용합니다. 운영에서 “싱글 스레드”라는 말만 외우면 CPU, 디스크, fork 비용을 같은 문제로 취급하게 됩니다.5

SLOWLOG와 INFO commandstats는 서버가 명령에 쓴 시간을 보는 도구입니다. 애플리케이션의 연결 풀 대기, 네트워크 왕복, 응답을 읽는 시간은 별도입니다. 이 글에서는 처리량이나 장애 복구 시간을 측정해 일반화하지 않습니다.

TYPE 아래에 여러 인코딩이 있습니다

TYPE은 공개 자료형을 말하고, OBJECT ENCODING은 현재 표현을 말합니다. redisObject는 type, encoding, 참조 수, LRU/LFU 정보와 실제 데이터 포인터를 갖습니다. 같은 hash라도 작은 것은 listpack, 커진 것은 hashtable일 수 있습니다.6

공개 자료형이 태그에서 읽어 볼 내부 표현읽을 함수
string정수 int, 객체와 SDS를 한 번에 할당하는 embstr, 별도 SDS의 rawcreateStringObject, tryObjectEncoding
hashfield/value 쌍을 나열한 listpack 또는 dicthashTypeSet, hashTypeConvert
set정수 배열 intset, listpack, dictsetTypeCreate, setTypeAddAux
sorted set작은 listpack 또는 dict와 skip listzsetAdd, zsetConvertAndExpand
list작은 listpack 또는 quicklistlistTypeTryConversionRaw
streamradix tree에 매단 listpack 묶음, 그룹별 pending 정보streamAppendItem

string의 embstr 경계는 이 소스의 OBJ_ENCODING_EMBSTR_SIZE_LIMIT = 44입니다. 이는 바이트 길이이며 모든 44바이트 이하 입력이 끝까지 embstr로 남는다는 뜻은 아닙니다. 정수로 표현 가능한 값은 정수 인코딩으로 바뀔 수 있고, 수정 경로에서도 인코딩이 바뀝니다. SDS는 문자열 길이를 별도 필드에 두므로 값 안의 NUL 바이트도 다룰 수 있습니다.6

dict의 확장은 전체 키를 한 번에 다시 넣는 호출 하나로만 구성되지 않습니다. dictRehash가 옛 테이블에서 새 테이블로 버킷을 조금씩 옮깁니다. 이 기간에는 두 테이블이 공존합니다. 점진적이라는 말도 작업 하나의 지연 상한을 보장하지는 않습니다. 버킷 하나에 연결된 엔트리를 옮기는 비용은 남습니다.7

sorted set의 dict는 멤버로 점수를 찾고, skip list는 점수 순서와 범위를 찾습니다. skip list의 span은 건너뛴 원소 수여서 rank를 계산할 수 있습니다. 점수가 같으면 멤버 문자열의 바이트 순서로 정렬합니다. ZRANK와 큰 ZRANGE를 같은 O(log N) 한 줄로 묶으면 반환할 원소 수의 비용을 놓칩니다.8

stream은 각 메시지를 독립된 dict 엔트리로만 저장하지 않습니다. streamAppendItem은 ID를 정렬 가능한 바이트로 바꿔 radix tree에서 listpack 묶음을 찾습니다. 묶음의 기준 ID와 필드명을 공유하고, 메시지의 ID 차이와 반복 필드를 압축합니다. consumer group의 PEL은 전달됐지만 아직 확인되지 않은 항목을 추적하는 별도 상태입니다. 소비자가 일을 완료했다고 XACK하는 것과 데이터가 디스크에 영속화되는 것은 다른 사건입니다.9

listpack을 읽을 때 놓치기 쉬운 경계

listpack.c의 형식은 총 바이트 수와 원소 수가 있는 6바이트 헤더, 원소들, 끝 표시 0xff입니다. 각 원소는 인코딩된 값 뒤에 자기 인코딩 길이의 backlen을 둡니다. backlen 자체의 크기를 그 길이에 포함하지 않습니다. 뒤로 걸을 때 자기 원소의 시작을 찾는 정보이지, 다음 원소에 저장된 앞 원소 길이가 아닙니다.10

헤더: 총 길이 / 원소 수 값 A / backlen A 값 B / backlen B 0xff

이 설계는 ziplist의 prevlen 연쇄 갱신을 없앱니다. 연속 배열의 중간에 넣을 때 뒤 바이트를 옮기는 비용까지 없애지는 않습니다. lpInsert에는 실제 memmove와 필요할 때의 재할당이 있고, 호출자는 반환된 새 포인터를 보관해야 합니다.10

기본 임계값은 이 태그의 redis.conf에 있습니다. entries는 공개 자료형의 원소 수입니다. hash의 field/value를 listpack 항목 두 개로 저장한다고 해서 필드 제한을 절반으로 읽지 않습니다.

설정기본값어떤 한계를 정합니까
hash-max-listpack-entries512필드 수
hash-max-listpack-value64필드명 또는 값의 바이트 길이
zset-max-listpack-entries128멤버 수
zset-max-listpack-value64멤버의 바이트 길이
set-max-intset-entries512정수로 표현되는 멤버 수
set-max-listpack-entries128listpack set의 멤버 수
set-max-listpack-value64멤버의 바이트 길이
list-max-listpack-size-2quicklist 노드 크기 기준, -2는 8 KiB 설정
list-compress-depth0끝에서 압축하지 않을 노드 깊이, 0은 압축 끔

hashTypeSet에서는 512개를 넘거나 필드명·값의 길이 조건을 벗어나면 hashtable로 전환합니다. 삭제 후 작아졌다고 그 hash가 자동으로 listpack으로 돌아오는 경로는 아닙니다. set은 첫 값과 한 번에 넣을 개수의 힌트도 초기 표현에 영향을 줍니다. 정수가 아닌 값을 넣는 순간 무조건 hashtable이라고 설명하면, 작은 intset을 listpack으로 바꾸는 경로를 놓칩니다.11

list에는 특히 버전 확인이 필요합니다. 이 태그의 작은 list는 독립된 listpack일 수 있습니다. listTypeTryConvertListpack은 커지면 quicklist로 바꾸고, listTypeTryConvertQuicklist은 packed 노드 하나로 줄었을 때 반대 전환도 검사합니다. 축소 시에는 기준의 절반을 사용해 경계에서 계속 표현을 바꾸는 일을 줄입니다. 다른 자료형의 한쪽 방향 전환을 모든 Redis 자료형의 규칙으로 일반화하지 않습니다.12

퀴즈인코딩을 확인하는 이유

답을 고르면 해설이 나옵니다.

1문제 중 0개 맞힘

  1. 작아진 Redis 자료구조는 모두 작은 인코딩으로 되돌아갑니까?

복제는 같은 바이트 역사에 다시 합류하는 일입니다

primary는 현재 쓰기를 받는 서버이고, replica는 그 서버의 복제 스트림을 따라가는 서버입니다. 복제는 기본적으로 비동기입니다. primary가 쓰기를 실행한 뒤 모든 replica의 확인을 기다려서 일반 SET의 OK를 내보내는 구조가 아닙니다.13

레플리카는 연결 후 PING, 필요하면 인증, REPLCONF 협상과 PSYNC를 진행합니다. 여기서 비교하는 것은 키 개수가 아니라 replication ID와 스트림의 byte offset입니다. offset이 큰 레플리카가 더 많은 스트림을 받았다는 뜻이지, 복제 스트림에 실린 모든 바이트가 사용자 데이터라는 뜻은 아닙니다.14

부분 재동기화(partial resynchronization)가 되려면 요청한 ID가 현재 역사 또는 허용된 이전 역사와 맞고, 요청한 offset부터의 바이트를 backlog가 보관하고 있어야 합니다. backlog는 레플리카가 잠시 끊긴 동안 따라잡을 수 있도록 남기는 복제 이력입니다. 데이터베이스의 변경 로그를 무한히 저장하는 장치는 아닙니다.

src/replication.c L755-L792
if (strcasecmp(master_replid, server.replid) &&
(strcasecmp(master_replid, server.replid2) ||
psync_offset > server.second_replid_offset))
{
/* Replid "?" is used by slaves that want to force a full resync. */
/* 로그 생략 */
goto need_full_resync;
}
/* We still have the data our slave is asking for? */
if (!server.repl_backlog ||
psync_offset < server.repl_backlog->offset ||
psync_offset > (server.repl_backlog->offset + server.repl_backlog->histlen))
{
/* 로그 생략 */
goto need_full_resync;
}

첫 번째 if는 replica가 보낸 replid가 현재 replid와 같은지 봅니다. 다르면 이전 replid(replid2)와 같고 요청 offset이 second_replid_offset 이하인 경우만 통과합니다. 두 번째 if는 요청 offset이 backlog에 남아 있는 구간 안에 있는지 보고, 어느 쪽이든 실패하면 need_full_resync로 가서 전체 동기화를 합니다.

조건을 못 맞추면 full resynchronization으로 갑니다. primary가 기준 offset과 RDB 스냅샷을 보내고, 스냅샷을 만드는 동안 생긴 이후 스트림도 보내 레플리카가 이어서 적용하게 합니다. 스냅샷 없이 현재 메모리를 조금씩 읽으며 임의 순서로 복사하는 방식이 아닙니다.15

설정기본값줄이거나 늘렸을 때의 의미
repl-backlog-size1 MiB끊김 동안 보관할 스트림의 목표 크기입니다. 쓰기량과 단절 시간을 함께 봅니다.
repl-backlog-ttl3600초연결된 레플리카가 없을 때 backlog를 언제 해제할지 정합니다. 키 TTL이 아닙니다.
repl-timeout60초복제 연결과 전송의 타임아웃입니다. Sentinel의 감지 시간과 별도입니다.
repl-ping-replica-period10초primary가 복제 연결에 PING을 보내는 주기입니다.
repl-diskless-syncyesfull sync의 RDB를 디스크 파일 대신 소켓으로 보내는 경로를 허용합니다.
repl-diskless-sync-delay5초full sync를 묶어 시작하려고 기다리는 시간입니다.
repl-diskless-loaddisabled수신하는 레플리카의 적재 방식입니다. 송신 설정과 같지 않습니다.
replica-read-onlyyes애플리케이션의 일반 쓰기를 레플리카에서 거절합니다.
replica-serve-stale-datayes복제 연결이 끊겨도 읽기를 허용할 수 있습니다. 최신성 보장이 아닙니다.

위 값은 설정 등록부와 태그의 설정 파일에서 확인했습니다.16 diskless도 디스크, CPU와 메모리 비용이 전부 없어졌다는 뜻은 아닙니다. RDB를 만들고 적재하는 일이 남습니다.

승격 후에는 새 replication ID를 사용합니다. 이전 ID와 유효 offset 경계를 replid2, second_replid_offset에 남겨 기존 레플리카가 이전 역사에서 부분 재동기화할 기회를 줍니다. 둘로 갈라진 쓰기 역사를 ID 하나로 합치는 기능은 아닙니다.17

OK와 레플리카 반영 사이

클라이언트대기
primaryA
replicaA

시작

두 서버가 A를 갖고 있습니다.

A와 B는 설명용 값입니다. 스냅샷은 비동기 복제의 가능한 순서이며, 전송 지연을 측정하지 않습니다.
전체 상태 보기 (JavaScript 없이도 읽을 수 있습니다)

반영 후 장애

  1. 시작

    클라이언트: 대기 · primary: A · replica: A

    두 서버가 A를 갖고 있습니다.

  2. SET B 실행

    클라이언트: OK · primary: B · replica: A

    현재 primary가 B를 쓰고 OK를 응답합니다.

  3. 복제 적용

    클라이언트: OK · primary: B · replica: B

    replica가 B의 스트림을 적용합니다.

  4. primary 장애

    클라이언트: 재연결 필요 · primary: 중단 · replica: B

    B를 받은 replica가 선택되는 경우 B가 남습니다. 선택과 영속화 조건은 별도입니다.

반영 전 장애

  1. 시작

    클라이언트: 대기 · primary: A · replica: A

    두 서버가 A를 갖고 있습니다.

  2. SET B 실행

    클라이언트: OK · primary: B · replica: A

    OK를 받았어도 replica는 아직 A일 수 있습니다.

  3. primary 장애

    클라이언트: 재연결 필요 · primary: 중단 · replica: A

    B를 못 받은 replica만 승격 후보로 남는 순서입니다.

  4. replica 승격

    클라이언트: A를 읽음 · primary: 중단 · replica: A / primary

    새 primary에 B가 없습니다. 원래 OK를 받았다는 사실로 복원되지 않습니다.

WAIT와 WAITAOF를 붙이면 무엇이 달라집니까

WAIT numreplicas timeout은 같은 클라이언트 연결의 앞선 쓰기 offset을 일정 수의 replica가 확인했는지 기다리고, 실제 확인 수를 돌려줍니다. 결과가 요구한 수보다 작아도 앞선 쓰기를 rollback하지 않습니다. 애플리케이션은 성공 기준에 못 미친 결과를 별도로 처리해야 합니다.18

WAITAOF numlocal numreplicas timeout은 같은 연결의 앞선 쓰기에 대한 AOF fsync 확인을 기다립니다. local과 replica 확인 수를 따로 돌려줍니다. AOF가 꺼진 로컬 서버에 로컬 fsync를 요구할 수는 없습니다. 이 역시 반환값을 검사해야 합니다.18

둘 다 연결을 바꾸고 호출하면 원래 연결의 쓰기를 기다리는 용도로 쓸 수 없습니다. redis-cli SET ...와 별도의 redis-cli WAIT ...를 두 번 실행하는 예제는 그 점을 숨깁니다. 연결 풀이 어느 연결을 빌려 주는지도 중요합니다.

WAIT가 성공해도 Sentinel/Cluster 선거가 그 쓰기에 투표한 레플리카만 반드시 고르는 것은 아닙니다. 디스크에 남기는 요구와 다음 primary 선택 규칙까지 설계하지 않고 “강한 일관성이 됐다”고 말하지 않습니다. 응답 타임아웃 뒤에 같은 증가 명령을 다시 보내는 문제도 남습니다. 첫 시도가 적용됐을 수 있으므로 재시도에는 idempotency를 별도로 설계해야 합니다.

단독 서버와 수동 FAILOVER

복제도 없는 서버 하나가 멈추면 대체 primary 후보가 없습니다. RDB/AOF를 적재해 재시작하는 것은 장애 조치 선거와 다릅니다.

Sentinel이나 Cluster 없이 primary와 replica만 연결했다면, 복제 링크가 끊겼다는 이유로 replica가 자동으로 쓰기 담당자가 되지는 않습니다. 사람이 REPLICAOF NO ONE으로 승격하고 다른 노드와 클라이언트를 재설정할 수 있지만, 이 명령에는 감시자 과반수 투표나 옛 primary fencing이 없습니다.19

실행 중인 standalone primary에서 시작하는 FAILOVER 명령도 있습니다. coordinated failover는 쓰기를 멈추고 대상 replica가 offset을 따라잡게 한 뒤 역할을 넘기는 경로입니다. 죽은 primary에 명령을 보내는 자동 장애 복구 기능은 아닙니다. TO, TIMEOUT, FORCE, ABORT의 의미를 Sentinel이나 CLUSTER FAILOVER 옵션과 섞지 않습니다.19

standalone의 FAILOVER ... FORCE는 정한 timeout 안에 따라잡지 못해도 지정한 대상으로 역할을 넘길 수 있어 유실 위험이 있습니다. REPLICAOF NO ONE은 즉시 역할을 바꾸는 다른 명령입니다. 역할이 바뀌었다고 애플리케이션의 주소, DNS와 연결 풀이 자동으로 바뀌지는 않습니다.

Sentinel의 SDOWN, ODOWN과 선거는 서로 다른 문입니다

Sentinel은 데이터 키를 나누는 서버가 아니라 외부 감시자입니다. 하나의 primary와 그 replicas를 감시하고, 다른 Sentinels를 알아내고, 필요할 때 승격을 조정합니다. 여기서 primary 주소는 서비스 이름으로 조회할 수 있어야 클라이언트가 새 연결을 만들 수 있습니다.

SDOWN은 내 관측입니다

sentinelCheckSubjectivelyDown은 Sentinel 하나의 관측으로 SDOWN(subjectively down)을 설정합니다. down-after-milliseconds 동안 유효한 응답을 못 받았는지 등을 봅니다. PING의 정상 응답에는 PONG뿐 아니라 서버가 살아 있음을 나타내는 LOADING, MASTERDOWN도 포함됩니다. TCP 연결 여부 하나만으로 판정하지 않습니다.20

src/sentinel.c L4576-L4602
/* Update the SDOWN flag. We believe the instance is SDOWN if:
*
* 1) It is not replying.
* 2) We believe it is a master, it reports to be a slave for enough time
* to meet the down_after_period, plus enough time to get two times
* INFO report from the instance. */
if (elapsed > ri->down_after_period ||
(ri->flags & SRI_MASTER &&
ri->role_reported == SRI_SLAVE &&
mstime() - ri->role_reported_time >
(ri->down_after_period+sentinel_info_period*2)) ||
(ri->flags & SRI_MASTER_REBOOT &&
mstime()-ri->master_reboot_since_time > ri->master_reboot_down_after_period))
{
/* Is subjectively down */
if ((ri->flags & SRI_S_DOWN) == 0) {
sentinelEvent(LL_WARNING,"+sdown",ri,"%@");
ri->s_down_since_time = mstime();
ri->flags |= SRI_S_DOWN;
}
} else {
/* Is subjectively up */
if (ri->flags & SRI_S_DOWN) {
sentinelEvent(LL_WARNING,"-sdown",ri,"%@");
ri->flags &= ~(SRI_S_DOWN|SRI_SCRIPT_KILL_SENT);
}
}

조건은 세 가지입니다. 마지막 정상 응답 이후 elapsed가 down_after_period를 넘었거나, primary가 자기를 replica라고 보고한 상태가 down_after_period+sentinel_info_period*2보다 오래 갔거나, 재시작한 primary가 master_reboot_down_after_period 안에 회복하지 못한 경우입니다. 이때 +sdown 이벤트를 내고 SRI_S_DOWN 플래그를 켭니다.

이 판정은 주로 “내가 이 서버를 정상적으로 사용할 수 없다고 봅니다”입니다. 내가 고립됐거나 내 경로만 끊겼을 수도 있습니다. primary뿐 아니라 replica나 다른 Sentinel에도 SDOWN 플래그가 붙을 수 있습니다.

ODOWN은 감지 quorum을 채운 관측입니다

primary가 SDOWN이면 SENTINEL is-master-down-by-addr로 다른 감시자의 관측을 묻습니다. sentinelCheckObjectivelyDown은 자기 자신과 다른 감시자들의 down 보고를 세어 설정된 quorum에 도달하면 ODOWN(objectively down)을 설정합니다. 모든 감시자가 동의했다는 뜻도, 데이터에 합의했다는 뜻도 아닙니다.21

src/sentinel.c L4605-L4628
/* Is this instance down according to the configured quorum?
*
* Note that ODOWN is a weak quorum, it only means that enough Sentinels
* reported in a given time range that the instance was not reachable.
* However messages can be delayed so there are no strong guarantees about
* N instances agreeing at the same time about the down state. */
void sentinelCheckObjectivelyDown(sentinelRedisInstance *master) {
dictIterator *di;
dictEntry *de;
unsigned int quorum = 0, odown = 0;
if (master->flags & SRI_S_DOWN) {
/* Is down for enough sentinels? */
quorum = 1; /* the current sentinel. */
/* Count all the other sentinels. */
di = dictGetIterator(master->sentinels);
while((de = dictNext(di)) != NULL) {
sentinelRedisInstance *ri = dictGetVal(de);
if (ri->flags & SRI_MASTER_DOWN) quorum++;
}
dictReleaseIterator(di);
if (quorum >= master->quorum) odown = 1;
}

quorum = 1은 자기 자신의 한 표이고, 다른 Sentinel 중 SRI_MASTER_DOWN 플래그가 켜진 수만큼 더합니다. 합이 설정한 quorum 이상이면 ODOWN입니다. 주석이 스스로 “weak quorum”이라고 부르는 이유는, 이 표들이 같은 순간에 모인 합의가 아니라 최근에 받은 응답의 집계이기 때문입니다.

승격 허가는 알려진 감시자들의 과반수도 필요합니다

ODOWN을 본 Sentinel이 혼자 아무 replica나 승격하면 두 곳에서 동시에 역할을 바꿀 수 있습니다. 그래서 선거 epoch마다 leader를 정합니다. sentinelVoteLeader는 epoch에 대해 투표하고, sentinelGetLeader는 알려진 Sentinels의 절대 과반수와 설정 quorum을 모두 채운 leader인지 검사합니다.22

src/sentinel.c L4843-L4862
/* Count this Sentinel vote:
* if this Sentinel did not voted yet, either vote for the most
* common voted sentinel, or for itself if no vote exists at all. */
if (winner)
myvote = sentinelVoteLeader(master,epoch,winner,&leader_epoch);
else
myvote = sentinelVoteLeader(master,epoch,sentinel.myid,&leader_epoch);
if (myvote && leader_epoch == epoch) {
uint64_t votes = sentinelLeaderIncr(counters,myvote);
if (votes > max_votes) {
max_votes = votes;
winner = myvote;
}
}
voters_quorum = voters/2+1;
if (winner && (max_votes < voters_quorum || max_votes < master->quorum))
winner = NULL;

voters_quorum = voters/2+1이 과반입니다. 가장 많은 표를 받은 후보라도 max_votes가 과반에 못 미치거나 설정한 quorum에 못 미치면 winner를 NULL로 돌려 이번 epoch에서는 리더가 없습니다. 그래서 Sentinel 5대에 quorum 2를 줘도 failover를 시작하려면 3표가 필요합니다.

즉 quorum은 장애 감지 기준이고, 선거에는 과반수 조건이 추가됩니다. 아래 수는 실제 배치 측정이 아닌 quorum 계산 예제입니다. 감시자 수에는 자신도 포함하며, 같은 primary에 대해 알고 있는 Sentinels를 셉니다.

ODOWN인데 왜 승격하지 못합니까

알려진 Sentinel3
down 보고1
leader 득표0
판정SDOWN

내 관측

S1만 down으로 봅니다. quorum에 못 미칩니다.

quorum=2로 고정한 설명용 선거입니다. 감지 quorum과 leader 선출 조건을 분리하며, 실제 타임아웃과 메시지 재전송은 생략합니다.
전체 상태 보기 (JavaScript 없이도 읽을 수 있습니다)

감시자 3개

  1. 내 관측

    알려진 Sentinel: 3 · down 보고: 1 · leader 득표: 0 · 판정: SDOWN

    S1만 down으로 봅니다. quorum에 못 미칩니다.

  2. S2도 down 보고

    알려진 Sentinel: 3 · down 보고: 2 · leader 득표: 0 · 판정: ODOWN

    자신을 포함한 보고 2개로 ODOWN입니다. 이 보고 자체가 leader 투표는 아닙니다.

  3. 같은 epoch의 leader 투표

    알려진 Sentinel: 3 · down 보고: 2 · leader 득표: 2 · 판정: 선출 가능

    leader가 2표를 모으면 3개의 절대 과반수와 quorum=2를 함께 채웁니다.

감시자 5개

  1. 내 관측

    알려진 Sentinel: 5 · down 보고: 1 · leader 득표: 0 · 판정: SDOWN

    S1만 down으로 봅니다.

  2. S2도 down 보고

    알려진 Sentinel: 5 · down 보고: 2 · leader 득표: 0 · 판정: ODOWN

    quorum=2이므로 ODOWN이 될 수 있습니다.

  3. 2표만 확보

    알려진 Sentinel: 5 · down 보고: 2 · leader 득표: 2 · 판정: 승격 허가 없음

    알려진 5개 중 절대 과반수는 3개입니다. 2표로는 leader를 선출하지 못합니다.

  4. 같은 leader에 3표

    알려진 Sentinel: 5 · down 보고: 2 · leader 득표: 3 · 판정: 선출 가능

    같은 epoch에서 과반수와 quorum을 채워야 선출됩니다.

퀴즈quorum만 낮추면 복구됩니까

답을 고르면 해설이 나옵니다.

1문제 중 0개 맞힘

  1. Sentinel 5개를 알고 있고 quorum=2입니다. 네트워크가 갈라져 2개만 서로 통신합니다. ODOWN이면 자동 승격을 허가받습니까?

leader가 정해진 뒤에도 할 일이 남습니다

sentinelFailoverStateMachine의 상태 순서를 읽으면 승격은 한 명령의 반환값으로 끝나지 않습니다.23

상태코드가 기다리는 일
WAIT_STARTleader 선출과 시작 조건
SELECT_SLAVE승격할 replica 후보 선택
SEND_SLAVEOF_NOONE대상에게 REPLICAOF NO ONE에 해당하는 역할 변경 명령 전송
WAIT_PROMOTION대상의 INFO에서 primary 역할을 확인
RECONF_SLAVES다른 replicas를 새 primary에 연결
UPDATE_CONFIG감시 대상 주소와 구성을 새 primary 기준으로 갱신

후보 선택에도 두 단계가 있습니다. 먼저 SDOWN/ODOWN, 오래 끊긴 연결, INFO의 신선도, primary와 끊긴 기간, replica-priority=0 등을 검사해 후보를 거릅니다. 그다음 남은 후보를 작은 priority, 큰 replication offset, run ID 순서로 정렬합니다. 가장 최신 offset을 무조건 첫 기준으로 쓰는 것이 아닙니다.24

leader 선출 뒤 실제 역할이 바뀌는 순서

Sentinel leader선출됨
후보 R1replica
다른 replicas옛 primary 추종

WAIT_START

같은 epoch의 leader로 선출되고 시작 조건을 만족합니다.

성공 경로를 편집한 상태 재생입니다. 후보는 사전에 적격성 검사를 통과했다고 가정하며, 타임아웃·재선거·재구성 재시도는 본문에서 설명합니다.
전체 상태 보기 (JavaScript 없이도 읽을 수 있습니다)

승격과 재구성

  1. WAIT_START

    Sentinel leader: 선출됨 · 후보 R1: replica · 다른 replicas: 옛 primary 추종

    같은 epoch의 leader로 선출되고 시작 조건을 만족합니다.

  2. SELECT_SLAVE

    Sentinel leader: R1 선택 · 후보 R1: 선택됨 · 다른 replicas: 옛 primary 추종

    적격 후보 중 priority, offset, run ID 순으로 R1을 고릅니다.

  3. SEND_SLAVEOF_NOONE

    Sentinel leader: 명령 전송 · 후보 R1: 승격 요청 · 다른 replicas: 옛 primary 추종

    R1에 역할 변경 명령을 보냅니다. 아직 INFO 확인 전입니다.

  4. WAIT_PROMOTION

    Sentinel leader: INFO 확인 · 후보 R1: primary · 다른 replicas: 옛 primary 추종

    R1의 INFO에서 primary 역할을 확인합니다.

  5. RECONF_SLAVES

    Sentinel leader: 재구성 · 후보 R1: primary · 다른 replicas: R1으로 동기화

    parallel-syncs 제한 안에서 다른 replicas를 R1에 연결합니다.

  6. UPDATE_CONFIG

    Sentinel leader: 주소 갱신 · 후보 R1: primary · 다른 replicas: R1 추종

    서비스 이름의 primary 주소를 갱신합니다. 애플리케이션은 이를 조회해 재연결해야 합니다.

WAIT_PROMOTION에서 역할 확인을 못 하면 시간 제한과 실패 경로가 작동합니다. parallel-syncs는 leader 득표 수가 아니라 동시에 새 primary로 재구성할 replica 수입니다. “선거가 끝났습니다”와 “모든 replica가 다시 붙었습니다”를 같은 시각으로 보지 않습니다.

Sentinel 설정과 네트워크 분할

설정 파일의 감시 시작점은 sentinel monitor <name> <ip> <port> <quorum>입니다. quorum에는 하나의 보편적인 기본 배치값을 대신 넣지 않습니다. 주소는 Sentinel이 관측하고 재구성할 수 있어야 합니다. NAT나 컨테이너 환경에서 서로 도달하지 못하는 주소를 광고하면 감시와 클라이언트 재연결이 다른 곳을 보게 됩니다.

설정코드 기본값운영에서 묻는 질문
down-after-milliseconds30000 ms정상 서버의 일시적인 지연을 장애로 볼 가능성과 감지 지연을 어떻게 맞춥니까
failover-timeout180000 ms선거·승격·재구성·다음 시도의 시간 제한을 어떻게 운용합니까
parallel-syncs1동시에 재동기화되는 replicas 때문에 읽기 용량이 얼마나 줄 수 있습니까
replica-priority100어떤 replica를 우선 승격합니까. 0은 자동 승격 후보에서 제외합니다.
min-replicas-to-write0일정 수의 정상 replica 없이 primary가 쓰기를 받을 수 있습니까
min-replicas-max-lag10초정상 replica를 셀 때 마지막 ACK의 지연을 얼마나 허용합니까

Sentinel 상수와 Redis 설정 등록부의 값입니다.25 failover-timeout을 “전체 복구가 반드시 이 시간 안에 끝납니다”로 읽지 않습니다. 반복 시도와 단계별 조건을 제어하는 값입니다.

네트워크 분할에서는 새 primary가 생겨도 옛 primary가 즉시 죽지 않을 수 있습니다. Sentinel은 옛 primary의 CPU를 멈추거나 기존 애플리케이션 연결을 강제로 차단하는 fencing 장치가 아닙니다. 옛 주소에 붙은 클라이언트가 계속 쓰면, 재결합 후 그 서버가 새 primary의 replica로 재구성되면서 분기한 쓰기가 사라질 수 있습니다.26

min-replicas-to-write와 min-replicas-max-lag는 이 창을 줄이는 도구입니다. primary는 최근 ACK 기준으로 정상 replica 수를 검사해 NOREPLICAS로 쓰기를 거절할 수 있습니다. 각 쓰기마다 동기 복제 합의를 얻는 기능은 아니므로, 설정했다고 유실 창이 사라졌다고 말하지 않습니다.27

Sentinel에는 TILT도 있습니다. 시간 변화나 긴 실행 정지로 타이머 관측이 이상해졌을 때 감지는 계속하되 위험한 조치를 억제하는 모드입니다. 이 태그의 sentinel_tilt_trigger 기본값은 2000 ms이고 sentinel_tilt_period는 SENTINEL_PING_PERIOD * 30, 즉 30000 ms입니다. 감지 시간을 짧게 잡는 것만으로 호스트 정지와 타이머 문제를 해결할 수는 없습니다.28

영속화를 끈 primary를 빈 데이터로 자동 재시작하는 경우도 주의해야 합니다. 여전히 primary로 돌아오면 replicas가 그 빈 상태를 다시 따라갈 수 있습니다. replica를 백업으로 생각하면서 원본 서버의 재시작 정책을 따로 두지 않습니다. 복제는 삭제와 빈 상태도 따라갈 수 있습니다.

Cluster의 장애 판정과 투표

Cluster는 keyspace를 나눕니다. 이 소스의 CLUSTER_SLOTS는 16384이고, keyHashSlot은 CRC16 결과를 그 범위로 줄입니다. 비어 있지 않은 첫 hash tag를 사용하면 {user:42}:profile과 {user:42}:session은 같은 슬롯에 갑니다. 슬롯은 키 하나가 아니라 키를 배정하는 칸이고, 그 칸의 primary가 현재 쓰기를 담당합니다.29

각 데이터 노드는 별도의 cluster bus로 서로 상태를 교환합니다. Sentinel 프로세스가 이 선거를 대신하지 않습니다. bus의 기본 포트 관계는 데이터 포트에 10000을 더한 값이며 cluster-port로 지정할 수도 있습니다. 클라이언트가 데이터 포트에 연결된다고 노드 간 bus 연결까지 정상인 것은 아닙니다.30

PFAIL은 한 노드가 다른 노드를 제때 못 만난다는 로컬 의심입니다. FAIL은 슬롯을 담당하는 voting primary들의 장애 보고를 모아 과반수 조건을 만족시키는 판정입니다. primary들의 보고와 로컬 노드가 primary일 때의 자기 관측을 함께 셉니다. replica 수를 늘려도 투표권 있는 primary 수를 대신 늘리지 않습니다.31

장애 primary의 replica는 clusterHandleSlaveFailover 경로에서 승격을 시도합니다. 적격성 검사 후, replication offset에 따른 replica rank와 무작위 지연으로 시도를 벌리고, 새 epoch에서 투표 요청을 보냅니다. offset rank는 더 뒤처진 replica가 늦게 시도하게 만드는 장치입니다. 모든 노드가 후보 데이터를 비교해 최신 값을 복원하는 절차가 아닙니다.32

src/cluster.c L4344-L4363
/* If the previous failover attempt timeout and the retry time has
* elapsed, we can setup a new one. */
if (auth_age > auth_retry_time) {
server.cluster->failover_auth_time = mstime() +
500 + /* Fixed delay of 500 milliseconds, let FAIL msg propagate. */
random() % 500; /* Random delay between 0 and 500 milliseconds. */
server.cluster->failover_auth_count = 0;
server.cluster->failover_auth_sent = 0;
server.cluster->failover_auth_rank = clusterGetSlaveRank();
/* We add another delay that is proportional to the slave rank.
* Specifically 1 second * rank. This way slaves that have a probably
* less updated replication offset, are penalized. */
server.cluster->failover_auth_time +=
server.cluster->failover_auth_rank * 1000;
/* However if this is a manual failover, no delay is needed. */
if (server.cluster->mf_end) {
server.cluster->failover_auth_time = mstime();
server.cluster->failover_auth_rank = 0;
clusterDoBeforeSleep(CLUSTER_TODO_HANDLE_FAILOVER);
}

선거 시작 시각은 지금부터 500ms에 0~499ms의 난수를 더하고, rank 1마다 1초를 더 늦춥니다. rank는 clusterGetSlaveRank(L4142-L4157)가 셉니다. failover가 가능한 형제 replica 중 자기보다 repl_offset이 큰 수이므로, 데이터를 가장 많이 받은 replica가 먼저 표를 요청합니다. 수동 failover(mf_end)면 지연이 0입니다.

voting primary는 clusterSendFailoverAuthIfNeeded에서 자신의 역할, 이미 투표한 epoch, 대상 primary의 FAIL 상태와 슬롯의 config epoch 등을 검사합니다. 후보가 voting primary의 과반수 ACK를 모으면 승격하고 슬롯을 인계합니다. currentEpoch는 선거의 진행 번호이고, configEpoch는 슬롯 소유권 정보의 우선순위를 정할 때 쓰입니다. 키 값의 버전 번호가 아닙니다.32

src/cluster.c L4039-L4083
if (nodeIsSlave(myself) || myself->numslots == 0) return;
/* Request epoch must be >= our currentEpoch.
* Note that it is impossible for it to actually be greater since
* our currentEpoch was updated as a side effect of receiving this
* request, if the request epoch was greater. */
if (requestCurrentEpoch < server.cluster->currentEpoch) {
/* 로그 생략 */
return;
}
/* I already voted for this epoch? Return ASAP. */
if (server.cluster->lastVoteEpoch == server.cluster->currentEpoch) {
/* 로그 생략 */
return;
}
/* Node must be a slave and its master down.
* The master can be non failing if the request is flagged
* with CLUSTERMSG_FLAG0_FORCEACK (manual failover). */
if (nodeIsMaster(node) || master == NULL ||
(!nodeFailed(master) && !force_ack))
{
/* 로그 생략 */
return;
}

앞쪽 검사들입니다. 투표하는 노드가 slot을 가진 primary여야 하고, 요청의 epoch가 내 currentEpoch보다 작으면 거절합니다. 같은 epoch에 이미 투표했으면(lastVoteEpoch == currentEpoch) 두 번 찍지 않고, 요청한 replica의 primary가 FAIL로 보이지 않으면(수동 failover의 force_ack 제외) 거절합니다.

src/cluster.c L4085-L4125
/* We did not voted for a slave about this master for two
* times the node timeout. This is not strictly needed for correctness
* of the algorithm but makes the base case more linear. */
if (mstime() - node->slaveof->voted_time < server.cluster_node_timeout * 2)
{
/* 로그 생략 */
return;
}
/* The slave requesting the vote must have a configEpoch for the claimed
* slots that is >= the one of the masters currently serving the same
* slots in the current configuration. */
for (j = 0; j < CLUSTER_SLOTS; j++) {
if (bitmapTestBit(claimed_slots, j) == 0) continue;
if (isSlotUnclaimed(j) ||
server.cluster->slots[j]->configEpoch <= requestConfigEpoch)
{
continue;
}
/* If we reached this point we found a slot that in our current slots
* is served by a master with a greater configEpoch than the one claimed
* by the slave requesting our vote. Refuse to vote for this slave. */
/* 로그 생략 */
return;
}
/* We can vote for this slave. */
server.cluster->lastVoteEpoch = server.cluster->currentEpoch;
node->slaveof->voted_time = mstime();
clusterDoBeforeSleep(CLUSTER_TODO_SAVE_CONFIG|CLUSTER_TODO_FSYNC_CONFIG);
clusterSendFailoverAuth(node);

같은 primary의 replica에게는 node_timeout*2 안에 다시 투표하지 않습니다. 요청이 주장하는 slot 중 하나라도 내가 아는 소유자의 configEpoch가 요청의 configEpoch보다 크면 거절합니다. 모두 통과하면 lastVoteEpoch를 기록하고 설정 저장과 fsync를 beforeSleep에 예약한 다음 clusterSendFailoverAuth를 부릅니다. 이 함수는 메시지를 링크 큐에 넣기만 하고 실제 전송은 write handler가 하는데(L3530-L3535), 그 handler는 beforeSleep의 clusterBeforeSleep(server.c L1663)이 설정 파일을 fsync한 뒤에 돕니다. 그래서 표가 네트워크로 나가기 전에 lastVoteEpoch가 디스크에 있고, 재시작한 노드가 같은 epoch에 두 번 투표하지 않습니다.

로컬 관측: PFAIL primary들의 장애 보고 보고 과반수: FAIL replica: 적격성 / rank / 새 epoch voting primary들의 선거 ACK 승격과 슬롯 인계 새 configEpoch 광고

cluster-node-timeout이 15000 ms라고 해서 정확히 그 시간에 감지, 투표, 승격과 클라이언트 재연결까지 끝나지는 않습니다. 메시지 전송, 선거 지연, 재시도, 연결 상태가 추가로 관여합니다. 이 값은 해당 태그의 장애 판단 기준이며 복구 시간 SLA가 아닙니다.33

Cluster의 수동 승격과 가용성 설정

CLUSTER FAILOVER는 replica에서 시작합니다. 정상적인 수동 경로에서는 기존 primary와 조정해 쓰기를 일시 중지하고 offset을 따라잡은 뒤 선거를 진행합니다. primary에 보내는 standalone FAILOVER와 출발 노드부터 다릅니다.34

CLUSTER FAILOVER FORCE는 기존 primary와의 조정을 건너뛰지만 voting primary들의 선거 허가는 여전히 필요합니다. TAKEOVER는 정상 선거도 건너뛰고 로컬에서 승격과 소유권 변경을 진행합니다. 후자는 복구 작업자가 분할 상황과 권한을 통제하는 경우의 위험한 도구입니다. 단순히 “더 빨리”라는 이유로 선택하지 않습니다.

설정기본값실제로 바꾸는 것
cluster-enabledno서버가 Cluster 프로토콜을 실행할지 정합니다.
cluster-node-timeout15000 ms노드 연결, 장애 판단과 선거 관련 시간 기준입니다.
cluster-replica-validity-factor10오래 primary와 단절된 replica의 자동 승격 적격성을 제한합니다.
cluster-require-full-coverageyes미할당 슬롯 또는 FAIL 상태 담당자가 있으면 전체 keyspace 서비스를 실패 상태로 둘 수 있습니다.
cluster-allow-reads-when-downnoCluster down 상태에서 허용할 읽기의 범위를 바꿉니다. 쓰기 합의나 최신성을 만들지 않습니다.
cluster-replica-no-failoverno해당 replica의 자동 failover 참여를 억제합니다.
cluster-migration-barrier1replica가 없는 primary 쪽으로 replica가 옮겨 갈 때 기존 primary에 남겨 둘 정상 replica 수입니다.
cluster-allow-replica-migrationyesreplica 재배치를 허용합니다. 클라이언트 키의 슬롯 이동과 다른 기능입니다.

기본값은 config.c에 등록된 값입니다.33 replica validity는 단순히 factor와 timeout의 곱 하나만 보는 것으로 끝나지 않습니다. 이 코드의 적격성 기준에는 replication PING 주기도 더해집니다. factor 0은 오래 끊긴 replica를 그 기준으로 제외하지 않도록 하는 선택이며, 최신 데이터 보장이 아닙니다.

cluster-require-full-coverage no는 슬롯 일부를 사용할 수 없을 때 나머지 슬롯을 서비스할 수 있게 하는 선택입니다. voting primary의 과반수를 잃은 쪽에서도 계속 쓰게 만드는 스위치가 아닙니다. clusterUpdateState의 majority reachability 검사는 별도로 남습니다.35

READONLY를 사용한 replica 읽기도 따로 이해해야 합니다. 자기 primary가 담당하는 슬롯에 대해 replica에서 읽도록 허용하는 연결 상태입니다. 복제가 비동기이므로 read-after-write를 자동으로 만족시키지 않습니다. 새 primary 선택, 읽기 경로, 애플리케이션 재시도는 각각 다른 설계입니다.

슬롯 이동은 소유권과 데이터를 따로 바꿉니다

슬롯을 A에서 B로 옮긴다는 말을 “A의 슬롯 번호만 B로 바꿉니다”로 줄이면 이동 중 라우팅을 설명할 수 없습니다. 먼저 B를 IMPORTING A, A를 MIGRATING B로 둡니다. 아직 공식 슬롯 담당자는 A입니다. 데이터를 옮긴 뒤 마지막에 SETSLOT ... NODE B로 소유권을 확정합니다.36

이 상태에서 A는 기존 키를 계속 처리합니다. 없는 키를 요청하면 “지금 이 한 명령은 B로 가 보십시오”라는 ASK를 보낼 수 있습니다. B에서는 같은 연결로 ASKING을 보내고 해당 명령을 실행해야 합니다. ASK는 슬롯 맵을 영구 갱신하라는 의미가 아닙니다.

반대로 MOVED는 현재 슬롯 담당자 정보를 알려 줍니다. 클라이언트는 그 주소로 재시도하고 슬롯 맵도 갱신할 수 있습니다. redis-cli -c가 평소에는 편리하지만, 아래 실험처럼 ASK와 MOVED 자체를 관찰할 때는 자동 재전송이 응답을 숨길 수 있습니다.

이동 중 요청소스의 분기
A에서 기존 키 조회A가 처리합니다.
A에서 없는 키 조회B를 가리키는 ASK가 나올 수 있습니다.
B에서 ASKING 없이 조회현재 owner A를 가리키는 MOVED가 나올 수 있습니다.
B에서 ASKING 후 조회해당 importing 슬롯의 명령을 B가 받아들입니다.
같은 슬롯의 여러 키 중 일부만 A에 존재한 명령을 나눠 실행할 수 없어 TRYAGAIN이 나올 수 있습니다.
서로 다른 슬롯의 일반 multi-key 명령CROSSSLOT입니다. 이동 상태만으로 하나의 트랜잭션이 되지 않습니다.

같은 hash tag를 썼다고 이동 중 multi-key 명령이 무조건 성공하는 것도 아닙니다. 슬롯은 같아도 키가 양쪽에 나뉜 순간이 있습니다. getNodeByQuery는 missing key 수를 세어 그런 명령을 거절합니다. TRYAGAIN 재시도에도 제한과 backoff가 필요합니다.36

src/cluster.c L7508-L7540
/* MIGRATE always works in the context of the local node if the slot
* is open (migrating or importing state). We need to be able to freely
* move keys among instances in this case. */
if ((migrating_slot || importing_slot) && cmd->proc == migrateCommand)
return myself;
/* If we don't have all the keys and we are migrating the slot, send
* an ASK redirection or TRYAGAIN. */
if (migrating_slot && missing_keys) {
/* If we have keys but we don't have all keys, we return TRYAGAIN */
if (existing_keys) {
if (error_code) *error_code = CLUSTER_REDIR_UNSTABLE;
return NULL;
} else {
if (error_code) *error_code = CLUSTER_REDIR_ASK;
return server.cluster->migrating_slots_to[slot];
}
}
/* If we are receiving the slot, and the client correctly flagged the
* request as "ASKING", we can serve the request. However if the request
* involves multiple keys and we don't have them all, the only option is
* to send a TRYAGAIN error. */
if (importing_slot &&
(c->flags & CLIENT_ASKING || cmd_flags & CMD_ASKING))
{
if (multiple_keys && missing_keys) {
if (error_code) *error_code = CLUSTER_REDIR_UNSTABLE;
return NULL;
} else {
return myself;
}
}

MIGRATE 자체는 slot이 열려 있으면 로컬에서 실행합니다. migrating 쪽에서 키가 일부만 남아 있으면 CLUSTER_REDIR_UNSTABLE(클라이언트가 보는 -TRYAGAIN)이고, 하나도 없으면 -ASK로 migrating_slots_to[slot]을 알려줍니다. importing 쪽은 ASKING이 붙은 요청만 받고, 다중 키 요청에서 키가 빠져 있으면 역시 TRYAGAIN입니다.

MIGRATE가 하는 일

migrateCommand는 대상과 연결하고 필요한 AUTH/SELECT를 준비합니다. 키의 값을 RDB 직렬화 형식으로 만들고, 남은 TTL과 함께 RESTORE를 보냅니다. Cluster에서는 importing 대상에 넣기 위해 RESTORE-ASKING 경로를 씁니다. 대상이 성공 응답을 보낸 뒤에 원본을 삭제합니다. COPY면 원본을 남기고, REPLACE면 대상의 기존 키 덮어쓰기를 허용합니다.37

이 과정에서는 값 복사와 슬롯 소유권 변경이 별개입니다. MIGRATE 한 번은 전체 슬롯의 키를 모두 옮겼다는 증거도 아닙니다. 대상의 RESTORE와 원본의 DEL도 각 노드의 복제와 영속화 경로를 따릅니다.

src/cluster.c L7151-L7185
for (j = 0; j < num_keys; j++) {
if (connSyncReadLine(cs->conn, buf2, sizeof(buf2), timeout) <= 0) {
socket_error = 1;
break;
}
if ((password && buf0[0] == '-') ||
(select && buf1[0] == '-') ||
buf2[0] == '-')
{
/* On error assume that last_dbid is no longer valid. */
/* 첫 번째 오류만 클라이언트에 응답 */
} else {
if (!copy) {
/* No COPY option: remove the local key, signal the change. */
dbDelete(c->db,kv[j]);
signalModifiedKey(c,c->db,kv[j]);
notifyKeyspaceEvent(NOTIFY_GENERIC,"del",kv[j],c->db->id);
server.dirty++;
/* Populate the argument vector to replace the old one. */
newargv[del_idx++] = kv[j];
incrRefCount(kv[j]);
}
}
}

target이 각 키의 RESTORE에 OK로 답할 때마다, COPY가 아니면 원본에서 dbDelete로 키를 지우고 newargv에 모아 둡니다. 오류가 난 키는 지우지 않으므로 원본에 그대로 남습니다.

src/cluster.c L7187-L7215
/* On socket error, if we want to retry, do it now before rewriting the
* command vector. We only retry if we are sure nothing was processed
* and we failed to read the first reply (j == 0 test). */
if (!error_from_target && socket_error && j == 0 && may_retry &&
errno != ETIMEDOUT)
{
goto socket_err; /* A retry is guaranteed because of tested conditions.*/
}
/* On socket errors, close the migration socket now that we still have
* the original host/port in the ARGV. Later the original command may be
* rewritten to DEL and will be too later. */
if (socket_error) migrateCloseSocket(c->argv[1],c->argv[2]);
if (!copy) {
/* Translate MIGRATE as DEL for replication/AOF. Note that we do
* this only for the keys for which we received an acknowledgement
* from the receiving Redis server, by using the del_idx index. */
if (del_idx > 1) {
newargv[0] = createStringObject("DEL",3);
/* Note that the following call takes ownership of newargv. */
replaceClientCommandVector(c,del_idx,newargv);
argv_rewritten = 1;
} else {
/* No key transfer acknowledged, no need to rewrite as DEL. */
zfree(newargv);
}
newargv = NULL; /* Make it safe to call zfree() on it in the future. */
}

재시도 조건은 네 가지입니다. target이 오류로 답한 게 아니라 소켓 오류가 났고, 응답을 하나도 못 읽었고(j == 0), 이번이 첫 시도이고(may_retry), 타임아웃이 아니어야 합니다. 키는 OK 응답을 읽은 뒤에만 지우므로 j == 0이면 지운 키가 없고, 그래서 다시 보내도 안전합니다. 끝나면 지운 키만 모아 명령을 DEL로 바꿔 replica와 AOF에 전파합니다.

키가 옮겨져도 owner는 아직 A입니다

공식 ownerA
A의 keyV
B의 key없음
라우팅A 처리

시작

A가 슬롯과 키를 갖고 있습니다.

같은 슬롯의 키 하나를 옮기는 성공 경로입니다. 값 V와 노드 이름은 설명용이며 복제 ACK와 슬롯 전체의 반복 이동은 생략합니다.
전체 상태 보기 (JavaScript 없이도 읽을 수 있습니다)

IMPORTING → MIGRATING → NODE

  1. 시작

    공식 owner: A · A의 key: V · B의 key: 없음 · 라우팅: A 처리

    A가 슬롯과 키를 갖고 있습니다.

  2. 이동 상태 설정

    공식 owner: A · A의 key: V · B의 key: 없음 · 라우팅: 기존 키: A

    B는 IMPORTING, A는 MIGRATING입니다. owner는 그대로입니다.

  3. B의 RESTORE 성공

    공식 owner: A · A의 key: V · B의 key: V · 라우팅: owner는 A

    B가 값을 받았습니다. 원본 삭제보다 앞입니다.

  4. A가 성공 응답 수신

    공식 owner: A · A의 key: 없음 · B의 key: V · 라우팅: A: ASK B

    COPY 없는 성공 경로에서 A가 원본을 삭제합니다.

  5. 슬롯 전체 점검

    공식 owner: A · A의 key: 없음 · B의 key: V · 라우팅: ASKING으로 B

    A에 남은 슬롯 키가 없는지 확인합니다. 그림은 한 키만 보여 줍니다.

  6. 소유권 확정과 전파

    공식 owner: B · A의 key: 없음 · B의 key: V · 라우팅: MOVED B

    B가 슬롯 담당자가 됩니다. 다른 노드와 클라이언트는 새 맵을 배웁니다.

MIGRATE 중 네트워크가 끊겼을 때

가장 위험한 지점은 “대상에 썼습니다”와 “그 성공 응답을 소스가 받았습니다” 사이입니다. 대상은 RESTORE를 마쳤는데 응답을 잃으면, A는 원본을 삭제해도 되는지 알 수 없습니다. 이 소스는 확인하지 못한 키를 원본에 남길 수 있습니다. 타임아웃은 이동이 아무 일도 하지 않았다는 증거가 아닙니다.37

응답 하나를 잃으면 두 복사본이 남을 수 있습니다

AV
네트워크연결됨
B없음

원본

A만 V를 갖고 있습니다.

MIGRATE의 RESTORE 성공과 응답 수신을 분리한 가능한 순서입니다. 실제 장애 조치까지 시뮬레이션하지 않으며, 그림의 중복은 성공 응답 유실을 설명합니다.
전체 상태 보기 (JavaScript 없이도 읽을 수 있습니다)

응답 도착

  1. 원본

    A: V · 네트워크: 연결됨 · B: 없음

    A만 V를 갖고 있습니다.

  2. RESTORE 실행

    A: V · 네트워크: OK 전송 · B: V

    B가 V를 저장하고 성공 응답을 보냅니다.

  3. OK 수신

    A: 없음 · 네트워크: OK 도착 · B: V

    A가 확인한 뒤 원본을 삭제합니다.

응답 유실

  1. 원본

    A: V · 네트워크: 연결됨 · B: 없음

    A만 V를 갖고 있습니다.

  2. RESTORE 실행

    A: V · 네트워크: OK 전송 · B: V

    B에는 이미 V가 있습니다.

  3. 응답을 못 받음

    A: V 남음 · 네트워크: IOERR 가능 · B: V 남음

    A는 성공을 확인하지 못합니다. 대상에 데이터가 없다고 판단해서는 안 됩니다.

  4. 복구 판단

    A: 검사 필요 · 네트워크: 재연결 · B: 검사 필요

    슬롯 상태와 양쪽 데이터 및 새 쓰기를 확인한 뒤 재개 방식을 정합니다. 자동 삭제나 무조건 REPLACE하지 않습니다.

단일 키와 KEYS 여러 키를 옮기는 경우도 구분합니다. 여러 RESTORE 응답을 처리하는 중에는 어떤 키는 확인 후 삭제됐고, 어떤 키는 원본에 남은 부분 진행 상태가 가능합니다. 한 번의 실패를 슬롯 전체의 rollback으로 해석하지 않습니다.

끊긴 위치별로 확인할 것

끊긴 위치가능한 상태먼저 확인할 것
대상 연결 또는 AUTH 실패원본만 남을 수 있습니다.정확한 오류와 대상 접근 권한
RESTORE가 대상에서 오류 응답해당 원본이 남습니다.BUSYKEY, OOM, 대상 역할과 importing 상태
RESTORE 성공 뒤 응답 유실양쪽에 값이 남을 수 있습니다.양쪽 키 값, TTL, 최근 쓰기, owner와 이동 상태
원본 삭제 뒤 대상이 장애대상 replica가 아직 값을 못 받았을 수 있습니다.대상 복제 진행과 영속화, 슬롯 복구 상태
모든 키 이동 뒤 owner 전파 중 단절노드마다 owner 정보가 잠시 다를 수 있습니다.각 노드의 슬롯 맵과 config epoch, 남은 importing/migrating 표시

마지막 두 행은 MIGRATE 성공 응답을 분산 트랜잭션의 commit으로 부를 수 없는 이유입니다. 대상에서 WAIT나 WAITAOF를 추가로 사용하려면 같은 연결의 offset 조건부터 해결해야 합니다. 소스에서 MIGRATE를 실행한 연결에 WAIT를 붙였다고 대상 replica의 RESTORE가 확인되는 것은 아닙니다.

복구 중에는 클라이언트가 여전히 쓸 수 있다는 점도 중요합니다. 중복된 두 값이 시작할 때는 같았어도 나중에도 같다는 보장은 없습니다. TTL까지 비교하지 않고 원본을 지우거나 MIGRATE ... REPLACE를 반복하면 새 값을 덮거나 수명을 바꿀 수 있습니다.

Cluster의 --cluster fix도 업무 의미를 알고 두 값을 합치는 도구가 아닙니다. 변경 전에 노드별 CLUSTER NODES, CLUSTER SLOTS, CLUSTER COUNTKEYSINSLOT, 필요한 키의 값과 TTL, 복제 상태를 보존하고 쓰기 경로를 통제해야 합니다. 키 공간에 개인정보가 있다면 진단 데이터도 보호해야 합니다.

만료와 축출은 삭제 이유가 다릅니다

만료(expiration)는 키의 유효 시간이 끝난 일이고, 축출(eviction)은 메모리가 부족해 값을 내보내는 일입니다. 둘 다 키가 사라지므로 캐시 사용자에게는 miss가 되지만, 운영 지표와 해결책은 다릅니다.

db.c의 expireIfNeeded는 조회 경로에서 만료를 검사합니다. expire.c의 activeExpireCycle은 TTL이 있는 dict를 조금씩 훑어 만료된 키를 정리합니다. 이 태그는 dictScan 기반의 cursor도 사용합니다. 옛 버전의 “매번 무작위 키 몇 개를 뽑습니다”를 그대로 복사하지 않습니다.38

active-expire-effort의 기본값은 1이며 범위는 1부터 10입니다. 값을 올리면 검사량, 허용하는 stale 비율과 CPU 시간 예산이 달라집니다. hz=10, dynamic-hz=yes도 “키 TTL이 100 ms 단위로만 정확하다”는 뜻은 아닙니다. 논리적 만료 판정과 실제 메모리 정리 주기를 분리합니다.39

primary의 삭제는 복제 스트림으로 전파됩니다. replica는 복제 원본의 만료·삭제를 따라야 하므로 일반 replica 상태에서 자체적으로 데이터셋을 무조건 삭제하지 않습니다. 그렇다고 만료된 키를 사용자 읽기에 항상 반환하는 것도 아닙니다. expireIfNeeded는 논리적으로 expired라고 호출자에게 알려 줄 수 있습니다.38

maxmemory는 프로세스 RSS 상한이 아닙니다

performEvictions는 getMaxmemoryState로 축출 관점의 메모리를 검사합니다. freeMemoryGetNotCountedMemory는 AOF 버퍼와 복제 버퍼의 일부를 빼 줍니다. 복제 backlog 목표 크기에 해당하는 부분까지 전부 무조건 제외하는 것도 아닙니다. 소스는 backlog 크기와 블록 overhead를 고려한 기준보다 큰 복제 버퍼 부분을 따로 계산합니다.40

삭제한 키의 DEL이 복제/AOF 버퍼를 늘리고, 그 늘어난 버퍼 때문에 다시 키를 지우는 악순환을 막으려는 계산입니다. INFO memory의 mem_not_counted_for_evict를 볼 이유가 여기에 있습니다. allocator 여유, fork의 copy-on-write와 기타 RSS 비용까지 포함한 호스트 용량 계획은 별도로 해야 합니다.

정책후보와 선택
noeviction키를 축출하지 않습니다. OOM에서 거절 대상인 명령은 실패합니다.
allkeys-lru / volatile-lru전체 키 또는 TTL 있는 키 중 샘플의 최근 접근 정보를 비교합니다.
allkeys-lfu / volatile-lfu같은 후보 범위에서 감쇠하는 빈도 정보를 비교합니다.
allkeys-random / volatile-random해당 범위에서 무작위 후보를 고릅니다.
volatile-ttlTTL 있는 후보 중 더 빨리 만료될 키를 선호합니다.

기본 maxmemory는 0, 기본 정책은 noeviction입니다. volatile-*인데 TTL 있는 키가 없다면 축출할 후보가 없을 수 있습니다. “메모리 제한을 걸었으니 Redis가 아무 키나 알아서 지웁니다”는 기본 동작이 아닙니다.39

LRU는 전체 키의 완벽한 접근 순서 리스트를 유지하지 않습니다. 기본 maxmemory-samples=5로 표본을 채우고 eviction pool에서 더 좋은 후보를 유지하는 근사 방식입니다. maxmemory-eviction-tenacity=10은 축출 작업 시간 예산에 관여하며 CPU 비율 10%라는 뜻이 아닙니다.40

src/evict.c L168-L187
/* Calculate the idle time according to the policy. This is called
* idle just because the code initially handled LRU, but is in fact
* just a score where an higher score means better candidate. */
if (server.maxmemory_policy & MAXMEMORY_FLAG_LRU) {
idle = estimateObjectIdleTime(o);
} else if (server.maxmemory_policy & MAXMEMORY_FLAG_LFU) {
/* When we use an LRU policy, we sort the keys by idle time
* so that we expire keys starting from greater idle time.
* However when the policy is an LFU one, we have a frequency
* estimation, and we want to evict keys with lower frequency
* first. So inside the pool we put objects using the inverted
* frequency subtracting the actual frequency to the maximum
* frequency of 255. */
idle = 255-LFUDecrAndReturn(o);
} else if (server.maxmemory_policy == MAXMEMORY_VOLATILE_TTL) {
/* In this case the sooner the expire the better. */
idle = ULLONG_MAX - (long)dictGetVal(de);
} else {
serverPanic("Unknown eviction policy in evictionPoolPopulate()");
}

변수 이름은 idle이지만 정책마다 뜻이 다른 점수이고, 높을수록 먼저 쫓겨납니다. LRU는 유휴 시간, LFU는 255 - 빈도, volatile-ttl은 ULLONG_MAX - 만료 시각이라 만료가 가까운 키일수록 점수가 높습니다.

LFU는 정확한 요청 카운터가 아닙니다. 객체 필드의 8비트 logarithmic counter와 16비트 분 단위 감쇠 정보를 사용합니다. 실제 LFUDecrAndReturn은 경과 감쇠 구간 수를 카운터에서 빼 줍니다. 근처의 오래된 주석에 보이는 “항상 반으로 줄입니다”만 옮기면 구현과 달라집니다. 기본 lfu-log-factor=10, lfu-decay-time=1도 이 확률 증가와 감쇠를 조정하는 값입니다.41

src/evict.c L297-L326
/* Logarithmically increment a counter. The greater is the current counter value
* the less likely is that it gets really incremented. Saturate it at 255. */
uint8_t LFULogIncr(uint8_t counter) {
if (counter == 255) return 255;
double r = (double)rand()/RAND_MAX;
double baseval = counter - LFU_INIT_VAL;
if (baseval < 0) baseval = 0;
double p = 1.0/(baseval*server.lfu_log_factor+1);
if (r < p) counter++;
return counter;
}
/* 중략 */
unsigned long LFUDecrAndReturn(robj *o) {
unsigned long ldt = o->lru >> 8;
unsigned long counter = o->lru & 255;
unsigned long num_periods = server.lfu_decay_time ? LFUTimeElapsed(ldt) / server.lfu_decay_time : 0;
if (num_periods)
counter = (num_periods > counter) ? 0 : counter - num_periods;
return counter;
}

LFULogIncr는 카운터를 확률 p = 1/((counter - 5) * lfu-log-factor + 1)로만 올립니다(5는 LFU_INIT_VAL, server.h L3411). 기본 factor 10에서 redis.conf L2168-L2180의 표는 100회 접근에 10, 1M회에 255를 보여줍니다. LFUDecrAndReturn은 lru 필드 24비트를 상위 16비트 분 단위 시각과 하위 8비트 카운터로 나눠 쓰고, lfu-decay-time 분이 지날 때마다 1씩 깎습니다.

replica-ignore-maxmemory=yes가 기본이라 replica는 primary의 데이터셋을 따라가면서 독립적인 축출을 억제합니다. replica의 실제 메모리와 호스트 제한은 여전히 필요합니다. 승격되면 primary로서 메모리 정책을 적용하므로 역할 변경 직후의 여유도 확인해야 합니다.39

RDB, AOF와 다시 시작한 서버

RDB는 시점 스냅샷입니다. rdbSaveBackground는 자식 프로세스에서 저장하며, 부모는 계속 요청을 처리할 수 있습니다. fork와 copy-on-write 비용이 있으므로 “백그라운드라 메인 서버에 영향이 없습니다”로 설명하지 않습니다.5

AOF는 이후 명령을 기록하는 경로입니다. 쓰기 버퍼, OS에 쓰는 작업, fsync 완료는 같은 사건이 아닙니다. 기본 appendonly=no이고, AOF를 켰을 때 기본 fsync 정책은 everysec입니다. always는 더 자주 동기화하며 지연과 저장 오류 처리도 다릅니다.42

이 버전의 AOF rewrite는 base 파일과 이후 incremental 파일, manifest를 함께 관리하는 multi-part AOF 구조입니다. 무작정 오래된 파일 하나를 지우는 유지보수 예제를 쓰지 않습니다. 복원하려면 manifest와 그 파일 집합의 관계를 보아야 합니다.5

everysec는 정상적인 운용 목표와, OS 정지나 저장장치 장애까지 포함한 보장이 다릅니다. 장애 종류와 저장장치 동작을 확인하지 않고 무조건 “정확히 1초만 잃습니다”라고 약속하지 않습니다. WAIT, WAITAOF, AOF 정책, replica 선택을 각각의 완료 조건으로 읽습니다.

캐시와 원본 저장소도 구분해야 합니다. 원본 DB에서 다시 만들 수 있는 데이터라면 miss와 재가열 부하가 문제입니다. Redis에만 있는 데이터라면 ACK와 복구 정책이 데이터 유실 계약이 됩니다. 이름을 cache라고 붙인다고 복구할 원본이 생기지는 않습니다.

Pub/Sub는 복제 확인이나 작업 완료 확인이 아닙니다

pubsubPublishMessageInternal은 채널의 구독자 목록을 찾고 각 클라이언트의 응답 버퍼에 메시지를 넣습니다. 일반 Pub/Sub에서는 pattern 목록도 검사합니다. disconnected subscriber를 위해 메시지 이력을 보관하거나 재접속 후 replay하는 큐가 아닙니다.43

PUBLISH의 정수 응답은 서버가 메시지를 보낸 로컬 구독 전달 수에 관련된 값입니다. 소비자가 코드를 실행했는지, 일을 끝냈는지, 디스크에 남겼는지를 확인한 값이 아닙니다. 채널 구독과 pattern 구독이 겹치면 하나의 연결이 여러 전달을 받을 수도 있으므로 유일한 사용자 수로 읽지 않습니다.

일반 Cluster Pub/Sub는 cluster bus로 메시지를 전파합니다. sharded Pub/Sub의 SPUBLISH, SSUBSCRIBE는 채널을 슬롯에 배정하고 해당 shard 범위로 전파합니다. pubsubPublishMessageInternal의 shard 분기는 pattern 구독을 처리하지 않습니다. shard는 노드 하나만 뜻하지 않고 그 primary와 replicas의 묶음입니다.44

standalone에서 일반 PUBLISH를 replication으로 전달하는 코드가 있다고 메시지가 영속 큐가 되는 것도 아닙니다. 일반 PUBLISH는 AOF에 저장해 구독자별 replay하는 방식이 아닙니다. 전달 보장을 요구하면 Streams나 외부 큐의 보관, ACK와 재처리 정책을 함께 검토합니다.

느린 구독자는 output buffer를 키울 수 있습니다. client-output-buffer-limit pubsub 32mb 8mb 60은 이 태그의 설정 파일에 있는 값입니다. hard limit과 soft limit 및 지속 시간을 정하며, 한계를 넘으면 연결이 닫힐 수 있습니다. 마지막 60은 메시지 개수가 아니라 초입니다.45

재접속했다고 놓친 메시지가 따라오지는 않습니다. 알림이 손실돼도 다음 조회로 복원할 수 있는 용도인지, 모든 이벤트를 처리해야 하는 작업인지부터 결정합니다. keyspace notification도 Pub/Sub이므로 영속 변경 로그로 취급하지 않습니다.

ACL은 명령, 키, 채널을 함께 검사합니다

이 릴리스는 TLS pending-data 처리, ACL key extraction, blocked-client 처리의 보안 수정이 포함된 버전입니다. 본문의 구현 설명은 수정된 태그에 고정합니다. 예전 Redis의 동작이나 현재 문서만으로 접근 제어를 판단하지 않습니다.46

ACLCheckAllPerm은 사용자와 명령, 인자 배열을 넘겨 ACLCheckAllUserCommandPerm을 호출합니다. selector 하나가 명령과 필요한 모든 키·채널 조건을 만족하면 허용합니다. 서로 다른 selector에서 GET 권한과 키 패턴을 하나씩 꺼내 섞어 새 허용 조합을 만드는 방식이 아닙니다.47

키는 모든 인자를 키로 간주해서 검사하지 않습니다. 명령의 key specs와 필요한 추출 경로로 실제 접근 키를 찾습니다. EVAL처럼 인자에 키 수가 있는 명령, SORT의 간접 접근처럼 별도 주의가 필요한 경로가 있어서 arity와 추출 검증이 권한 검사의 일부입니다.

ACL 표현의미
on / off사용자 활성화 여부
+get, -set명령 허용과 거절
+@read, -@all명령 카테고리
~cache:*read/write 키 패턴
%R~cache:* / %W~cache:*읽기 또는 쓰기 키 접근 패턴
&events:*Pub/Sub 채널 패턴. 키 패턴과 별개입니다.
reset / clearselectors기존 권한과 selector를 어떻게 지울지 정합니다.

default user는 특별합니다. ACLCreateDefaultUser는 on, nopass, +@all, ~*, &*로 만듭니다. 새 제한 사용자에 채널 권한이 기본으로 열리는 것과 같은 규칙이 아닙니다. 기본 acl-pubsub-default는 제한적이며, 실제 서버의 ACL과 네트워크 설정을 확인해야 합니다.48

PSUBSCRIBE의 pattern 허용도 일반 채널명과 다릅니다. ACLCheckChannelAgainstList는 pattern 구독의 인자를 허용된 패턴과 literal로 비교합니다. 임의 pattern을 주고 서버가 자동으로 안전한 채널 집합을 계산해 준다고 생각하지 않습니다.47

운영 변경 전에는 ACL DRYRUN으로 허용과 거절을 검사하고, 실제 인증된 연결에서도 확인합니다. ACL LOG는 거절 진단에 사용합니다. ACL SETUSER의 실행 중 변경, ACL SAVE로 ACL 파일에 저장하는 일, 설정 파일 재작성은 별개입니다. 재시작 후 유지되는지까지 검사해야 합니다.49

Sentinel이 데이터 노드에 접속하는 인증, replicas가 primary에 접속하는 인증, 일반 앱의 인증도 서로 다른 연결입니다. 앱용 GET/SET 사용자 하나를 재사용했다가 감시자의 INFO나 역할 변경 명령이 거절되면 데이터가 살아 있어도 장애 조치가 막힐 수 있습니다. 각 역할에 필요한 최소 권한은 해당 태그의 Sentinel 문서와 실제 거절 로그로 확인해야 합니다.

이 글의 재현과 확인하지 않은 경계

재현 스크립트는 Docker의 redis:7.2.16을 사용하고 서버 버전을 먼저 확인합니다. 호스트의 Redis에는 붙지 않고, 이름이 겹치지 않는 전용 컨테이너 안에서 서버를 띄웁니다. 종료 시 컨테이너를 정리합니다. 운영 서버의 failover 명령을 복사해서 실행하는 실습이 아닙니다.

실행하려면 이 글에 첨부된 Python 스크립트를 내려받아 Docker가 동작하는 환경에서 실행합니다. 별도 Python 패키지는 필요하지 않습니다. 다운로드한 코드는 실행 전에 확인하십시오.

재현 스크립트 내려받기
격리된 재현 실행
python3 test-redis-internals.py --docker

이 실행은 인코딩 경계와 실제 서버의 응답, 정상 복제와 역할 전환, 슬롯 라우팅을 assertion으로 확인합니다. 소스에서 읽은 전체 상태 머신을 가능한 모든 스케줄에서 증명하는 검사는 아닙니다. 테스트 토폴로지의 실패 주입과 대기 제한은 재현용 값이며 권장 운영 기본값이 아닙니다.

실제로 통과한 항목은 hash/set/zset의 원소 수·바이트 경계, list의 성장과 축소, 인증된 ACL selector의 분리, Pub/Sub 재접속 시 미전달 메시지가 재생되지 않는 동작, 같은 연결의 WAIT와 읽기 전용 replica입니다. standalone 역할 교체 후 새 쓰기 복제, Sentinel의 SDOWN·ODOWN·leader 선출·주소 변경, Cluster의 PFAIL·FAIL·replica 승격도 확인했습니다. 슬롯 이동에서는 ASK·MOVED·TRYAGAIN, ASKING과 GET, MIGRATE 성공 후 원본 삭제와 실제 BUSYKEY 오류 후 양쪽 값 보존을 검사했습니다.

성공한 RESTORE의 응답 유실은 주입하지 않았습니다. BUSYKEY 오류 재현을 응답 유실 재현으로 세지 않습니다. WAITAOF, 디스크 전원 차단과 운영 규모의 부하도 이번 실행의 검사 항목에 없습니다.

네트워크가 단절되는 시점, 스토리지 전원 차단, 두 분할에서 동시에 새 쓰기가 발생하는 모든 조합을 한 노트북 실험으로 보장할 수 없습니다. 그런 경우는 본문의 소스 분기와 가능한 순서로 설명했습니다. 수치화한 장애 복구 SLA, 운영 환경 용량과 데이터 유실 상한은 이 글의 결과가 아닙니다.

다음 장애에서 판단해 봅니다

퀴즈상황을 바꾸어 적용합니다

답을 고르면 해설이 나옵니다.

5문제 중 0개 맞힘

  1. SET에 OK를 받았습니다. primary가 끊기고, 그 쓰기를 못 받은 replica가 승격됐습니다. 어떤 결과가 가능합니까?

  2. CLUSTER FAILOVER FORCE는 무엇을 건너뜁니까?

  3. MIGRATE에 IOERR가 나왔습니다. 바로 원본을 삭제해도 됩니까?

  4. 소스에서 MIGRATE를 실행하고 같은 연결로 WAIT를 했습니다. 대상 replica의 RESTORE까지 기다린 것입니까?

  5. PUBLISH가 구독 전달 수를 반환했습니다. 소비자의 작업 완료를 확인한 것입니까?

다시 떠올릴 용어

카드를 누르면 뒤집힙니다.

10장 중 0장 확인

소스를 다시 열 때의 지도

동작을 바꾸는 설정을 보았다면 그 값을 읽는 함수를 찾아야 합니다. 설정 이름에서 다음 함수로 들어가면 이 글의 설명을 다시 확인할 수 있습니다.

질문파일과 진입점
왜 명령이 거절됐습니까server.c: processCommand
누가 실제 명령을 실행합니까server.c: call, networking.c: threaded read 후처리
작은 값이 왜 큰 표현으로 바뀌었습니까t_hash.c, t_set.c, t_zset.c, t_list.c
왜 full sync로 갔습니까replication.c: masterTryPartialResynchronization
왜 WAIT의 결과가 부족합니까replication.c: waitCommand, processClientsWaitingReplicas
ODOWN인데 왜 선거가 안 됩니까sentinel.c: sentinelGetLeader, sentinelFailoverStateMachine
왜 이 replica가 선택됐습니까sentinel.c: sentinelSelectSlave, compareSlavesForPromotion
왜 Cluster 쓰기와 승격이 막혔습니까cluster.c: clusterUpdateState, clusterHandleSlaveFailover
왜 ASK, MOVED, TRYAGAIN을 받았습니까cluster.c: getNodeByQuery
MIGRATE 실패 뒤 어떤 키가 남습니까cluster.c: migrateCommand
왜 메모리 한도보다 RSS가 큽니까evict.c: getMaxmemoryState, freeMemoryGetNotCountedMemory
왜 구독 전달 수가 완료 수가 아닙니까pubsub.c: pubsubPublishMessageInternal
권한 조합은 어디서 검사합니까acl.c: ACLSelectorCheckCmd, ACLCheckAllUserCommandPerm

설명 전체를 “Redis가 알아서 복구합니다”로 줄이면, 어디서 관측하고 어디서 투표하며 어떤 ACK를 기다리는지가 사라집니다. 운영 판단에는 그 경계가 필요합니다. 지금 보고 있는 명령이 바꾼 메모리, 복제 역사, 슬롯 소유권 중 무엇을 확인했는지부터 적어 두면 다음 장애에서 확인할 대상이 줄어듭니다.

각주

  1. networking.c, 입력 처리. ↩

  2. processCommand, call. ↩

  3. multiCommand, execCommand. ↩

  4. handleClientsWithPendingReadsUsingThreads, config.c, I/O 설정. ↩

  5. rdbSaveBackground, aof.c, bio.c. ↩ ↩2 ↩3

  6. object.c, 생성과 인코딩, sds.h. ↩ ↩2

  7. dictRehash. ↩

  8. zslInsert, span과 바이트 순서, zslGetRank. ↩

  9. streamAppendItem, t_stream.c, 그룹과 ACK. ↩

  10. listpack.c, 형식, lpInsert. ↩ ↩2

  11. hashTypeSet, setTypeCreate / setTypeAddAux. ↩

  12. t_list.c, 양방향 표현 전환. ↩

  13. replication.c. ↩

  14. masterTryPartialResynchronization. ↩

  15. replication.c, full sync 준비, syncCommand. ↩

  16. config.c, 복제 bool 설정, config.c, 복제 숫자 설정. ↩

  17. replication.c, replication ID 변경. ↩

  18. waitCommand, waitaofCommand. ↩ ↩2

  19. replicaofCommand, failoverCommand. ↩ ↩2

  20. sentinelCheckSubjectivelyDown. ↩

  21. sentinelCheckObjectivelyDown. ↩

  22. sentinelVoteLeader, sentinelGetLeader. ↩

  23. sentinel.c, failover 상태 상수, sentinelFailoverStateMachine. ↩

  24. compareSlavesForPromotion, sentinelSelectSlave. ↩

  25. sentinel.c, 기본 상수, sentinelHandleConfiguration. ↩

  26. sentinelCheckObjectivelyDown, sentinelGetLeader. ↩

  27. server.c, 정상 replica 검사. ↩

  28. sentinelCheckTiltCondition, sentinel.c, TILT 상수. ↩

  29. keyHashSlot, cluster.h, CLUSTER_SLOTS. ↩

  30. clusterProcessPacket, cluster.h, bus port offset. ↩

  31. markNodeAsFailingIfNeeded 주변, cluster.h, FAIL 상수. ↩

  32. clusterSendFailoverAuthIfNeeded, clusterGetSlaveRank, clusterHandleSlaveFailover. ↩ ↩2

  33. config.c, Cluster 기본값. ↩ ↩2

  34. CLUSTER FAILOVER 처리, clusterHandleManualFailover, clusterBumpConfigEpochWithoutConsensus. ↩

  35. clusterUpdateState. ↩

  36. getNodeByQuery, clusterRedirectClient, CLUSTER SETSLOT. ↩ ↩2

  37. migrateCommand, restoreCommand, BUSYKEY. BUSYKEY는 migrateCommand가 직접 내지 않습니다. 대상 노드의 restoreCommand가 REPLACE 없이 이미 있는 키를 만나면 내고, MIGRATE가 그 오류를 그대로 돌려줍니다. ↩ ↩2

  38. activeExpireCycle, expireIfNeeded. ↩ ↩2

  39. config.c, 메모리 설정, redis.conf, hz. ↩ ↩2 ↩3

  40. evict.c, 메모리 계산, performEvictions. ↩ ↩2

  41. LFULogIncr / LFUDecrAndReturn. ↩

  42. redis.conf, appendonly, aof.c, fsync. ↩

  43. pubsubPublishMessageInternal / publishCommand. ↩

  44. pubsub.c, sharded 분기, cluster.c, clusterPropagatePublish. ↩

  45. redis.conf, output buffer 제한. ↩

  46. 7.2.16 release. 이 글의 모든 구현 링크는 커밋 335554f18caf7bbf6b0ac2b3548133d750f00a1b에 고정합니다. ↩

  47. ACLSelectorCheckCmd / ACLCheckAllUserCommandPerm. ↩ ↩2

  48. ACLCreateDefaultUser, config.c, acl-pubsub-default. ↩

  49. ACLSaveToFile, 파일 저장과 startup 처리, ACL DRYRUN. ↩

~/blog/redis-7-2-internals/en.mdx

Redis 7.2.16 internals: from one write to failover

Follow source functions from command execution and data structures through replication, Sentinel voting, Cluster failover and slot migration. Connect lost MIGRATE replies, eviction, Pub/Sub and ACL inside the same server.

You sent SET to Redis and received OK. What has finished? The value is in the memory of the server you connected to. Whether a replica received it, whether it reached disk, and whether it survives the next failover require separate checks.

This article follows that one write. It starts with receiving and executing a command, stores a value in a byte array, sends it over a replication connection, and examines who becomes the next writer when a server disconnects. Later sections follow slot migration through a lost reply.

The analysis is pinned to commit 335554f18caf7bbf6b0ac2b3548133d750f00a1b of Redis 7.2.16. The release was published on 2026-08-17; the displayed date is 2026-08-24, the following week. The source investigation and reproductions below were verified on 2026-10-10. The displayed date is not a record of when I ran the experiments.

Current redis.io documentation can include features from later versions, so the implementations and defaults here are pinned to this commit. Diagram playback uses edited snapshots of sequences read from the source. It does not run Redis in the browser or predict failure timing.

Client SET Command checks and execution Current primary memory Asynchronous replication RDB / AOF Sentinel: external monitor voting Cluster: slot-owning primary voting Slot migration: data and ownership

On a first read, follow §1 through §8 in order. For an operational problem, start at §5 for replication, §7 for Sentinel, §9 for Cluster, or §11 for slot migration. Cache usage patterns are covered in the cache field guide, listpack memory measurements in the listpack article, and rank calculations in the skip list article. Those articles use different reference versions.

Before a command executes

A TCP connection is not a command. Redis must read the client’s RESP bytes and parse them into a command name and argument array. Following readQueryFromClient and processInputBuffer in networking.c leads to processCommand in server.c.1

processCommand has several gates before an actual write. It checks the command and argument count, authentication and ACL. In Cluster mode, it checks whether the keys belong to this node’s slots. Memory pressure, disk errors, insufficient replicas and a read-only replica role can also reject the command here. If the checks pass, call executes c->cmd->proc(c).2

RESP bytes Input buffer and argv Command / arity check AUTH / ACL Slot routing Memory / disk / role checks call: command function Reply buffer AOF / replication propagation

Finishing reads and parsing does not mean the command has executed. RESP completeness and the command’s argument count are separate checks.

Before execution, Redis checks permissions, slot ownership and whether it can accept the write. A MOVED or NOPERM response can mean the command never reached the function that modifies its data structure.

The command function changes memory and prepares a reply. Propagation and persistence have separate paths, so OK is not a completion marker for replicas or disk.

MULTI queues commands for execution at EXEC. Preventing other ordinary clients’ commands from interleaving during execution and undoing an earlier command’s results are different features. Redis transactions do not have SQL-style rollback. Ignoring an execution-time command error and concluding that “EXEC is atomic, so everything succeeded” is incorrect.3

What single-threaded execution does and does not explain

In this version, the main thread executes ordinary commands. A large command that takes a long time therefore affects other requests waiting on the same execution path. Pipelining reduces network round trips; it does not remove the server execution cost of a large SMEMBERS or a long Lua operation.

That does not mean the Redis process has only one thread. io-threads defaults to 1 and io-threads-do-reads to no. When enabled, I/O threads share socket writes and, optionally, reads and parsing. handleClientsWithPendingReadsUsingThreads waits for their work to finish, then calls processPendingCommandAndInputBuffer on the main thread. This configuration does not distribute command execution across I/O threads.4

Background work is separate too. AOF fsync and lazy free use background jobs, while RDB saves and AOF rewrites use child processes. Remembering only “single-threaded” makes it easy to treat CPU, disk and fork costs as the same problem.5

SLOWLOG and INFO commandstats show time spent on commands inside the server. Application connection-pool waits, network round trips and reading replies are separate. This article does not measure throughput or failover recovery times and generalize them.

TYPE has several encodings underneath

TYPE reports the public data type; OBJECT ENCODING reports its current representation. A redisObject holds the type, encoding, reference count, LRU/LFU information and a pointer to the actual data. Even within hashes, a small one can use listpack while a larger one uses a hashtable.6

Public typeInternal representations to read in this tagFunctions to read
stringInteger int, embstr allocating the object and SDS together, raw with a separate SDScreateStringObject, tryObjectEncoding
hashlistpack of field/value pairs or dicthashTypeSet, hashTypeConvert
setInteger array intset, listpack, dictsetTypeCreate, setTypeAddAux
sorted setSmall listpack or dict plus skip listzsetAdd, zsetConvertAndExpand
listSmall listpack or quicklistlistTypeTryConversionRaw
streamlistpack groups attached to a radix tree, per-group pending statestreamAppendItem

The string embstr boundary in this source is OBJ_ENCODING_EMBSTR_SIZE_LIMIT = 44. This is a byte length, not a promise that every input of 44 bytes or fewer stays embstr forever. Values representable as integers can become integer-encoded, and mutation paths can change the encoding too. SDS stores string length in a separate field, so it can handle NUL bytes inside a value.6

Dict expansion is not exclusively one call that reinserts all keys at once. dictRehash moves buckets incrementally from the old table to the new one. Both tables coexist during this period. “Incremental” still does not guarantee an upper latency bound for each operation: moving the entries linked to one bucket still costs work.7

A sorted set’s dict looks up scores by member, while its skip list finds score order and ranges. A skip list’s span counts skipped elements, enabling rank calculations. Equal scores are ordered by the bytes of member strings. Describing both ZRANK and a large ZRANGE with the same O(log N) line misses the cost of the number of returned elements.8

A stream does not store every message only as a separate dict entry. streamAppendItem converts IDs into sortable bytes and locates a listpack group in the radix tree. The group shares a base ID and field names, compressing message ID differences and repeated fields. A consumer group’s PEL is separate state tracking entries delivered but not yet acknowledged. A consumer reporting completed work with XACK and data becoming durable on disk are different events.9

Boundaries that are easy to miss in listpack

The format in listpack.c consists of a 6-byte header holding the total byte count and element count, the elements, and a 0xff end marker. Each element stores a backlen after its encoded value, describing its own encoded length. That length excludes the backlen’s own size. It locates this element’s start when walking backward; it is not the previous element’s length stored in the next element.10

Header: total length / element count Value A / backlen A Value B / backlen B 0xff

This design eliminates ziplist’s cascading prevlen updates. It does not eliminate moving trailing bytes when inserting into the middle of a contiguous array. lpInsert contains an actual memmove and reallocates when necessary. The caller must retain the new pointer it returns.10

Default thresholds are in this tag’s redis.conf. Entries refer to elements of the public data type. Storing a hash field/value pair as two listpack entries does not halve the field limit.

SettingDefaultWhat it limits
hash-max-listpack-entries512Number of fields
hash-max-listpack-value64Field name or value byte length
zset-max-listpack-entries128Number of members
zset-max-listpack-value64Member byte length
set-max-intset-entries512Number of integer-representable members
set-max-listpack-entries128Number of members in a listpack set
set-max-listpack-value64Member byte length
list-max-listpack-size-2Quicklist node size criterion; -2 selects 8 KiB
list-compress-depth0Depth of uncompressed nodes from each end; 0 disables compression

hashTypeSet converts to a hashtable when the count exceeds 512 or field names or values exceed the length conditions. Deleting entries until the hash becomes small does not automatically convert it back to listpack. For sets, the first value and a hint about how many values will be inserted at once also affect the initial representation. Saying that any non-integer value immediately means hashtable misses the path converting a small intset to listpack.11

Lists especially require a version check. A small list in this tag can be a standalone listpack. listTypeTryConvertListpack converts a growing list to quicklist, while listTypeTryConvertQuicklist checks the reverse conversion when it shrinks to one packed node. Shrink conversion uses half the threshold to reduce repeated representation changes near the boundary. Do not generalize another type’s one-way conversion into a rule for every Redis type.12

QuizWhy check the encoding?

Choose an answer to see the explanation.

0 of 1 right

  1. Do all Redis data structures switch back to a compact encoding after shrinking?

Replication means rejoining the same byte history

The primary accepts current writes; a replica follows that server’s replication stream. Replication is asynchronous by default. An ordinary SET does not execute a write on the primary and then wait for every replica’s acknowledgment before returning OK.13

After connecting, a replica proceeds through PING, authentication if needed, REPLCONF negotiation and PSYNC. The comparison here concerns the replication ID and the stream’s byte offset, not the number of keys. A replica with a higher offset has received more of the stream; that does not mean every byte in the replication stream is user data.14

Partial resynchronization requires the requested ID to match the current history or an accepted previous history, and the backlog to retain the bytes from the requested offset. The backlog retains replication history so a replica can catch up after a brief disconnection. It is not an unlimited database change log.

src/replication.c L755-L792
if (strcasecmp(master_replid, server.replid) &&
(strcasecmp(master_replid, server.replid2) ||
psync_offset > server.second_replid_offset))
{
/* Replid "?" is used by slaves that want to force a full resync. */
/* log omitted */
goto need_full_resync;
}
/* We still have the data our slave is asking for? */
if (!server.repl_backlog ||
psync_offset < server.repl_backlog->offset ||
psync_offset > (server.repl_backlog->offset + server.repl_backlog->histlen))
{
/* log omitted */
goto need_full_resync;
}

The first if checks that the replid sent by the replica matches the current one. If it does not, it passes only when it matches the previous replid (replid2) and the requested offset is at or below second_replid_offset. The second if checks that the requested offset still lies inside the backlog; failing either check jumps to need_full_resync.

If those conditions fail, Redis performs full resynchronization. The primary sends a reference offset and an RDB snapshot, followed by the stream generated while the snapshot was being created, which the replica continues applying. It does not copy current memory piecemeal in arbitrary order without a snapshot.15

SettingDefaultMeaning of changing it
repl-backlog-size1 MiBTarget size of the stream retained during disconnection. Consider write volume and disconnection duration together.
repl-backlog-ttl3600 secondsWhen to free the backlog if no replicas are connected. This is not a key TTL.
repl-timeout60 secondsTimeout for replication connections and transfers, separate from Sentinel detection time.
repl-ping-replica-period10 secondsHow often the primary sends PING over replication connections.
repl-diskless-syncyesAllows sending a full-sync RDB over sockets instead of a disk file.
repl-diskless-sync-delay5 secondsDelay to group full-sync starts together.
repl-diskless-loaddisabledLoading mode on the receiving replica, distinct from the sending setting.
replica-read-onlyyesRejects ordinary application writes on a replica.
replica-serve-stale-datayesCan allow reads while replication is disconnected. This does not guarantee freshness.

I checked these values in the configuration registry and the tag’s configuration file.16 Diskless does not remove all disk, CPU and memory costs. Creating and loading an RDB still require work.

Promotion creates a new replication ID. Redis retains the previous ID and valid offset boundary in replid2 and second_replid_offset, giving existing replicas a chance to partially resynchronize from the previous history. It does not merge divergent write histories into one ID.17

Between OK and replica application

ClientWaiting
primaryA
replicaA

Start

Both servers hold A.

A and B are illustrative values. These snapshots show possible asynchronous replication orderings, not measured transfer delays.
All snapshots (also available without JavaScript)

Failure after application

  1. Start

    Client: Waiting · primary: A · replica: A

    Both servers hold A.

  2. Execute SET B

    Client: OK · primary: B · replica: A

    The current primary writes B and replies OK.

  3. Apply replication

    Client: OK · primary: B · replica: B

    The replica applies the stream containing B.

  4. Primary fails

    Client: Reconnect needed · primary: Stopped · replica: B

    B remains if a replica that received it is selected. Selection and persistence conditions are separate.

Failure before application

  1. Start

    Client: Waiting · primary: A · replica: A

    Both servers hold A.

  2. Execute SET B

    Client: OK · primary: B · replica: A

    The replica can still hold A even after the client receives OK.

  3. Primary fails

    Client: Reconnect needed · primary: Stopped · replica: A

    In this ordering, only a replica that did not receive B remains eligible for promotion.

  4. Promote replica

    Client: Reads A · primary: Stopped · replica: A / primary

    The new primary does not have B. Receiving OK earlier does not restore it.

What changes with WAIT and WAITAOF?

WAIT numreplicas timeout waits for a specified number of replicas to acknowledge the offset of preceding writes on the same client connection, then returns the actual acknowledgment count. A result below the requested count does not roll back the earlier writes. The application must handle a result that falls short of its success criterion.18

WAITAOF numlocal numreplicas timeout waits for AOF fsync acknowledgments for preceding writes on the same connection. It returns local and replica acknowledgment counts separately. A local server with AOF disabled cannot satisfy a request for local fsync. Again, check the return value.18

Neither command can wait for the original connection’s writes if called on a different connection. Running redis-cli SET ... and a separate redis-cli WAIT ... hides that distinction. Which connection a pool lends out also matters.

Even a successful WAIT does not force a Sentinel or Cluster election to select only replicas that acknowledged that write. Without designing disk durability requirements and the next-primary selection rules too, do not describe this as “strong consistency.” Retrying an increment after a reply timeout is another remaining problem. The first attempt might have applied, so retries require a separate idempotency design.

Standalone servers and manual FAILOVER

If a server with no replication stops, there is no replacement primary candidate. Restarting it from RDB/AOF is different from a failover election.

If a primary and replica are connected without Sentinel or Cluster, a broken replication link does not automatically make the replica the writer. An operator can promote it with REPLICAOF NO ONE and reconfigure other nodes and clients, but this command has neither a monitor-majority vote nor fencing of the old primary.19

There is also a FAILOVER command initiated on a running standalone primary. Coordinated failover pauses writes, lets the target replica catch up to the offset, then hands over the role. It is not automatic recovery by sending a command to a dead primary. Do not mix the meanings of TO, TIMEOUT, FORCE and ABORT with Sentinel or CLUSTER FAILOVER options.19

Standalone FAILOVER ... FORCE can hand the role to the specified target even if it has not caught up within the configured timeout, creating a data-loss risk. REPLICAOF NO ONE is a different command that changes the role immediately. A role change does not automatically update application addresses, DNS or connection pools.

Sentinel SDOWN, ODOWN and elections are separate gates

Sentinel is an external monitor, not a server partitioning data keys. It monitors a primary and its replicas, discovers other Sentinels, and coordinates promotion when needed. Clients need to resolve the primary address by service name to establish a new connection.

SDOWN is my observation

sentinelCheckSubjectivelyDown sets SDOWN (subjectively down) from one Sentinel’s observations. Among other conditions, it checks whether valid replies have been absent for down-after-milliseconds. Valid PING replies include PONG, as well as LOADING and MASTERDOWN, which indicate that the server is alive. TCP connection status alone does not determine this.20

src/sentinel.c L4576-L4602
/* Update the SDOWN flag. We believe the instance is SDOWN if:
*
* 1) It is not replying.
* 2) We believe it is a master, it reports to be a slave for enough time
* to meet the down_after_period, plus enough time to get two times
* INFO report from the instance. */
if (elapsed > ri->down_after_period ||
(ri->flags & SRI_MASTER &&
ri->role_reported == SRI_SLAVE &&
mstime() - ri->role_reported_time >
(ri->down_after_period+sentinel_info_period*2)) ||
(ri->flags & SRI_MASTER_REBOOT &&
mstime()-ri->master_reboot_since_time > ri->master_reboot_down_after_period))
{
/* Is subjectively down */
if ((ri->flags & SRI_S_DOWN) == 0) {
sentinelEvent(LL_WARNING,"+sdown",ri,"%@");
ri->s_down_since_time = mstime();
ri->flags |= SRI_S_DOWN;
}
} else {
/* Is subjectively up */
if (ri->flags & SRI_S_DOWN) {
sentinelEvent(LL_WARNING,"-sdown",ri,"%@");
ri->flags &= ~(SRI_S_DOWN|SRI_SCRIPT_KILL_SENT);
}
}

There are three conditions: elapsed since the last valid reply exceeds down_after_period, the primary has been reporting itself as a replica for longer than down_after_period+sentinel_info_period*2, or a rebooted primary has not recovered within master_reboot_down_after_period. Any of them emits +sdown and sets SRI_S_DOWN.

This assessment mainly means “I cannot use this server normally.” The Sentinel itself might be isolated, or only its network path might be broken. SDOWN flags can apply to replicas and other Sentinels too, not only the primary.

ODOWN meets the detection quorum

When a primary is SDOWN, Sentinel asks other monitors for their observations with SENTINEL is-master-down-by-addr. sentinelCheckObjectivelyDown counts its own and other monitors’ down reports, setting ODOWN (objectively down) when they reach the configured quorum. This means neither that all monitors agree nor that they have reached agreement on data.21

src/sentinel.c L4605-L4628
/* Is this instance down according to the configured quorum?
*
* Note that ODOWN is a weak quorum, it only means that enough Sentinels
* reported in a given time range that the instance was not reachable.
* However messages can be delayed so there are no strong guarantees about
* N instances agreeing at the same time about the down state. */
void sentinelCheckObjectivelyDown(sentinelRedisInstance *master) {
dictIterator *di;
dictEntry *de;
unsigned int quorum = 0, odown = 0;
if (master->flags & SRI_S_DOWN) {
/* Is down for enough sentinels? */
quorum = 1; /* the current sentinel. */
/* Count all the other sentinels. */
di = dictGetIterator(master->sentinels);
while((de = dictNext(di)) != NULL) {
sentinelRedisInstance *ri = dictGetVal(de);
if (ri->flags & SRI_MASTER_DOWN) quorum++;
}
dictReleaseIterator(di);
if (quorum >= master->quorum) odown = 1;
}

quorum = 1 is this Sentinel’s own vote, and each other Sentinel with SRI_MASTER_DOWN set adds one. If the total reaches the configured quorum, the primary is ODOWN. The comment calls this a “weak quorum” because the votes are recent replies counted together, not an agreement reached at one instant.

Promotion also requires a majority of known monitors

Allowing a Sentinel that observes ODOWN to promote any replica by itself could produce simultaneous role changes in two places. An election therefore chooses a leader for each epoch. sentinelVoteLeader votes for an epoch, and sentinelGetLeader checks that the leader meets both an absolute majority of known Sentinels and the configured quorum.22

src/sentinel.c L4843-L4862
/* Count this Sentinel vote:
* if this Sentinel did not voted yet, either vote for the most
* common voted sentinel, or for itself if no vote exists at all. */
if (winner)
myvote = sentinelVoteLeader(master,epoch,winner,&leader_epoch);
else
myvote = sentinelVoteLeader(master,epoch,sentinel.myid,&leader_epoch);
if (myvote && leader_epoch == epoch) {
uint64_t votes = sentinelLeaderIncr(counters,myvote);
if (votes > max_votes) {
max_votes = votes;
winner = myvote;
}
}
voters_quorum = voters/2+1;
if (winner && (max_votes < voters_quorum || max_votes < master->quorum))
winner = NULL;

voters_quorum = voters/2+1 is the majority. Even the most-voted candidate is rejected (winner = NULL) if max_votes is below the majority or below the configured quorum. So with five Sentinels and quorum 2, starting a failover still takes three votes.

Quorum is the failure-detection threshold; elections add the majority condition. The numbers below are quorum arithmetic examples, not deployment measurements. The monitor count includes the Sentinel itself and counts Sentinels known for the same primary.

Why can ODOWN still block promotion?

Known Sentinels3
Down reports1
Leader votes0
DecisionSDOWN

My observation

Only S1 considers the primary down. This is below quorum.

An illustrative election with quorum fixed at 2. Detection quorum and leader election conditions are separate; actual timeouts and message retransmissions are omitted.
All snapshots (also available without JavaScript)

3 monitors

  1. My observation

    Known Sentinels: 3 · Down reports: 1 · Leader votes: 0 · Decision: SDOWN

    Only S1 considers the primary down. This is below quorum.

  2. S2 reports down too

    Known Sentinels: 3 · Down reports: 2 · Leader votes: 0 · Decision: ODOWN

    Two reports, including its own, produce ODOWN. Those reports are not themselves leader votes.

  3. Leader votes in one epoch

    Known Sentinels: 3 · Down reports: 2 · Leader votes: 2 · Decision: Election possible

    Two votes meet both the absolute majority of 3 and quorum=2.

5 monitors

  1. My observation

    Known Sentinels: 5 · Down reports: 1 · Leader votes: 0 · Decision: SDOWN

    Only S1 considers the primary down.

  2. S2 reports down too

    Known Sentinels: 5 · Down reports: 2 · Leader votes: 0 · Decision: ODOWN

    With quorum=2, this can produce ODOWN.

  3. Only 2 votes

    Known Sentinels: 5 · Down reports: 2 · Leader votes: 2 · Decision: No promotion authorization

    An absolute majority of the 5 known monitors is 3. Two votes cannot elect a leader.

  4. 3 votes for one leader

    Known Sentinels: 5 · Down reports: 2 · Leader votes: 3 · Decision: Election possible

    Election requires both majority and quorum within the same epoch.

QuizDoes lowering quorum restore availability?

Choose an answer to see the explanation.

0 of 1 right

  1. There are 5 known Sentinels and quorum=2. A partition leaves only 2 able to communicate with each other. Does ODOWN authorize automatic promotion?

Work remains after choosing the leader

The state sequence in sentinelFailoverStateMachine shows that promotion does not finish with one command’s return value.23

StateWhat the code waits for
WAIT_STARTLeader election and start conditions
SELECT_SLAVESelection of a replica for promotion
SEND_SLAVEOF_NOONESending the target a role-change command equivalent to REPLICAOF NO ONE
WAIT_PROMOTIONConfirmation of the primary role in the target’s INFO
RECONF_SLAVESConnecting other replicas to the new primary
UPDATE_CONFIGUpdating the monitored address and configuration to the new primary

Candidate selection also has two stages. First, eligibility checks filter candidates using SDOWN/ODOWN, long-disconnected links, INFO freshness, time disconnected from the primary, replica-priority=0 and other conditions. Remaining candidates are then sorted by lower priority, higher replication offset, then run ID. The newest offset is not unconditionally the first criterion.24

Role changes after leader election

Sentinel leaderElected
Candidate R1replica
Other replicasFollow old primary

WAIT_START

Elected leader in the same epoch, with start conditions satisfied.

Edited state playback of the successful path. The candidate is assumed to have passed eligibility checks; the text covers timeouts, reelections and reconfiguration retries.
All snapshots (also available without JavaScript)

Promotion and reconfiguration

  1. WAIT_START

    Sentinel leader: Elected · Candidate R1: replica · Other replicas: Follow old primary

    Elected leader in the same epoch, with start conditions satisfied.

  2. SELECT_SLAVE

    Sentinel leader: R1 selected · Candidate R1: Selected · Other replicas: Follow old primary

    Select R1 among eligible candidates by priority, offset and run ID.

  3. SEND_SLAVEOF_NOONE

    Sentinel leader: Command sent · Candidate R1: Promotion requested · Other replicas: Follow old primary

    Send R1 the role-change command. INFO confirmation has not happened yet.

  4. WAIT_PROMOTION

    Sentinel leader: INFO confirmed · Candidate R1: primary · Other replicas: Follow old primary

    Confirm R1's primary role through INFO.

  5. RECONF_SLAVES

    Sentinel leader: Reconfigure · Candidate R1: primary · Other replicas: Sync to R1

    Connect other replicas to R1 within the parallel-syncs limit.

  6. UPDATE_CONFIG

    Sentinel leader: Address updated · Candidate R1: primary · Other replicas: Follow R1

    Update the service name's primary address. Applications must resolve it and reconnect.

Failure to confirm the role in WAIT_PROMOTION activates time limits and failure paths. parallel-syncs counts replicas being reconfigured to the new primary at once, not leader votes. “The election finished” and “all replicas reconnected” are not the same timestamp.

Sentinel configuration and network partitions

Monitoring starts with sentinel monitor <name> <ip> <port> <quorum> in the configuration file. There is no universal deployment default to substitute for quorum. Sentinel must be able to observe and reconfigure the advertised address. Advertising unreachable addresses behind NAT or in containers can make monitoring and client reconnection point to different places.

SettingCode defaultOperational question
down-after-milliseconds30000 msHow do you balance detection delay against treating a healthy server’s temporary delay as failure?
failover-timeout180000 msHow do you operate time limits for election, promotion, reconfiguration and subsequent attempts?
parallel-syncs1How much read capacity can simultaneous replica resynchronization remove?
replica-priority100Which replica should be promoted first? 0 excludes it from automatic promotion candidates.
min-replicas-to-write0Can the primary accept writes without a specified number of healthy replicas?
min-replicas-max-lag10 secondsHow much time since the last ACK is allowed when counting healthy replicas?

These values come from Sentinel constants and the Redis configuration registry.25 failover-timeout does not promise that complete recovery finishes within that time. It controls retries and conditions for individual stages.

During a network partition, creating a new primary does not necessarily stop the old one immediately. Sentinel does not fence the old primary’s CPU or forcibly close existing application connections. If clients attached to the old address keep writing, those divergent writes can disappear after reconnection when that server becomes a replica of the new primary.26

min-replicas-to-write and min-replicas-max-lag can reduce this window. The primary checks the number of healthy replicas using recent ACKs and can reject writes with NOREPLICAS. This does not obtain synchronous replication agreement for every write, so configuring it does not eliminate the data-loss window.27

Sentinel also has TILT mode. When clock changes or long execution pauses make timer observations unreliable, it continues monitoring while suppressing risky actions. In this tag, sentinel_tilt_trigger defaults to 2000 ms and sentinel_tilt_period to SENTINEL_PING_PERIOD * 30, which is 30000 ms. Shortening detection thresholds alone does not solve host pauses and timer problems.28

Take care with automatically restarting a persistence-disabled primary with an empty dataset too. If it returns still acting as primary, replicas can follow that empty state. Treating a replica as a backup requires considering the original server’s restart policy too. Replication can follow deletions and empty states.

Cluster failure detection and voting

Cluster partitions the keyspace. CLUSTER_SLOTS in this source is 16384, and keyHashSlot reduces the CRC16 result into that range. Using the first nonempty hash tag puts {user:42}:profile and {user:42}:session in the same slot. A slot is a bucket assigning keys, not one key; its primary currently handles writes.29

Each data node exchanges state over a separate cluster bus. Sentinel processes do not conduct this election. By default, the bus port is the data port plus 10000, though cluster-port can specify it. A client’s working data-port connection does not prove that node-to-node bus connections work.30

PFAIL is a local suspicion that another node has not been reachable in time. FAIL aggregates failure reports from slot-owning voting primaries and requires a majority. Reports from primaries and the local node’s own observation, when it is a primary, are counted together. Adding replicas does not substitute for adding voting primaries.31

A replica of the failed primary attempts promotion through clusterHandleSlaveFailover. After eligibility checks, it spreads attempts using replica rank based on replication offset and a random delay, then requests votes in a new epoch. Offset rank makes more lagging replicas attempt later. It is not a procedure in which every node compares candidate datasets and restores the newest values.32

src/cluster.c L4344-L4363
/* If the previous failover attempt timeout and the retry time has
* elapsed, we can setup a new one. */
if (auth_age > auth_retry_time) {
server.cluster->failover_auth_time = mstime() +
500 + /* Fixed delay of 500 milliseconds, let FAIL msg propagate. */
random() % 500; /* Random delay between 0 and 500 milliseconds. */
server.cluster->failover_auth_count = 0;
server.cluster->failover_auth_sent = 0;
server.cluster->failover_auth_rank = clusterGetSlaveRank();
/* We add another delay that is proportional to the slave rank.
* Specifically 1 second * rank. This way slaves that have a probably
* less updated replication offset, are penalized. */
server.cluster->failover_auth_time +=
server.cluster->failover_auth_rank * 1000;
/* However if this is a manual failover, no delay is needed. */
if (server.cluster->mf_end) {
server.cluster->failover_auth_time = mstime();
server.cluster->failover_auth_rank = 0;
clusterDoBeforeSleep(CLUSTER_TODO_HANDLE_FAILOVER);
}

The election starts 500 ms plus a random 0 to 499 ms from now, then one more second per rank. clusterGetSlaveRank (L4142-L4157) computes rank as the number of failover-capable sibling replicas with a larger repl_offset, so the most up-to-date replica asks for votes first. A manual failover (mf_end) removes the delay.

In clusterSendFailoverAuthIfNeeded, a voting primary checks its own role, whether it already voted in the epoch, the target primary’s FAIL state, slot config epochs and other conditions. A candidate that gathers ACKs from a majority of voting primaries promotes itself and takes over the slots. currentEpoch numbers election progress; configEpoch establishes precedence between slot-ownership information. Neither is a key-value version number.32

src/cluster.c L4039-L4083
if (nodeIsSlave(myself) || myself->numslots == 0) return;
/* Request epoch must be >= our currentEpoch.
* Note that it is impossible for it to actually be greater since
* our currentEpoch was updated as a side effect of receiving this
* request, if the request epoch was greater. */
if (requestCurrentEpoch < server.cluster->currentEpoch) {
/* log omitted */
return;
}
/* I already voted for this epoch? Return ASAP. */
if (server.cluster->lastVoteEpoch == server.cluster->currentEpoch) {
/* log omitted */
return;
}
/* Node must be a slave and its master down.
* The master can be non failing if the request is flagged
* with CLUSTERMSG_FLAG0_FORCEACK (manual failover). */
if (nodeIsMaster(node) || master == NULL ||
(!nodeFailed(master) && !force_ack))
{
/* log omitted */
return;
}

These are the early checks. The voter must be a primary that owns slots, and a request whose epoch is below the voter’s currentEpoch is refused. A node that already voted in this epoch (lastVoteEpoch == currentEpoch) does not vote again, and the request is refused unless the requester’s primary is seen as FAIL (or force_ack is set for a manual failover).

src/cluster.c L4085-L4125
/* We did not voted for a slave about this master for two
* times the node timeout. This is not strictly needed for correctness
* of the algorithm but makes the base case more linear. */
if (mstime() - node->slaveof->voted_time < server.cluster_node_timeout * 2)
{
/* log omitted */
return;
}
/* The slave requesting the vote must have a configEpoch for the claimed
* slots that is >= the one of the masters currently serving the same
* slots in the current configuration. */
for (j = 0; j < CLUSTER_SLOTS; j++) {
if (bitmapTestBit(claimed_slots, j) == 0) continue;
if (isSlotUnclaimed(j) ||
server.cluster->slots[j]->configEpoch <= requestConfigEpoch)
{
continue;
}
/* If we reached this point we found a slot that in our current slots
* is served by a master with a greater configEpoch than the one claimed
* by the slave requesting our vote. Refuse to vote for this slave. */
/* log omitted */
return;
}
/* We can vote for this slave. */
server.cluster->lastVoteEpoch = server.cluster->currentEpoch;
node->slaveof->voted_time = mstime();
clusterDoBeforeSleep(CLUSTER_TODO_SAVE_CONFIG|CLUSTER_TODO_FSYNC_CONFIG);
clusterSendFailoverAuth(node);

A voter does not vote again for a replica of the same primary within node_timeout*2. If any slot the request claims has a known owner with a higher configEpoch than the request, the vote is refused. Once every check passes it records lastVoteEpoch, schedules a config save and fsync for beforeSleep, and calls clusterSendFailoverAuth. That call only queues the message on the link; the write handler sends it (L3530-L3535), and that handler runs after clusterBeforeSleep in beforeSleep (server.c L1663) has fsynced the config. So lastVoteEpoch is on disk before the vote leaves the node, and a restarted node cannot vote twice in one epoch.

Local observation: PFAIL Failure reports from primaries Report majority: FAIL Replica: eligibility / rank / new epoch Election ACKs from voting primaries Promotion and slot handover Advertise new configEpoch

A cluster-node-timeout of 15000 ms does not mean detection, voting, promotion and client reconnection finish exactly then. Message transfer, election delays, retries and connection state also contribute. This value is a failure-assessment criterion in this tag, not a recovery-time SLA.33

Cluster manual promotion and availability settings

CLUSTER FAILOVER starts on a replica. The normal manual path coordinates with the existing primary, temporarily pauses writes, catches up to its offset, then holds an election. Even the initiating node differs from standalone FAILOVER, which is sent to the primary.34

CLUSTER FAILOVER FORCE skips coordination with the existing primary but still requires authorization from voting primaries. TAKEOVER skips the normal election too and performs promotion and ownership changes locally. The latter is a dangerous recovery tool for an operator controlling the partition and authority. Do not choose it just because it is “faster.”

SettingDefaultWhat it actually changes
cluster-enablednoWhether the server runs the Cluster protocol.
cluster-node-timeout15000 msTiming criteria for node connections, failure assessment and elections.
cluster-replica-validity-factor10Limits automatic promotion eligibility for replicas disconnected from their primary for a long time.
cluster-require-full-coverageyesCan place the entire keyspace service in a failed state if a slot is unassigned or its owner is in FAIL.
cluster-allow-reads-when-downnoChanges which reads are allowed when Cluster is down. It does not create write consensus or freshness.
cluster-replica-no-failovernoSuppresses this replica’s participation in automatic failover.
cluster-migration-barrier1Number of healthy replicas to leave with the existing primary when a replica moves to a primary that has none.
cluster-allow-replica-migrationyesAllows replica relocation, distinct from migrating client keys between slots.

Defaults are registered in config.c.33 Replica validity is not determined solely by multiplying factor and timeout. This code’s eligibility criterion also adds the replication PING period. Factor 0 disables excluding long-disconnected replicas by that criterion; it does not guarantee fresh data.

cluster-require-full-coverage no allows serving remaining slots when some are unavailable. It does not enable continued writes on the side that has lost a majority of voting primaries. The majority-reachability check in clusterUpdateState remains separate.35

Replica reads using READONLY require a separate understanding too. This connection state permits reading from a replica for slots owned by its primary. Asynchronous replication does not automatically satisfy read-after-write. Selecting the next primary, choosing a read path and retrying application requests are separate designs.

Slot migration changes ownership and data separately

Reducing “move a slot from A to B” to “change A’s slot number to B” cannot explain routing during migration. First put B in IMPORTING A and A in MIGRATING B. A is still the official slot owner. After moving the data, finalize ownership with SETSLOT ... NODE B.36

In this state, A keeps handling existing keys. A request for a missing key can receive ASK, meaning “try B for this one command.” On B, send ASKING and the command over the same connection. ASK does not mean permanently updating the slot map.

MOVED, by contrast, reports the current slot owner. The client can retry at that address and update its slot map too. redis-cli -c is convenient in ordinary use, but when observing ASK and MOVED themselves as in the reproduction below, its automatic resending can hide those responses.

Request during migrationSource branch
Read an existing key on AA handles it.
Read a missing key on AMay return ASK pointing to B.
Read on B without ASKINGMay return MOVED pointing to current owner A.
Read on B after ASKINGB accepts the command for that importing slot.
Only some keys of a same-slot multi-key command exist on AMay return TRYAGAIN because it cannot split execution of one command.
Ordinary multi-key command spanning different slotsCROSSSLOT. Migration state does not turn it into one transaction.

Using the same hash tag does not guarantee that multi-key commands succeed during migration either. Keys can share a slot while temporarily residing on different nodes. getNodeByQuery counts missing keys and rejects such commands. TRYAGAIN retries need limits and backoff too.36

src/cluster.c L7508-L7540
/* MIGRATE always works in the context of the local node if the slot
* is open (migrating or importing state). We need to be able to freely
* move keys among instances in this case. */
if ((migrating_slot || importing_slot) && cmd->proc == migrateCommand)
return myself;
/* If we don't have all the keys and we are migrating the slot, send
* an ASK redirection or TRYAGAIN. */
if (migrating_slot && missing_keys) {
/* If we have keys but we don't have all keys, we return TRYAGAIN */
if (existing_keys) {
if (error_code) *error_code = CLUSTER_REDIR_UNSTABLE;
return NULL;
} else {
if (error_code) *error_code = CLUSTER_REDIR_ASK;
return server.cluster->migrating_slots_to[slot];
}
}
/* If we are receiving the slot, and the client correctly flagged the
* request as "ASKING", we can serve the request. However if the request
* involves multiple keys and we don't have them all, the only option is
* to send a TRYAGAIN error. */
if (importing_slot &&
(c->flags & CLIENT_ASKING || cmd_flags & CMD_ASKING))
{
if (multiple_keys && missing_keys) {
if (error_code) *error_code = CLUSTER_REDIR_UNSTABLE;
return NULL;
} else {
return myself;
}
}

MIGRATE itself runs locally while the slot is open. On the migrating side, if only some keys remain the result is CLUSTER_REDIR_UNSTABLE (the client sees -TRYAGAIN); if none remain it returns -ASK pointing at migrating_slots_to[slot]. The importing side serves only requests flagged with ASKING, and a multi-key request with missing keys also gets TRYAGAIN.

What MIGRATE does

migrateCommand connects to the destination and prepares AUTH/SELECT as needed. It serializes key values in RDB format and sends RESTORE with the remaining TTL. In Cluster mode it uses RESTORE-ASKING to load into an importing destination. It deletes the source only after the destination returns success. COPY keeps the source; REPLACE allows overwriting an existing destination key.37

Value copying and slot-ownership changes are separate. One MIGRATE is not proof that every key in a slot has moved. The destination’s RESTORE and the source’s DEL also follow each node’s own replication and persistence paths.

src/cluster.c L7151-L7185
for (j = 0; j < num_keys; j++) {
if (connSyncReadLine(cs->conn, buf2, sizeof(buf2), timeout) <= 0) {
socket_error = 1;
break;
}
if ((password && buf0[0] == '-') ||
(select && buf1[0] == '-') ||
buf2[0] == '-')
{
/* On error assume that last_dbid is no longer valid. */
/* reply with the first error only */
} else {
if (!copy) {
/* No COPY option: remove the local key, signal the change. */
dbDelete(c->db,kv[j]);
signalModifiedKey(c,c->db,kv[j]);
notifyKeyspaceEvent(NOTIFY_GENERIC,"del",kv[j],c->db->id);
server.dirty++;
/* Populate the argument vector to replace the old one. */
newargv[del_idx++] = kv[j];
incrRefCount(kv[j]);
}
}
}

Each time the target answers OK to a key’s RESTORE, the source deletes that key with dbDelete (unless COPY was given) and collects it in newargv. A key that got an error is not deleted, so it stays on the source.

src/cluster.c L7187-L7215
/* On socket error, if we want to retry, do it now before rewriting the
* command vector. We only retry if we are sure nothing was processed
* and we failed to read the first reply (j == 0 test). */
if (!error_from_target && socket_error && j == 0 && may_retry &&
errno != ETIMEDOUT)
{
goto socket_err; /* A retry is guaranteed because of tested conditions.*/
}
/* On socket errors, close the migration socket now that we still have
* the original host/port in the ARGV. Later the original command may be
* rewritten to DEL and will be too later. */
if (socket_error) migrateCloseSocket(c->argv[1],c->argv[2]);
if (!copy) {
/* Translate MIGRATE as DEL for replication/AOF. Note that we do
* this only for the keys for which we received an acknowledgement
* from the receiving Redis server, by using the del_idx index. */
if (del_idx > 1) {
newargv[0] = createStringObject("DEL",3);
/* Note that the following call takes ownership of newargv. */
replaceClientCommandVector(c,del_idx,newargv);
argv_rewritten = 1;
} else {
/* No key transfer acknowledged, no need to rewrite as DEL. */
zfree(newargv);
}
newargv = NULL; /* Make it safe to call zfree() on it in the future. */
}

It retries only on a socket error (not a target error), when no reply has been read yet (j == 0), on the first attempt, and not on a timeout. Keys are deleted only after an OK is read, so j == 0 means nothing was deleted and resending is safe. Finally the command is rewritten as DEL over the deleted keys only and propagated to replicas and the AOF.

The key moves, but A still owns the slot

Official ownerA
Key on AV
Key on BAbsent
RoutingA handles it

Start

A holds the slot and key.

Successful migration of one key in a slot. Value V and node names are illustrative; replication ACKs and repeated migrations for the whole slot are omitted.
All snapshots (also available without JavaScript)

IMPORTING → MIGRATING → NODE

  1. Start

    Official owner: A · Key on A: V · Key on B: Absent · Routing: A handles it

    A holds the slot and key.

  2. Set migration states

    Official owner: A · Key on A: V · Key on B: Absent · Routing: Existing key: A

    B is IMPORTING and A is MIGRATING. Ownership is unchanged.

  3. RESTORE succeeds on B

    Official owner: A · Key on A: V · Key on B: V · Routing: Owner is A

    B has received the value. Source deletion has not happened yet.

  4. A receives success

    Official owner: A · Key on A: Absent · Key on B: V · Routing: A: ASK B

    On the successful path without COPY, A deletes the source.

  5. Check the entire slot

    Official owner: A · Key on A: Absent · Key on B: V · Routing: B via ASKING

    Check that A has no remaining keys in this slot. The diagram shows only one key.

  6. Finalize and propagate ownership

    Official owner: B · Key on A: Absent · Key on B: V · Routing: MOVED B

    B becomes the slot owner. Other nodes and clients learn the new map.

When the network disconnects during MIGRATE

The most dangerous point lies between “the destination wrote it” and “the source received the success reply.” If the destination finishes RESTORE but the reply is lost, A cannot know whether it can delete the source. This source can leave unconfirmed keys on the source node. A timeout is not evidence that migration did nothing.37

One lost reply can leave two copies

AV
NetworkConnected
BAbsent

Source

Only A holds V.

A possible sequence separating MIGRATE's RESTORE success from reply receipt. This does not simulate failover; the duplicate copies illustrate a lost success reply.
All snapshots (also available without JavaScript)

Reply arrives

  1. Source

    A: V · Network: Connected · B: Absent

    Only A holds V.

  2. Execute RESTORE

    A: V · Network: Sending OK · B: V

    B stores V and sends a success reply.

  3. Receive OK

    A: Absent · Network: OK arrived · B: V

    A deletes the source after confirmation.

Reply lost

  1. Source

    A: V · Network: Connected · B: Absent

    Only A holds V.

  2. Execute RESTORE

    A: V · Network: Sending OK · B: V

    B already holds V.

  3. No reply received

    A: V remains · Network: Possible IOERR · B: V remains

    A cannot confirm success. Do not conclude that the destination lacks the data.

  4. Choose recovery

    A: Inspection needed · Network: Reconnect · B: Inspection needed

    Check slot state, both copies and new writes before deciding how to resume. Do not automatically delete or blindly REPLACE.

Distinguish a single-key migration from moving multiple keys with KEYS. While processing multiple RESTORE replies, partial progress is possible: some keys have been confirmed and deleted, while others remain on the source. One failure is not a rollback of the entire slot.

What to check at each disconnection point

Disconnection pointPossible stateFirst checks
Destination connection or AUTH failsOnly the source may remain.Exact error and destination permissions
RESTORE returns an error at the destinationThat source key remains.BUSYKEY, OOM, destination role and importing state
Reply lost after RESTORE succeedsValues may remain on both sides.Both values, TTLs, recent writes, owner and migration states
Destination fails after source deletionIts replica might not have received the value yet.Destination replication progress and persistence, slot recovery state
Disconnection during owner propagation after all keys moveNodes can temporarily disagree on the owner.Each node’s slot map and config epoch, remaining importing/migrating markers

The last two rows explain why a MIGRATE success reply is not a distributed transaction commit. Adding WAIT or WAITAOF at the destination first requires resolving their same-connection offset conditions. Calling WAIT on the source connection that ran MIGRATE does not acknowledge RESTORE on the destination’s replicas.

Clients can still write during recovery. Two duplicates that matched at the start are not guaranteed to remain equal. Deleting the source without comparing TTLs, or repeatedly running MIGRATE ... REPLACE, can overwrite newer values or change their lifetimes.

Cluster’s --cluster fix does not merge two values according to business meaning either. Before changing anything, preserve each node’s CLUSTER NODES, CLUSTER SLOTS, CLUSTER COUNTKEYSINSLOT, required key values and TTLs, and replication state; control the write path. If the keyspace contains personal information, protect the diagnostic data too.

Expiration and eviction delete for different reasons

Expiration ends a key’s valid lifetime; eviction removes a value under memory pressure. Both make keys disappear and produce cache misses, but the operational metrics and remedies differ.

expireIfNeeded in db.c checks expiration on lookup paths. activeExpireCycle in expire.c incrementally scans TTL-bearing dicts and cleans up expired keys. This tag also uses a cursor based on dictScan. Do not copy the older explanation that it “picks a few random keys each time” unchanged.38

active-expire-effort defaults to 1 and ranges from 1 to 10. Increasing it changes the amount inspected, tolerated stale ratio and CPU time budget. hz=10 and dynamic-hz=yes do not mean that key TTLs are accurate only in 100 ms increments. Logical expiration decisions and actual memory cleanup cycles are separate.39

Primary deletions propagate through the replication stream. Replicas must follow expiration and deletion from their replication source, so an ordinary replica does not independently and unconditionally delete its dataset. That does not mean user reads always return expired keys. expireIfNeeded can report a key as logically expired to its caller.38

maxmemory is not a process RSS ceiling

performEvictions uses getMaxmemoryState to evaluate memory for eviction. freeMemoryGetNotCountedMemory subtracts AOF buffers and part of the replication buffers. It does not unconditionally exclude the entire portion corresponding to the backlog target size too. The source separately calculates the replication-buffer portion exceeding a baseline that accounts for backlog size and block overhead.40

This calculation avoids a cycle in which DEL propagation grows replication/AOF buffers, which then causes more keys to be deleted. That is why mem_not_counted_for_evict in INFO memory matters. Host capacity planning must separately account for allocator slack, fork copy-on-write and other RSS costs.

PolicyCandidates and selection
noevictionDoes not evict keys. Commands subject to rejection under OOM fail.
allkeys-lru / volatile-lruCompares recent access information in samples of all keys or TTL-bearing keys.
allkeys-lfu / volatile-lfuCompares decaying frequency information within the same candidate scopes.
allkeys-random / volatile-randomSelects random candidates within the corresponding scope.
volatile-ttlPrefers sooner-expiring candidates among TTL-bearing keys.

maxmemory defaults to 0 and the policy to noeviction. With volatile-*, no TTL-bearing keys can mean no eviction candidates. “I set a memory limit, so Redis automatically deletes arbitrary keys” is not the default behavior.39

LRU does not maintain a perfect access-order list of all keys. It approximates ordering with samples, defaulting to maxmemory-samples=5, and retains better candidates in an eviction pool. maxmemory-eviction-tenacity=10 affects the eviction time budget; it does not mean 10% CPU.40

src/evict.c L168-L187
/* Calculate the idle time according to the policy. This is called
* idle just because the code initially handled LRU, but is in fact
* just a score where an higher score means better candidate. */
if (server.maxmemory_policy & MAXMEMORY_FLAG_LRU) {
idle = estimateObjectIdleTime(o);
} else if (server.maxmemory_policy & MAXMEMORY_FLAG_LFU) {
/* When we use an LRU policy, we sort the keys by idle time
* so that we expire keys starting from greater idle time.
* However when the policy is an LFU one, we have a frequency
* estimation, and we want to evict keys with lower frequency
* first. So inside the pool we put objects using the inverted
* frequency subtracting the actual frequency to the maximum
* frequency of 255. */
idle = 255-LFUDecrAndReturn(o);
} else if (server.maxmemory_policy == MAXMEMORY_VOLATILE_TTL) {
/* In this case the sooner the expire the better. */
idle = ULLONG_MAX - (long)dictGetVal(de);
} else {
serverPanic("Unknown eviction policy in evictionPoolPopulate()");
}

The variable is named idle, but it is a policy-specific score where higher means evicted sooner. LRU uses idle time, LFU uses 255 - frequency, and volatile-ttl uses ULLONG_MAX - expire time, so keys expiring sooner score higher.

LFU is not an exact request counter. It uses an 8-bit logarithmic counter and 16-bit minute-based decay information in the object field. The actual LFUDecrAndReturn subtracts the number of elapsed decay periods from the counter. Copying only an older nearby comment saying it “always halves” would contradict the implementation. Defaults lfu-log-factor=10 and lfu-decay-time=1 adjust this probabilistic increment and decay.41

src/evict.c L297-L326
/* Logarithmically increment a counter. The greater is the current counter value
* the less likely is that it gets really incremented. Saturate it at 255. */
uint8_t LFULogIncr(uint8_t counter) {
if (counter == 255) return 255;
double r = (double)rand()/RAND_MAX;
double baseval = counter - LFU_INIT_VAL;
if (baseval < 0) baseval = 0;
double p = 1.0/(baseval*server.lfu_log_factor+1);
if (r < p) counter++;
return counter;
}
/* snip */
unsigned long LFUDecrAndReturn(robj *o) {
unsigned long ldt = o->lru >> 8;
unsigned long counter = o->lru & 255;
unsigned long num_periods = server.lfu_decay_time ? LFUTimeElapsed(ldt) / server.lfu_decay_time : 0;
if (num_periods)
counter = (num_periods > counter) ? 0 : counter - num_periods;
return counter;
}

LFULogIncr bumps the counter only with probability p = 1/((counter - 5) * lfu-log-factor + 1) (5 is LFU_INIT_VAL, server.h L3411). With the default factor 10, the table in redis.conf L2168-L2180 shows 100 hits giving 10 and 1M hits giving 255. LFUDecrAndReturn splits the 24-bit lru field into a 16-bit minute timestamp and an 8-bit counter, and subtracts 1 for every lfu-decay-time minutes elapsed.

With replica-ignore-maxmemory=yes by default, replicas suppress independent eviction while following the primary’s dataset. Replica memory and host limits still need attention. After promotion, the server applies memory policy as a primary, so check headroom immediately after the role change too.39

RDB, AOF and a restarted server

RDB is a point-in-time snapshot. rdbSaveBackground saves through a child process, while the parent can keep handling requests. Fork and copy-on-write have costs; “background” does not mean “no effect on the main server.”5

AOF records subsequent commands. The write buffer, writing to the OS and completing fsync are separate events. appendonly defaults to no; when AOF is enabled, the default fsync policy is everysec. always synchronizes more frequently, with different latency and storage-error handling.42

This version’s AOF rewrite uses multi-part AOF, managing a base file, subsequent incremental files and a manifest together. Do not maintain it by indiscriminately deleting an old file. Restoration requires understanding the relationship between the manifest and its file set.5

The normal operational target of everysec differs from a guarantee covering OS pauses and storage failures. Without examining the failure type and storage behavior, do not promise that “exactly one second is lost.” Read WAIT, WAITAOF, AOF policy and replica selection as separate completion conditions.

Distinguish a cache from a source of record too. If data can be rebuilt from the original database, misses and reheating load are the concern. If Redis holds the only copy, acknowledgment and recovery policies define the data-loss contract. Calling it a cache does not create an original copy to recover from.

Pub/Sub does not acknowledge replication or completed work

pubsubPublishMessageInternal looks up the channel’s subscribers and places the message in each client’s reply buffer. Ordinary Pub/Sub also checks the pattern list. It is not a queue retaining message history for disconnected subscribers or replaying it after reconnection.43

The integer reply from PUBLISH concerns local subscription deliveries made by the server. It does not confirm that a consumer ran its code, completed work or persisted anything to disk. Overlapping channel and pattern subscriptions can give one connection multiple deliveries, so this is not a unique-user count.

Ordinary Cluster Pub/Sub propagates messages over the cluster bus. Sharded Pub/Sub commands SPUBLISH and SSUBSCRIBE assign channels to slots and propagate within that shard. The shard branch in pubsubPublishMessageInternal does not handle pattern subscriptions. A shard includes its primary and replicas, not just one node.44

The code propagating ordinary PUBLISH through standalone replication does not make it a durable queue either. Ordinary PUBLISH does not store messages in AOF for per-subscriber replay. If delivery guarantees are required, consider Streams or an external queue together with retention, acknowledgment and reprocessing policies.

Slow subscribers can grow output buffers. client-output-buffer-limit pubsub 32mb 8mb 60 is the value in this tag’s configuration file. It specifies a hard limit, a soft limit and duration; exceeding limits can close the connection. The final 60 is seconds, not a message count.45

Reconnecting does not retrieve missed messages. First decide whether a lost notification can be repaired by a subsequent read or whether every event must be processed. Keyspace notifications use Pub/Sub too; do not treat them as a durable change log.

ACL checks commands, keys and channels together

This release includes security fixes for TLS pending-data handling, ACL key extraction and blocked-client handling. The implementation discussion is pinned to the corrected tag. Do not assess access control solely from older Redis behavior or current documentation.46

ACLCheckAllPerm passes the user, command and argument array to ACLCheckAllUserCommandPerm. Access is allowed if one selector satisfies the command and all required key and channel conditions. It does not assemble a new permission combination by taking GET permission from one selector and a key pattern from another.47

Key checks do not treat every argument as a key. Command key specs and the required extraction paths identify the keys actually accessed. Commands such as EVAL, with a key count in their arguments, and indirect accesses such as SORT need additional care. Arity and extraction validation are part of permission checks.

ACL expressionMeaning
on / offWhether the user is enabled
+get, -setAllowing and denying commands
+@read, -@allCommand categories
~cache:*Read/write key pattern
%R~cache:* / %W~cache:*Read or write key access pattern
&events:*Pub/Sub channel pattern, separate from key patterns
reset / clearselectorsHow to remove existing permissions and selectors

The default user is special. ACLCreateDefaultUser creates it with on, nopass, +@all, ~* and &*. This does not mean channel permissions are open by default for a newly restricted user. The default acl-pubsub-default is restrictive; inspect the actual server’s ACL and network configuration.48

Pattern authorization for PSUBSCRIBE differs from ordinary channel names too. ACLCheckChannelAgainstList compares the pattern-subscription argument literally with allowed patterns. Do not assume an arbitrary pattern makes the server automatically calculate a safe set of channels.47

Before changing production permissions, test allowed and denied cases with ACL DRYRUN, then verify on an actual authenticated connection. Use ACL LOG to diagnose denials. Runtime changes with ACL SETUSER, persistence to an ACL file through ACL SAVE, and rewriting the configuration file are separate. Verify that changes survive a restart.49

Sentinel authentication to data nodes, replica authentication to primaries, and ordinary application authentication also use different connections. Reusing a GET/SET application user can block failover even while the data is intact if INFO or role-change commands from the monitor are denied. Check the minimum permissions for each role against this tag’s Sentinel documentation and actual denial logs.

Reproduction and boundaries not verified here

The reproduction script uses Docker’s redis:7.2.16 and checks the server version first. It does not connect to the host’s Redis; it starts servers inside a dedicated container with a noncolliding name and removes the container on exit. This is not an exercise in copying failover commands onto production servers.

Download the Python script attached to this article and run it where Docker works. No additional Python packages are required. Inspect downloaded code before executing it.

Download the reproduction script
Run the isolated reproduction
python3 test-redis-internals.py --docker

This run asserts encoding boundaries and actual server replies, normal replication and role transitions, and slot routing. It does not prove the entire source-derived state machine under every possible schedule. Failure injection and wait limits in the test topology are reproduction parameters, not recommended operational defaults.

The checks that actually passed cover hash/set/zset element-count and byte-length boundaries, list growth and shrinkage, separation of authenticated ACL selectors, absence of Pub/Sub replay after reconnection, and same-connection WAIT and read-only replicas. I also verified replication of new writes after a standalone role handoff, Sentinel SDOWN, ODOWN, leader election and address changes, and Cluster PFAIL, FAIL and replica promotion. Slot-migration checks covered ASK, MOVED, TRYAGAIN, ASKING followed by GET, source deletion after successful MIGRATE, and preservation of both values after an actual BUSYKEY error.

I did not inject the loss of a successful RESTORE reply. Reproducing BUSYKEY does not count as reproducing a lost reply. WAITAOF, storage power loss and production-scale load were not checked in this run either.

A laptop experiment cannot guarantee every combination of network disconnection timing, storage power loss and simultaneous new writes on both sides of a partition. Those cases are explained through source branches and possible sequences in the article. Quantified failover recovery SLAs, production capacity and upper bounds on data loss are not results of this article.

Apply this to the next failure

QuizApply the mechanism to a different situation

Choose an answer to see the explanation.

0 of 5 right

  1. SET returned OK. The primary disconnected, and a replica that had not received the write was promoted. What can happen?

  2. What does CLUSTER FAILOVER FORCE skip?

  3. MIGRATE returned IOERR. Can you delete the source immediately?

  4. You ran MIGRATE on the source, then WAIT on the same connection. Did you wait for RESTORE on the destination's replicas too?

  5. PUBLISH returned a subscription-delivery count. Does this confirm completed consumer work?

Terms to recall

Click a card to flip it.

0 of 10 flipped

A map for reopening the source

When you see a setting that changes behavior, find the function reading it. Following a setting name into these functions lets you check the article’s explanations again.

QuestionFile and entry point
Why was the command rejected?server.c: processCommand
Who executes the actual command?server.c: call, networking.c: postprocessing of threaded reads
Why did a small value switch to a larger representation?t_hash.c, t_set.c, t_zset.c, t_list.c
Why did replication require full sync?replication.c: masterTryPartialResynchronization
Why did WAIT return too few acknowledgments?replication.c: waitCommand, processClientsWaitingReplicas
Why is there no election despite ODOWN?sentinel.c: sentinelGetLeader, sentinelFailoverStateMachine
Why was this replica chosen?sentinel.c: sentinelSelectSlave, compareSlavesForPromotion
Why are Cluster writes and promotion blocked?cluster.c: clusterUpdateState, clusterHandleSlaveFailover
Why did I receive ASK, MOVED or TRYAGAIN?cluster.c: getNodeByQuery
Which keys remain after MIGRATE fails?cluster.c: migrateCommand
Why does RSS exceed the memory limit?evict.c: getMaxmemoryState, freeMemoryGetNotCountedMemory
Why is delivery count not completion count?pubsub.c: pubsubPublishMessageInternal
Where are permission combinations checked?acl.c: ACLSelectorCheckCmd, ACLCheckAllUserCommandPerm

Reducing all of this to “Redis recovers automatically” erases where observations occur, who votes and which ACKs are awaited. Operational decisions need those boundaries. Recording whether you verified changed memory, replication history or slot ownership narrows what you need to inspect in the next failure.

Notes

  1. networking.c, input handling. ↩

  2. processCommand, call. ↩

  3. multiCommand, execCommand. ↩

  4. handleClientsWithPendingReadsUsingThreads, config.c, I/O settings. ↩

  5. rdbSaveBackground, aof.c, bio.c. ↩ ↩2 ↩3

  6. object.c, creation and encoding, sds.h. ↩ ↩2

  7. dictRehash. ↩

  8. zslInsert, spans and byte order, zslGetRank. ↩

  9. streamAppendItem, t_stream.c, groups and ACK. ↩

  10. listpack.c, format, lpInsert. ↩ ↩2

  11. hashTypeSet, setTypeCreate / setTypeAddAux. ↩

  12. t_list.c, bidirectional representation conversion. ↩

  13. replication.c. ↩

  14. masterTryPartialResynchronization. ↩

  15. replication.c, full sync setup, syncCommand. ↩

  16. config.c, replication bool settings, config.c, replication numeric settings. ↩

  17. replication.c, replication ID changes. ↩

  18. waitCommand, waitaofCommand. ↩ ↩2

  19. replicaofCommand, failoverCommand. ↩ ↩2

  20. sentinelCheckSubjectivelyDown. ↩

  21. sentinelCheckObjectivelyDown. ↩

  22. sentinelVoteLeader, sentinelGetLeader. ↩

  23. sentinel.c, failover state constants, sentinelFailoverStateMachine. ↩

  24. compareSlavesForPromotion, sentinelSelectSlave. ↩

  25. sentinel.c, default constants, sentinelHandleConfiguration. ↩

  26. sentinelCheckObjectivelyDown, sentinelGetLeader. ↩

  27. server.c, healthy replica check. ↩

  28. sentinelCheckTiltCondition, sentinel.c, TILT constants. ↩

  29. keyHashSlot, cluster.h, CLUSTER_SLOTS. ↩

  30. clusterProcessPacket, cluster.h, bus port offset. ↩

  31. around markNodeAsFailingIfNeeded, cluster.h, FAIL constants. ↩

  32. clusterSendFailoverAuthIfNeeded, clusterGetSlaveRank, clusterHandleSlaveFailover. ↩ ↩2

  33. config.c, Cluster defaults. ↩ ↩2

  34. CLUSTER FAILOVER handling, clusterHandleManualFailover, clusterBumpConfigEpochWithoutConsensus. ↩

  35. clusterUpdateState. ↩

  36. getNodeByQuery, clusterRedirectClient, CLUSTER SETSLOT. ↩ ↩2

  37. migrateCommand, restoreCommand, BUSYKEY. migrateCommand never raises BUSYKEY itself. The target’s restoreCommand raises it when the key already exists and REPLACE was not given, and MIGRATE passes that error back. ↩ ↩2

  38. activeExpireCycle, expireIfNeeded. ↩ ↩2

  39. config.c, memory settings, redis.conf, hz. ↩ ↩2 ↩3

  40. evict.c, memory accounting, performEvictions. ↩ ↩2

  41. LFULogIncr / LFUDecrAndReturn. ↩

  42. redis.conf, appendonly, aof.c, fsync. ↩

  43. pubsubPublishMessageInternal / publishCommand. ↩

  44. pubsub.c, sharded branch, cluster.c, clusterPropagatePublish. ↩

  45. redis.conf, output buffer limits. ↩

  46. 7.2.16 release. All implementation links in this article are pinned to commit 335554f18caf7bbf6b0ac2b3548133d750f00a1b. ↩

  47. ACLSelectorCheckCmd / ACLCheckAllUserCommandPerm. ↩ ↩2

  48. ACLCreateDefaultUser, config.c, acl-pubsub-default. ↩

  49. ACLSaveToFile, file persistence and startup handling, ACL DRYRUN. ↩

ko.mdx

단축키Keyboard

/ ⌘K
글 검색Search posts
t
밝은/어두운 테마Light or dark theme
l
한국어/영어, 읽던 자리 유지Korean or English, keeping your place
[ ]
이전/다음 절Previous or next section
?
이 목록This list

↑↓ 이동move↵ 열기openesc 닫기close