Redis 트러블슈팅 가이드

🏗 1. 시스템 개요

apps/socket은 다중 인스턴스 Socket.io 서버이며 Redis를 다음 목적으로 사용합니다.

• 분산 세션/상태: Room, Peer, Instance 메타데이터 영속화
• 크로스 인스턴스 브로드캐스트: @socket.io/redis-adapter로 pub/sub
• 다중 인스턴스 라우팅: 같은 room의 모든 peer를 동일 instance로 핀 (room owner)
• 인스턴스 생존성 추적: Heartbeat + Reaper 패턴
• 녹화 메타 복구: 재시작 후 진행 중 녹화 세션 복구

관련 클라이언트

3개의 ioredis 인스턴스가 동시 운영됩니다.

핵심 코드 위치

• apps/socket/src/redis/client.ts - 연결 초기화, heartbeat
• apps/socket/src/redis/room-store.ts - Room Hash CRUD
• apps/socket/src/redis/peer-store.ts - Peer Hash + 역 인덱스
• apps/socket/src/redis/reaper.ts - Dead instance 정리
• apps/socket/src/redis/reaper-scheduler.ts - Leader lease
• apps/socket/src/redis/settings-store.ts - 전역 설정
• apps/socket/src/sfu-config.ts - 환경 변수 로딩

🔌 2. 연결 설정 & 환경 변수

필수 환경 변수

연결 옵션 (ioredis)

{
  lazyConnect: true,
  maxRetriesPerRequest: 3,
  enableReadyCheck: true,
  enableOfflineQueue: false,  // disconnect 중 명령 큐 비활성
  tls: REDIS_TLS === "true" ? {} : undefined,
}

부팅 시 동작 (fail-fast)

1. REDIS_URL 없으면 → throw (부팅 실패)
2. main 클라이언트 connect
3. PING 보내고 5초 내 PONG 안 오면 → throw
4. pub/sub 클라이언트 connect (adapter 활성화 시)
5. Heartbeat 타이머 시작 (10초 주기)

📦 3. Redis 사용처

3.1 Socket.io Redis Adapter

여러 Socket.io 인스턴스 간 메시지 브로드캐스트. 내부적으로 {prefix}socket.io#* 채널 사용.

장애 시: 같은 인스턴스 내부 메시지만 동작, 다른 인스턴스로 가는 메시지 손실.

3.2 Room 메타데이터 (Hash)

키: {prefix}room:{roomId}

필드: roomId, createdAt, peerCount, guest, hosts (JSON), guestState (JSON), routerInstanceId, autoTransitionEnabled, realtimeModelVersion, vadSettings, externalSttEnabled, autoResponseEnabled, isTest, groupId

TTL: 없음. removeRoom() 호출까지 유지.

3.3 Room Instance Owner (String + CAS)

키: {prefix}room:{roomId}:instance / TTL 90초

역할. 같은 room의 모든 peer를 동일 instance로 라우팅. Lua 스크립트 PIN_ROOM_LUA로 takeover까지 원자 처리.

• Owner 없음 → SET + SADD (성공)
• Owner 같음 → EXPIRE만 갱신 (TTL 연장)
• Owner 다르고 heartbeat 죽음 → takeover
• Owner 다르고 alive → 실패 + redirect 반환

3.4 Peer 정보 (Hash + 역 인덱스)

키: {prefix}peer:{peerId}

역 인덱스 Set (검색용).

• {prefix}socket:{socketId}:peers - Socket ID로 검색
• {prefix}instance:{instanceId}:peers - Instance로 검색
• {prefix}room:{roomId}:peers - Room의 모든 peer
• {prefix}room:{roomId}:hosts - 호스트만
• {prefix}room:{roomId}:guest - 게스트 (String, 1개)

3.5 Heartbeat (Sorted Set + String)

Instance 생존성 추적. Reaper가 이걸 기준으로 dead instance 판정.

• {prefix}instance:{instanceId}:heartbeat (String, TTL 30s)
• {prefix}instances:heartbeat (Zset, score=timestamp)

갱신 주기: 10초. Stale 판정: 45초 이상 미갱신.

3.6 Reaper Leader Lease (String)

키: {prefix}reaper:leader / TTL 90초

여러 instance가 동시에 reaper를 돌리지 않도록 leader election. SET NX EX로 취득, CAS Lua로 refresh.

3.7 Reaper (Dead instance 정리)

주기: 60초. 작업.

