Files
clean-architecture-backend-…/docs/redis/operations.md
T
DongHyeonka 4e2f08a687 docs(redis): Redis SDK 운영 문서를 한국어로 옮긴다
문제: docs/redis 아래 살아 있는 문서 4개가 영어였다(language 예외).

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다.
support-matrix.md의 표 첫 칸(package·capability·토폴로지 이름)과 증거 칸의 테스트 클래스
이름은 RedisSupportMatrixTest가 그대로 읽으므로 바꾸지 않았다. 번역하며 고친 것:
- 「pinned to Lettuce 6.8.2」: build.gradle은 버전 없이 Boot BOM을 따른다. 숫자 대신
  BOM과 leaf gradle.lockfile을 가리킨다.
- 「five defects」 뒤 목록이 일곱 항목이라 「결함 일곱」으로 고쳤다.

위험·한계: 내용 감사는 하지 않았다.

검증: python3 scripts/check-docs.py에서 이 폴더 예외 줄 0. RedisSupportMatrixTest의 세
단언(package·capability가 첫 칸에 있음, 토폴로지 행이 있는 테스트 클래스를 댐)을 같은
규칙으로 문서에 돌려 보았다(빠진 것 0).
2026-11-07 17:29:57 +09:00

4.6 KiB

Redis SDK 운영

metric이 알려 줄 수 있는 것과 없는 것

모든 관측은 명령 계열, 배포 방식, 지연을 담는다. key, field, member, value는 담지 않는다. 값이 커서가 아니라, 호출자 데이터로 만든 metric 차원은 가짓수에 상한이 없고 대부분의 배포에서 dashboard에 tenant 식별자를 띄우기 때문이다.

그래서 metric으로 「어느 명령 계열이 느린가」와 「어느 것이 실패하나」에는 답할 수 있지만 「어느 key가 뜨거운가」에는 답할 수 없다. 앞의 질문에는 admin plane의 SLOWLOG 투영을, 뒤의 질문에는 특정 key에 대한 MEMORY USAGE를 쓴다.

경보를 걸 만한 실패

신호 뜻 할 일
RedisCommandRejectedException SDK가 보내기 전에 거부했다 호출자가 선언한 상한을 넘었다. 이유가 어느 것인지 이름을 댄다
RedisCrossSlotException 여러 key 명령이 slot을 넘는다 key들이 같은 hash tag를 가져야 한다
RedisAmbiguousExecutionException 쓰기가 적용됐을 수도, 아닐 수도 있다 맞춰 본다. SDK는 재시도하지 않는다
RedisCapabilityUnavailableException 서버에 그 기능이 없다 capability bean을 손으로 만들었거나 probe 결과가 바뀌었다
SentinelFailoverObserver.ambiguousWriteCount 승격 때문에 잃은 멱등이 아닌 쓰기 하나하나 맞춰 봐야 한다. 그 수가 일의 양이다
ClusterTopologyObserver.reshardingObserved ASK/TRYAGAIN을 봤다 slot 이동이 진행 중이다. 끝날 때까지 지연이 고르지 않다

SDK가 절대 대신해 주지 않는 것

  • 시간 초과 뒤 멱등이 아닌 쓰기를 재시도하기. ExecutionCertainty.AMBIGUOUS_FAILURE를 보고할 뿐 풀지 않는다.
  • slot을 넘는 여러 key 명령을 나눠서 따라가기. 대신 거부한다.
  • collection, stream, index 전체를 읽기. 모든 읽기는 상한을 선언한다.
  • 요청 시점에 Lua script나 function library를 불러오기. 둘 다 배포 작업이다.
  • 분류할 수 없는 명령 보내기.
  • 확인 응답을 받은 쓰기를 잃었다고 알려 주기. 아래를 본다. 애플리케이션 코드로 돌아갈 수 있는 한계가 아니다.

client가 볼 수 없는 쓰기 손실

primary가 될 수 있는 모든 Redis 노드에 이것을 둔다.

min-replicas-to-write 1
min-replicas-max-lag 1

이것이 없으면 Sentinel 승격이 확인 응답을 받은 쓰기를 조용히 없앤다. 이론이 아니라 잰 것이다. 7.4 lane의 LiveRedisSentinelPromotionTest에서 Sentinel은 replica를 승격하고 옛 primary를 11초 동안 내리지 않았다. client는 이미 교체된 primary에 연결된 채 썼고, +OK를 2,086번 받았다. 옛 primary가 다시 동기화할 때 그 쓰기는 모두 버려졌다. 실패한 명령은 정확히 하나였다.

client 쪽에서는 아무것도 이것을 알아챌 수 없다. 서버가 답했으니 driver는 성공을 기록했고, SDK는 CONFIRMED_SUCCESS를 기록했고, 호출자는 쓰기가 들어갔다고 들었다. 여기의 어떤 metric도 그것을 세지 않고, SentinelFailoverObserver도 셀 수 없고, 어떤 재시도 정책도 돕지 못한다. 반응할 실패가 없었다. 같은 승격을 두 번째로 돌렸을 때는 쓰기 만 육천 개, 예외 0개, 그리고 같은 조용한 손실이 나왔다.

두 설정을 두자 똑같은 승격에서 잃은 쓰기는 하나였고, 2,020개는 NOREPLICAS로 거부됐다. SDK는 그것을 호출자가 대응할 수 있는, 결과가 분명한 실패로 보고한다. 차이는 그것이 전부다. 볼 수 없는 데이터 대신 볼 수 있는 장애다.

남은 구간은 min-replicas-max-lag만큼이고 설정만으로는 닫을 수 없다. 어떤 경우에도 승격을 견뎌야 하는 쓰기는 그 뒤에 WAIT가 필요하고, replica까지 왕복하는 비용이 든다. 전역이 아니라 쓰기마다 정한다.

Blocking 작업

blocking pop과 blocking stream 읽기는 전용 connection lane에서 돈다. 그것이 가득 차면 보통 트래픽은 건강한데 blocking 호출만 시간 초과가 나는 증상이 보인다. lane이 제 일을 하는 것이지 결함이 아니다. blocking pool은 요청률이 아니라 동시 소비자 수에 맞춘다.

Pub/Sub

많아야 한 번(at-most-once)이다. 다시 연결한 구독자는 떠나 있던 동안 온 것을 놓치고, 다시 받을 길이 없다. 지속돼야 하는 업무 이벤트는 consumer group이 있는 stream에 둔다. 그것은 적어도 한 번(at-least-once)이므로 멱등한 소비자가 필요하다.