이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.
- API 장애가 발생했을 때 사용자 영향과 원인 후보를 어떻게 나눠 확인하는가?
- Spring 백엔드 API 장애에서 안전한 임시 완화는 무엇인가?
- API 장애 Runbook은 어떤 정보가 있어야 장애 중 바로 실행 가능한가?
목적
이 Runbook은 API 오류율 증가, timeout, 응답 지연, 특정 기능 실패가 발생했을 때 적용한다.
목표는 원인 확정 전에 사용자 영향을 줄이고, 영향 범위를 좁히고, 안전한 완화 조치를 고르는 것이다.
API 장애는 코드 오류, DB 지연, cache 장애, 외부 API 실패, network 문제, 배포 문제, 데이터 상태 문제로 모두 나타날 수 있다.
따라서 첫 단계는 원인을 맞히는 것이 아니라 사용자 영향과 장애 범위를 정리하는 것이다.
적용 조건
- 특정 API의 5xx가 증가한다.
- p95 또는 p99 응답 시간이 기준을 넘는다.
- 사용자가 특정 기능 실패를 신고한다.
- 외부 API timeout이 증가한다.
- queue 적체로 API 결과가 지연된다.
- DB connection pool 대기가 증가한다.
- 최근 배포 없이도 오류가 증가한다.
배포 직후 발생했다면 배포 실패 Runbook과 함께 본다.
첫 5분
- 장애 채널을 열고 임시 Severity를 정한다.
- 사용자가 못 하는 일을 한 문장으로 적는다.
- 영향 endpoint, HTTP method, status code를 확인한다.
- 장애 시작 추정 시각과 탐지 시각을 분리해 기록한다.
- 최근 배포, 설정 변경, 배치 실행 여부를 확인한다.
- DB, cache, 외부 API 중 어느 축이 의심되는지 표시한다.
- 임시 완화가 가능한 기능 flag나 rate limit이 있는지 확인한다.
이 단계에서 불확실한 원인은 “가설”로 적는다.
영향 범위 확인
다음 질문에 예/아니오로 답한다.
- 모든 사용자에게 발생하는가?
- 특정 endpoint만 실패하는가?
- 쓰기 요청만 실패하는가?
- 특정 tenant, 지역, 앱 버전, 계정 유형만 영향이 있는가?
- 오류율 증가와 응답 시간 증가가 함께 있는가?
- 외부 의존성 호출이 포함된 요청만 실패하는가?
- 데이터 손실 가능성이 있는가?
영향 범위가 좁을수록 완화 조치를 작게 적용할 수 있다.
Spring 확인 순서
1. 애플리케이션 로그
grep "ERROR" application.log | tail -100
grep "orderId=12345" application.log확인할 것:
- 대표 exception class
- 영향 controller/service
- 요청 ID 또는 주문 ID
- 외부 API client 오류
- DB timeout 또는 transaction rollback
2. Metric
확인할 것:
- endpoint별 요청 수와 오류율
- p95/p99 응답 시간
- DB connection pool active/waiting
- JVM memory와 GC pause
- thread pool 또는 queue 적체
Metric은 규모를 보여 주고, log는 사례를 보여 준다.
3. 의존성
확인할 것:
- DB 연결이 가능한가?
- cache read/write가 실패하는가?
- 외부 API status가 정상인가?
- message consumer가 밀렸는가?
의존성 장애는 Spring 예외로 보이지만 실제 완화는 timeout, retry, fallback, 기능 제한이 될 수 있다.
안전한 완화 조치
- 영향 기능만 feature flag로 끈다.
- 쓰기 API를 제한하고 조회 API는 유지한다.
- 외부 API 실패가 원인이면 fallback 또는 degrade response를 사용한다.
- retry 폭주가 있으면 retry 횟수와 concurrency를 줄인다.
- 특정 endpoint가 과부하를 만든다면 rate limit을 적용한다.
- DB connection pool 포화가 있으면 트래픽 제한과 slow query 확인을 병행한다.
- 데이터 손실 가능성이 있으면 관련 쓰기 작업과 배치를 멈춘다.
완화 조치 후에는 어떤 지표가 회복되어야 하는지 먼저 정한다.
하지 말아야 할 대응
- 사용자 영향이 계속되는 동안 긴 원인 토론만 하지 않는다.
- 전체 서비스를 내리지 않고도 특정 기능 제한으로 완화 가능한지 확인하지 않는 상태로 두지 않는다.
- retry를 무작정 늘리지 않는다.
- 데이터 손실 가능성이 있는데 관련 배치를 계속 실행하지 않는다.
- 로그 샘플의 개인정보나 민감 payload를 그대로 공유하지 않는다.
인프라 담당자와 공유할 자료
- 영향 endpoint, method, status code, 시작 시각
- 사용자 영향 설명과 임시 Severity
- 대표 요청 ID, 사용자군, 주문 ID 등 샘플 식별자
- 최근 배포/설정/배치 변경
- 오류율, 응답 시간, 요청량, DB pool, queue 적체
- 이미 실행한 feature flag, rate limit, restart, traffic 조치
- 다음 업데이트 시각
종료 조건
- 영향 endpoint의 오류율과 응답 시간이 정상 범위로 돌아왔다.
- 사용자 신고 또는 핵심 이벤트 실패가 멈췄다.
- 임시 완화 조치의 유지/해제 조건이 정해졌다.
- 데이터 손실 가능성이 배제되었거나 별도 사고 대응으로 전환됐다.
- 장애 보고서에 타임라인과 후속 작업이 남았다.
확인 질문
확인 질문
- API 장애에서 첫 질문은 무엇이어야 하는가?
- 원인이 아니라 사용자가 무엇을 못 하는지와 영향 범위가 어디까지인지다.
- retry를 무작정 늘리면 위험한 이유는 무엇인가?
- 외부 의존성이나 DB 부하를 더 키워 장애를 증폭시킬 수 있기 때문이다.
- API 장애 종료 조건은 무엇인가?
- 사용자 영향 회복, 핵심 지표 정상화, 임시 조치 유지 조건, 후속 기록이다.
리뷰 체크포인트
- endpoint, status code, 사용자 영향이 먼저 나오는가?
- log, metric, 의존성 확인 순서가 분리되어 있는가?
- 안전한 완화 조치와 하지 말아야 할 대응이 구체적인가?
- 데이터 손실 가능성 분기가 있는가?
- 종료 조건과 다음 업데이트 기준이 있는가?