1. Stale instance 찾기 (heartbeat 60초 이상 부재)
2. 2-phase: 60초 후 재확인 (false positive 방지)
3. Owner CAS로 room 삭제 (takeover된 room은 skip)
4. Peer 정리
5. Instance 인덱스 정리

3.8 Recording Pending (String, TTL 3600s)

키: {prefix}recording:pending:{roomId}

녹화 중 서버 재시작 시 메타데이터 복구. TTL 만료 시 자동 폐기.

3.9 Settings Store (String)

키: {prefix}settings:ambientNoiseEnabled

전역 환경 소음 알림 토글. 유일하게 fail-open 패턴(Redis 미연결 시 true 반환).

3.10 Pending Disconnect (String, JSON)

키: {prefix}pending-disconnect:pending:{key}

게스트 disconnect 후 grace period 동안 재접속 대기. TTL은 GRACE_PERIOD_MS.

🔑 4. 키 네이밍 전체 표

모든 키는 ppi:socket:{STAGE}: prefix를 가집니다. 표는 prefix를 생략한 형태로 표기.

📊 5. 모니터링 & 헬스체크

Prometheus 메트릭

헬스체크 엔드포인트

/health에서 pingRedis() 호출. PONG 응답 시 healthy.

Web Admin Debug 페이지

/app/main/debug/redis에서 실시간 확인 가능.

• 메모리 vs Redis room 비교
• Instance heartbeat 상태
• Reaper leader 소유권
• Room pin owner (다중 인스턴스 라우팅)
• Monitoring claim peer 목록

⚠️ 6. 장애 시 영향 범위

Redis 완전 장애 시 영향. 대부분 FATAL입니다.

🔍 7. 트러블슈팅 체크리스트

redis-cli -u "$REDIS_URL" KEYS "ppi:socket:*" | awk -F: '{print $1":"$2":"$3}' | sort -u

# 잘못된 prefix만 삭제 (예시)
redis-cli -u "$REDIS_URL" --scan --pattern 'ppi:socket:wrong-stage:*' | \
  xargs -L 100 redis-cli -u "$REDIS_URL" DEL

# 자신의 heartbeat 확인
redis-cli -u "$REDIS_URL" GET "ppi:socket:prod:instance:$(hostname):heartbeat"
redis-cli -u "$REDIS_URL" TTL "ppi:socket:prod:instance:$(hostname):heartbeat"

# 전체 instance heartbeat
redis-cli -u "$REDIS_URL" ZRANGEBYSCORE "ppi:socket:prod:instances:heartbeat" -inf +inf WITHSCORES

# Redirect 메트릭 급증 확인
curl http://localhost:3001/metrics | grep ppi_socket_room_pin_redirect

# 해당 room owner 확인
redis-cli -u "$REDIS_URL" GET "ppi:socket:prod:room:{roomId}:instance"

# Owner instance의 heartbeat 확인
redis-cli -u "$REDIS_URL" GET "ppi:socket:prod:instance:{ownerId}:heartbeat"
# 없으면 stale → reaper가 정리할 때까지 대기 (60~120초)

# 강제로 pin 해제 (해당 room의 모든 peer가 끊김)
redis-cli -u "$REDIS_URL" DEL "ppi:socket:prod:room:{roomId}:instance"

echo $ROOM_META_SOURCE  # redis / both / memory

# 특정 room 직접 비교
redis-cli -u "$REDIS_URL" HGETALL "ppi:socket:prod:room:{roomId}"

redis-cli -u "$REDIS_URL" GET "ppi:socket:prod:recording:pending:{roomId}"
redis-cli -u "$REDIS_URL" TTL "ppi:socket:prod:recording:pending:{roomId}"

redis-cli -u "$REDIS_URL" INFO memory | grep used_memory_human
redis-cli -u "$REDIS_URL" --bigkeys
redis-cli -u "$REDIS_URL" --memkeys

redis-cli -u "$REDIS_URL" --scan --pattern 'ppi:socket:prod:room:*' | \
  xargs -L 1 redis-cli -u "$REDIS_URL" MEMORY USAGE

redis-cli -u "$REDIS_URL" GET "ppi:socket:prod:reaper:leader"
redis-cli -u "$REDIS_URL" TTL "ppi:socket:prod:reaper:leader"

# Adapter 연결 상태
curl http://localhost:3001/metrics | grep ppi_socket_redis_adapter_connected

# pub/sub 채널 활성 확인
redis-cli -u "$REDIS_URL" PUBSUB CHANNELS '*socket.io*'

