7.3 Incident Runbook

Incident 중에는 완벽한 원인 분석보다 사용자 영향을 줄이는 일이 먼저입니다. Runbook은 탐지, 범위 확인, 완화, 진단, 복구, 후속 조치 순서로 작성합니다.

0. 안전 원칙

• 증거를 남기기 전에 process와 Pod를 반복 재시작하지 않습니다.
• WAL file, data file, replication slot을 임의로 삭제하지 않습니다.
• pg_terminate_backend()와 failover는 영향 범위를 확인한 뒤 실행합니다.
• 여러 사람이 동시에 상반된 조치를 하지 않도록 incident commander를 정합니다.

1. 사용자 영향 확인

시작 시각:
영향 서비스:
오류율 / latency:
read / write 영향:
영향 region / tenant:
최근 변경:

Service SLI, synthetic transaction, 고객 오류를 먼저 봅니다. Monitoring만 끊긴 경우와 실제 요청 실패를 분리합니다.

2. 범위 분류

관찰	가능성이 높은 범위
모든 instance up=0	Prometheus/network/service discovery
up=1, pg_up=0	DB connection/인증/TLS/DB availability
일부 database만 지연	workload/lock/database별 object
primary write 실패	primary/storage/WAL/fencing
replica read만 오래됨	receive/replay/routing
node metric도 동시에 악화	CPU/memory/disk/network

3. 빠른 상태 수집

SELECT now(), pg_is_in_recovery(), current_setting('server_version');

SELECT state, wait_event_type, wait_event, count(*)
FROM pg_stat_activity
WHERE backend_type = 'client backend'
GROUP BY state, wait_event_type, wait_event
ORDER BY count(*) DESC;

SELECT pid, now() - xact_start AS xact_age,
       pg_blocking_pids(pid), left(query, 160)
FROM pg_stat_activity
WHERE xact_start IS NOT NULL
ORDER BY xact_start
LIMIT 20;

Host나 Kubernetes 상태도 같은 시각으로 저장합니다.

date -u
uptime
vmstat 1 5
iostat -xz 1 5
df -h

Kubernetes에서는 Pod status, restart, event, node pressure, PVC 사용량을 수집합니다.

4. 완화 선택

Connection 포화

• 비필수 traffic rate limit
• pool timeout과 queue 확인
• root blocker 취소
• runaway client 차단
• max_connections 즉시 증가는 memory와 fd 비용 검토 후 결정

Lock chain

• root blocker와 transaction owner 확인
• 안전하면 pg_cancel_backend()
• 사용자 영향이 지속되고 rollback 비용을 감수할 수 있을 때 terminate

Storage 포화

• archive/slot/log/temporary file 원인 구분
• 신규 batch나 write traffic 제한
• 안전한 volume 확장
• pg_wal 수동 삭제 금지

Replica lag

• stale read가 허용되지 않으면 routing에서 제외
• receive와 replay 병목 분리
• primary WAL 보존과 slot capacity 확인

Primary 장애

• HA manager 상태와 fencing 확인
• RPO/RTO 기준으로 failover 결정
• 두 primary가 동시에 쓰기를 받지 않는지 확인

5. 복구 확인

• 사용자 SLI가 정상 범위로 돌아왔는가?
• Error와 latency가 최소 두 관측 window 동안 안정적인가?
• Queue와 connection backlog가 해소됐는가?
• Replica와 archive가 따라잡았는가?
• 임시 traffic 제한을 되돌려도 되는가?
• Monitoring gap이 남지 않았는가?

6. Timeline 남기기

14:03 alert firing
14:05 사용자 write error 확인
14:08 root blocker PID 확인
14:10 batch transaction cancel
14:12 error ratio 정상화
14:25 replica lag 해소

Runbook은 incident가 끝난 뒤 실제로 막혔던 단계와 잘못된 query를 수정합니다. 실행되지 않는 runbook보다 짧더라도 검증된 절차가 낫습니다.