Ch10. 운영 트러블슈팅
프로덕션에서 자주 발생하는 Prisma/DB 이슈와 단계별 해결 절차
증상 기반 트리아지 매트릭스
| 증상 | 1차 확인 | 2차 확인 | 즉시 완화 |
|---|---|---|---|
| API 타임아웃 급증 | DB active connection | lock wait, long transaction | 트래픽 완화, 쿼리 제한 |
| CPU 급등 | 슬로우 쿼리 상위 N | 실행 계획/인덱스 | 문제 배치 중단 |
| 읽기 불일치 | replication lag | 읽기 라우팅 정책 | 임시 primary read 전환 |
| 배포 직후 오류 | migration 상태 | 앱-스키마 호환성 | 코드 롤백/feature off |
케이스 1: 연결 고갈
진단
- 앱 인스턴스 수 증가와 동시 발생 여부 확인
- 풀링 계층(PgBouncer) 상태 확인
- DB max connection 대비 사용률 확인
조치
- 비핵심 워커/배치 일시 중지
- API 인스턴스 급증 원인(오토스케일 정책) 점검
- PrismaClient 생성 패턴(싱글턴 위반 여부) 확인
케이스 2: 락 경합과 마이그레이션 지연
진단 SQL 예시
SELECT pid, usename, state, wait_event_type, wait_event, query
FROM pg_stat_activity
WHERE state <> 'idle';
SELECT blocked_locks.pid AS blocked_pid,
blocking_locks.pid AS blocking_pid,
blocked_activity.query AS blocked_query,
blocking_activity.query AS blocking_query
FROM pg_locks blocked_locks
JOIN pg_stat_activity blocked_activity
ON blocked_activity.pid = blocked_locks.pid
JOIN pg_locks blocking_locks
ON blocking_locks.locktype = blocked_locks.locktype
AND blocking_locks.DATABASE IS NOT DISTINCT FROM blocked_locks.DATABASE
AND blocking_locks.relation IS NOT DISTINCT FROM blocked_locks.relation
AND blocking_locks.page IS NOT DISTINCT FROM blocked_locks.page
AND blocking_locks.tuple IS NOT DISTINCT FROM blocked_locks.tuple
AND blocking_locks.virtualxid IS NOT DISTINCT FROM blocked_locks.virtualxid
AND blocking_locks.transactionid IS NOT DISTINCT FROM blocked_locks.transactionid
AND blocking_locks.classid IS NOT DISTINCT FROM blocked_locks.classid
AND blocking_locks.objid IS NOT DISTINCT FROM blocked_locks.objid
AND blocking_locks.objsubid IS NOT DISTINCT FROM blocked_locks.objsubid
AND blocking_locks.pid != blocked_locks.pid
JOIN pg_stat_activity blocking_activity
ON blocking_activity.pid = blocking_locks.pid
WHERE NOT blocked_locks.granted;조치
- 장시간 트랜잭션 종료 또는 작업 윈도우 재조정
- 문제 DDL을 더 작은 단위로 분할
- 필요 시 배포 중단 후 코드 롤백
케이스 3: 마이그레이션 드리프트
징후
migrate deploy실패_prisma_migrations이력과 실제 스키마 불일치
조치
- 실제 스키마와 마이그레이션 이력 비교
- 차이를 문서화한 뒤
migrate resolve적용 여부 결정 - 임의 수동 DDL이 있었다면 감사 기록과 함께 표준 경로로 회복
케이스 4: 대량 백필 중 성능 저하
조치 원칙
- 백필을 배치 청크 단위로 쪼개고 sleep 간격 적용
- 트랜잭션 크기 제한
- 피크 시간 자동 중단 토글 제공
운영 후속 조치
- 장애 유형별 재발 방지 체크리스트 업데이트
- 알림 임계치 튜닝 결과 반영
- 런북의 “탐지-완화-복구” 단계별 책임자 명시