🚨 8. 긴급 대응 런북

시나리오 A. Redis 완전 다운

1. 확인. redis-cli -u "$REDIS_URL" PING → 응답 없음
2. 인프라 팀에 즉시 에스컬레이션. ElastiCache/Valkey 콘솔에서 인스턴스 상태 확인
3. Failover 대기. Multi-AZ 구성이라면 자동 failover (1~2분)
4. Socket 서버는 자동 복구. ioredis가 재연결 시도. 단, 부팅 단계라면 컨테이너 재시작 필요
5. 사용자 영향 공지. 일시적으로 신규 room 생성 불가, 진행 중 세션은 끊김

시나리오 B. Redis 응답 지연 (latency 급증)

1. redis-cli --latency -u "$REDIS_URL"로 지연 측정
2. SLOWLOG GET 20으로 느린 쿼리 확인
3. CLIENT LIST로 비정상 클라이언트 탐색
4. --bigkeys로 거대 키 점검
5. 필요시 read replica 추가 또는 인스턴스 스케일업

시나리오 C. 데이터 일관성 깨짐 (잘못된 room 표시)

1. Web admin /app/main/debug/redis에서 불일치 식별
2. 특정 room이 stale이라면 강제 정리. DEL room:{id}* peer:{id}*
3. Reaper가 자동 정리할 때까지 기다리는 것이 안전 (60~120초)

시나리오 D. 전체 키 삭제 필요 (재해 복구)

금지: FLUSHALL 절대 사용 금지 (다른 서비스 키까지 삭제).

# prefix 한정 삭제 (안전)
redis-cli -u "$REDIS_URL" --scan --pattern 'ppi:socket:prod:*' | \
  xargs -L 100 redis-cli -u "$REDIS_URL" DEL

삭제 후 모든 Socket 서버 재시작 필요 (인메모리 캐시와 Redis 정합 회복).

⚙️ 9. 자주 쓰는 명령어 모음

기본 진단

# 연결
redis-cli -u "$REDIS_URL" PING

# 서버 정보
redis-cli -u "$REDIS_URL" INFO server
redis-cli -u "$REDIS_URL" INFO memory
redis-cli -u "$REDIS_URL" INFO clients

# 지연 측정
redis-cli -u "$REDIS_URL" --latency
redis-cli -u "$REDIS_URL" --latency-history -i 1

# 느린 쿼리
redis-cli -u "$REDIS_URL" SLOWLOG GET 20
redis-cli -u "$REDIS_URL" SLOWLOG RESET

키 탐색

# 활성 room 목록
redis-cli -u "$REDIS_URL" SMEMBERS "ppi:socket:prod:rooms:active"

# 특정 room 메타
redis-cli -u "$REDIS_URL" HGETALL "ppi:socket:prod:room:{roomId}"

# Instance heartbeat 전체 (score=timestamp)
redis-cli -u "$REDIS_URL" ZRANGEBYSCORE "ppi:socket:prod:instances:heartbeat" -inf +inf WITHSCORES

# 패턴 스캔 (KEYS는 절대 사용 금지, prod에서 차단됨)
redis-cli -u "$REDIS_URL" --scan --pattern 'ppi:socket:prod:room:*'

모니터링

# 실시간 명령 모니터 (prod에서 사용 주의)
redis-cli -u "$REDIS_URL" MONITOR

# 활성 클라이언트
redis-cli -u "$REDIS_URL" CLIENT LIST

# 키 공간 통계
redis-cli -u "$REDIS_URL" INFO keyspace

긴급 정리

# 특정 room 강제 정리
redis-cli -u "$REDIS_URL" DEL \
  "ppi:socket:prod:room:{roomId}" \
  "ppi:socket:prod:room:{roomId}:instance" \
  "ppi:socket:prod:room:{roomId}:peers" \
  "ppi:socket:prod:room:{roomId}:hosts" \
  "ppi:socket:prod:room:{roomId}:guest"
redis-cli -u "$REDIS_URL" SREM "ppi:socket:prod:rooms:active" "{roomId}"

# Reaper leader 강제 해제
redis-cli -u "$REDIS_URL" DEL "ppi:socket:prod:reaper:leader"

금지 명령

• KEYS * - O(N) 차단. SCAN 사용.
• FLUSHALL, FLUSHDB - 다른 서비스 키까지 삭제.
• DEBUG SLEEP - 운영 절대 금지.
• CONFIG SET maxmemory - 인프라 팀 외 금지.