본문으로 바로가기
리옵트 핸드북
리옵트 핸드북
Prisma Production Guardrails

기반 설계

Ch1. 환경 분리 전략Ch2. 토폴로지와 환경 구성Ch3. Prisma Postgres 활용

마이그레이션

Ch4. 마이그레이션 전략Ch5. 마이그레이션 파이프라인Ch6. 마이그레이션 실패 대응Ch7. 롤백 전략

운영 안정성

Ch8. 백업 및 DR 전략Ch9. 관측 전략Ch10. 운영 트러블슈팅Ch11. 운영 정책과 거버넌스Ch12. Prisma MCP 활용

부록

부록 A. 런북 템플릿검증 리포트업데이트 내역
핸드북›Prisma Production Guardrails›Ch10. 운영 트러블슈팅

Ch10. 운영 트러블슈팅

증상 기반 트리아지 매트릭스와 연결 고갈·락 경합·마이그레이션 드리프트·대량 백필 성능 저하 네 케이스의 진단 SQL과 단계별 조치를 정리합니다.

핵심 요약

  • API 타임아웃·CPU 급등·읽기 불일치·배포 직후 오류는 증상 기반 트리아지 매트릭스에서 1차·2차 확인과 즉시 완화로 나눠 다룹니다.
  • 연결 고갈은 비핵심 워커 중지, 오토스케일 정책 점검, PrismaClient 싱글턴 위반 여부 확인으로 대응합니다.
  • 락 경합은 pg_stat_activity·pg_locks 조인 쿼리로 blocking/blocked PID를 찾아 장시간 트랜잭션을 종료하거나 DDL을 분할합니다.
  • 마이그레이션 드리프트는 실제 스키마와 _prisma_migrations 이력을 비교한 뒤 migrate resolve를 적용할지 정합니다.
  • 대량 백필 성능 저하는 배치 청크 분할·sleep 간격·트랜잭션 크기 제한·피크 시간 자동 중단 토글로 완화합니다.

증상 기반 트리아지 매트릭스

증상1차 확인2차 확인즉시 완화
API 타임아웃 급증DB active connectionlock wait, long transaction트래픽 완화, 쿼리 제한
CPU 급등슬로우 쿼리 상위 N실행 계획/인덱스문제 배치 중단
읽기 불일치replication lag읽기 라우팅 정책임시 primary read 전환
배포 직후 오류migration 상태앱-스키마 호환성코드 롤백/feature off

케이스 1: 연결 고갈

진단

  • 앱 인스턴스 수 증가와 동시 발생 여부 확인
  • 풀링 계층(PgBouncer) 상태 확인
  • DB max connection 대비 사용률 확인

조치

  1. 비핵심 워커/배치 일시 중지
  2. API 인스턴스 급증 원인(오토스케일 정책) 점검
  3. 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 이력과 실제 스키마 불일치

조치

  1. 실제 스키마와 마이그레이션 이력 비교
  2. 차이를 문서화한 뒤 migrate resolve를 적용할지 결정
  3. 임의 수동 DDL이 있었다면 감사 기록과 함께 표준 경로로 회복

케이스 4: 대량 백필 중 성능 저하

조치 원칙

  • 백필을 배치 청크 단위로 쪼개고 sleep 간격 적용
  • 트랜잭션 크기 제한
  • 피크 시간 자동 중단 토글 제공

운영 후속 조치

  • 장애 유형별 재발 방지 체크리스트 업데이트
  • 알림 임계치 튜닝 결과 반영
  • 런북의 “탐지-완화-복구” 단계별 책임자 명시

관련 문서

Ch2. 토폴로지와 환경 구성

Prisma + DB 프로덕션 토폴로지, 풀링, 다중 인스턴스 및 배포 구성

부록 A. 런북 템플릿

마이그레이션 배포·장애 대응·복구 리허설(DR Drill)·포스트모템 네 가지 런북 템플릿을 복사해 바로 쓸 수 있는 체크리스트 형태로 제공합니다.

Ch9. 관측 전략

API·Prisma·DB 세 레이어 지표와 OTel 트레이스, slow query 로깅, 배포 직후 강화 관측, SLO/에러버짓 기반 알림 설계를 다룹니다.

Ch11. 운영 정책과 거버넌스

변경 관리·접근 제어·배포 통제·감사·회고 정책과 RACI, 변경 요청서, MCP 명령 등급별 승인 기준, 포스트모템 운영 KPI를 정리합니다.

On this page

증상 기반 트리아지 매트릭스케이스 1: 연결 고갈진단조치케이스 2: 락 경합과 마이그레이션 지연진단 SQL 예시조치케이스 3: 마이그레이션 드리프트징후조치케이스 4: 대량 백필 중 성능 저하조치 원칙운영 후속 조치