본문으로 건너뛰기

Frontend AI Ops · EP 04

복구는 감이 아니라 런북이다 — 장애가 터졌을 때의 시스템

AI로 구현이 빨라져도 장애 대응은 여전히 사람의 몫이다. 배포 후 48시간 관측, 디버깅 4단계, 트리아지, 온콜 드릴, 공급망 사고 대응을 실제로 돌아가는 시스템의 기록과 함께 한 편으로 묶었다.

· 10분 읽기

복구는 감이 아니라 런북이다 — 장애가 터졌을 때의 시스템

2월 말에 프론트엔드 AI 실무 시리즈에서 디버깅 런북을 썼다. 이어서 배포 후 48시간 관측 런북, 온콜 드릴, 공급망 사고 대응, MCP 트리아지까지 4월 초까지 다섯 편을 썼다. 주제는 저마다 달라 보였는데, 돌아보면 같은 문장을 다섯 번 쓴 것이었다.

장애 대응의 품질은 그날의 컨디션이 아니라, 평소에 만들어 둔 시스템에서 나온다.

첫 편의 검증 게이트가 “배포 가능함을 증명하는 장치”이고 두 번째 편의 계약과 하네스가 “품질을 사전에 고정하는 장치”라면, 이번 글은 그래도 터지는 것들을 위한 장치다. 지난 편 끝에 “계약과 하네스로도 못 막는 게 하나 남는다. 장애다”라고 썼다. 이 글은 2월부터 4월까지의 다섯 편을 한 편으로 합쳐 다시 쓴 것이다. 프레임은 남기고, 그 사이에 실제로 돌아가는 시스템의 기록을 이식했다.

1. 기능 스토리는 누구나 있는데, 장애 스토리는 아무도 없다

사이드 프로젝트 포트폴리오에서 가장 취약한 구간은 “문제가 터졌을 때”다. 기능 개발 스토리는 누구나 준비한다. 하지만 “AI로 구현은 빨랐는데, 장애 났을 때 어떻게 잡았나요?”라는 질문이 오면 대부분의 이야기가 거기서 멈춘다.

생성 속도는 상향 평준화됐다. 그래서 남는 차이는 복구 속도다. 정확히는, 이 세 가지를 시스템으로 갖고 있는가다.

  1. 장애를 재현 가능한 형태로 남길 수 있는가
  2. 원인을 시스템적으로 좁힐 수 있는가
  3. 같은 장애를 다시 막는 프로세스를 만들 수 있는가

다섯 편의 원문은 이 세 질문에 각자 답하려던 글이었다. 이 글에서는 그 답을 시간축으로 다시 배열한다. 배포 직후(48시간 관측) → 터진 뒤(디버깅 4단계, 트리아지) → 평시(온콜 드릴) → 밖(공급망 사고), 그리고 이 전체를 떠받치는 기억장치(세션 로그).

2. 배포는 끝이 아니라 관측이다 — 48시간 시간축

대부분의 프론트엔드 이슈는 배포 직후가 아니라, 트래픽과 사용자 경로가 쌓이는 24~48시간 안에 터진다. 특정 브라우저 조합에서만 나는 hydration 오류, AI가 생성한 분기 로직의 희귀 조건 누락, 성능 저하로 전환이 미세하게 깎이는 경우. 배포 성공은 끝이 아니라 관측 시작이다.

전제는 하나다. 지표를 먼저 고정하고 배포한다.

  1. Error KPI — JS 에러율, 주요 에러 Top 5
  2. UX KPI — LCP/INP, 주요 플로우 이탈률
  3. Business KPI — 회원가입·결제·문의 전환율

“문제가 생겼다”가 아니라 “어느 지표가 얼마나 나빠졌는지”를 말할 수 있어야 대응이 시작된다.

0~2시간, 스모크. release 태그가 이번 배포와 일치하는가, 핵심 플로우에 콘솔 오류가 없는가, P95 LCP/INP가 기준 안에 있는가. AI가 만든 try/catch에서 throw 누락을 먼저 본다. 로그는 문장보다 필드 구조(feature, step, userType)로 남긴다. 완벽함이 아니라 조기 감지가 목표다.

2~24시간, 군집화. 에러를 건별로 보면 끝이 없다. 먼저 묶는다 — 환경 이슈(브라우저/OS/네트워크), 코드 이슈(null 처리 누락, 타입 가정 실패), 데이터 이슈(API 스키마 변화, 필드 누락). 그리고 건수가 아니라 사용자 영향도로 우선순위를 정한다. 화이트스크린·CTA 불가가 최상위, 다음 기능 저하, 다음 체감 품질.

24~48시간, 재발 방지. 핫픽스로 끝내면 같은 문제가 돌아온다. 이 구간의 산출물은 셋이다 — 재현 조건 한 문장, 원인 분류(코드/데이터/운영), 재발 방지 액션 하나. 재현 조건의 목표 형태는 이런 문장이다. “Safari 17 + 느린 3G에서 상품 필터 초기화 시 hydration mismatch”처럼, 한 문장으로 못 쓰면 아직 원인을 모른다는 뜻이다.

## 배포 후 48시간 관측 로그

### 0~2h (스모크)
- Release:
- Top Error:
- LCP/INP:
- 즉시 조치:

### 2~24h (군집화)
- 환경 이슈:
- 코드 이슈:
- 데이터 이슈:
- 사용자 영향도 기준 우선순위:

### 24~48h (재발 방지)
- 재현 조건(1문장):
- 원인 분류:
- 방지 액션:
- 다음 배포 반영 여부:

3. 터졌다면 — 디버깅 4단계와 장애 대응 카드

관측이 장애를 잡아주는 건 아니다. 잡혔으면 이제 대응이고, 나의 루프는 4단계다.

1) 재현 — “에러 메시지”가 아니라 “사용자 흐름”으로. 세션 리플레이 링크, 환경 정보(브라우저·OS·배포 버전·기능 플래그), 네트워크/콘솔 스냅샷을 기본 세트로 수집한다. “어디서 터졌는지”보다 “어떤 흐름에서 터졌는지”를 남긴다. 재현이 흔들리면 나머지 단계가 전부 느려진다.

2) 원인 축소 — AI에는 “증거 묶음”만 준다. 막연히 “왜 깨졌어?”가 아니라 스택트레이스, 해당 커밋 범위(diff), 실패한 E2E 시나리오, 관련 컴포넌트 의존 관계를 묶어서 준다. 지난 편의 계약과 같은 원리다 — 입력이 고정돼야 출력이 의미를 갖는다. 그리고 AI의 출력은 정답이 아니라 우선순위가 붙은 가설 리스트로 다룬다. 가설 생성은 기계가, 사실 검증은 사람이.

3) 복구 — 핫픽스보다 롤백 가능한 작은 변경. 장애 상황에서 큰 리팩터링은 위험만 키운다. 단일 책임 PR로 쪼개고, 기존 동작을 보존하는 가드 코드를 먼저 붙이고, 구조 개선은 복구 후 별도 PR로 미룬다.

4) 회고 — 개인 실수가 아니라 시스템 티켓으로. 회고에는 최소 세 가지를 남긴다. 탐지까지 걸린 시간(MTTD), 복구까지 걸린 시간(MTTR), 재발 방지 액션(테스트·알림·가드레일). 이 데이터가 쌓여야 “장애를 겪었다”가 아니라 “장애 대응 체계를 운영했다”가 된다.

이 루프를 한 장의 카드로 남긴다.

## FE 장애 대응 카드

### Incident
- 증상:
- 최초 감지 시각:
- 영향 범위(사용자/매출/핵심 KPI):

### Evidence
- 세션 리플레이:
- Sentry 이슈:
- 실패 테스트/로그:
- 관련 커밋 범위:

### Hypotheses (AI + Human)
1. [ ] 가설 A / 검증 결과
2. [ ] 가설 B / 검증 결과
3. [ ] 가설 C / 검증 결과

### Mitigation
- [ ] 임시 완화(Feature Flag, Guard)
- [ ] 영구 수정 PR 링크
- [ ] 롤백 계획 확인

### Prevention
- [ ] E2E 회귀 케이스 추가
- [ ] 알림 룰 업데이트
- [ ] 문서/런북 업데이트

4. 트리아지 — 분류는 기계가, 결정은 사람이

장애 대응에서 시간이 가장 많이 사라지는 지점은 원인 분석이 아니라 그 앞이다. 누가 볼지 정하기, 재현 정보 수집, 로그·에러·배포 이력 대조, 우선순위 합의. 이 단계들은 사람마다 방식이 달라 품질이 흔들린다. 그래서 트리아지부터 자동화한다.

에이전트가 여러 소스(런타임 에러 로그, 배포 히스토리, 모니터링 이벤트, 이슈 트래커)를 같은 인터페이스로 읽어 초기 분류안을 만들게 한다. 이때 입력 4종이 고정돼 있지 않으면 분류 품질이 급락한다.

  • 에러 스택(Sentry/콘솔)
  • 사용자 영향 범위(세션 수, 전환율 변화)
  • 직전 배포 변경점(PR, 커밋)
  • 재현 조건(브라우저, 기기, 계정 상태)

분류 규칙은 팀 언어로 선언해 둔다. P0 로그인/결제/데이터 손실, P1 핵심 전환 퍼널 장애, P2 우회 가능한 기능 저하, P3 미관·경고성 이슈. 규칙이 문서가 아니라 머릿속에 있으면 분류가 사람마다 달라진다 — 그게 트리아지 품질 편차의 원인이다.

실행 계층에서는 분류 결과마다 에이전트가 초안을 내게 한다. 즉시 조치(롤백/핫픽스/플래그 OFF), 검증 체크리스트(E2E·스모크·접근성), 커뮤니케이션 문구(내부/고객 공지). 원칙은 앞 편들과 같다 — AI는 제안하고, 최종 결정은 사람이 한다. 내 일상에서는 파일 쓰기·커밋·네트워크 같은 파괴적 행위가 승인 버튼으로 릴레이되는 구조로 이미 돌아가고 있다. 장애 티켓도 같은 모양이다. 분류안과 조치 초안이 티켓에 남고, 사람이 승인하거나 고친다.

## FE Incident Triage

### 1) 증상 요약
- 최초 감지 시각:
- 사용자 영향:
- 에러 지표:

### 2) AI 분류 초안
- 우선순위(P0~P3):
- 근거 데이터:
- 신뢰도:

### 3) 재현 정보
- 브라우저/OS:
- 계정 상태:
- 재현 단계:

### 4) 권장 조치
- 즉시 조치:
- 검증 시나리오:
- 롤백 필요 여부:

### 5) 사람 검토 결과
- 최종 우선순위:
- 실제 조치:
- 회고 포인트:

5. 온콜 드릴 — 측정되지 않은 대응은 개선될 수 없다

여기까지는 장애가 났을 때의 이야기다. 문제는 실제 장애가 드물다는 것이다. 분기에 한 번 나올까 말까 한 사건으로는 대응 품질이 자라지 않는다. 그래서 드릴이다. 장애를 의도적으로 재현하고, 시간을 잰다.

시나리오 선정. “신기한 버그”가 아니라 설명 가능한 사고를 고른다. API는 성공인데 UI가 빈 상태로 고정되는 케이스, 캐시 오염으로 이전 사용자 데이터가 잠깐 노출되는 케이스, feature flag 미스매치로 결제 버튼이 숨겨지는 케이스.

관측 포인트 정의. 최소 네 가지를 먼저 고정한다. 사용자 징후(어떤 화면에서 어떤 증상), 로그 키(에러 코드, userId hash, release version), 경보 조건(에러율 임계치), 성공 기준(복구 후 핵심 경로 E2E 통과).

실행. 실제로 터뜨리고 네 시각을 기록한다 — 사고 시작, 첫 탐지(MTTD), 임시 완화 완료, 근본 원인 패치 완료(MTTR). 재현 스크립트, 로그 필드 보강 코드, 완화책 문서는 에이전트 초안으로 만들되 누가 승인했는지를 남긴다. AI가 제안한 대응, 사람이 채택한 대응, 반려한 대응과 이유 — 이 세 줄이 있어야 드릴이 기록이 되고, 없으면 리허설에 그친다.

회고. 세 줄이면 충분하다. 무엇이 늦었는가. 무엇이 오탐이었는가. 무엇을 자동화할 것인가.

여기서 하나 짚는다. 드릴 개선 수치의 ‘예시 값’을 원문에서 전부 뺐다. 측정한 적 없는 숫자를 인용하는 순간 기록이 아니라 소설이 되기 때문이다. MTTD와 MTTR은 드릴을 돌려서 직접 재야 하는 숫자고, 그래서 드릴이 필요하다.

## AI On-call Drill Log

### 1) 시나리오
- 사고 유형:
- 사용자 영향:
- 재현 방법:

### 2) 탐지
- 최초 징후:
- 감지 채널(Sentry/Datadog/로그):
- MTTD:

### 3) 대응
- AI 제안:
- 사람이 채택한 대응:
- 반려한 대응 + 이유:

### 4) 복구
- 임시 완화 시각:
- 근본 원인 패치 시각:
- MTTR:

### 5) 재발 방지
- 추가한 가드레일:
- 테스트/모니터링 변경:
- 다음 드릴 일정:

6. 공급망 사고 — 에이전트가 늘어난 만큼 공격면도 늘어난다

장애는 내 코드에서만 터지지 않는다. 로컬 CLI 에이전트가 코드를 쓰고, CI가 자동 리뷰와 리팩터링을 돌리고, 브라우저 확장과 SDK가 외부 서비스에 붙는 구조에서 공급망 문제는 프론트엔드의 문제다. 의도치 않은 코드 삽입, 토큰·환경변수 노출, PR 단위의 보안 기준 붕괴.

대응은 4단계다.

탐지. 개인 감이 아니라 룰이다. lockfile 변경 PR에 보안 리뷰 라벨 강제, 번들 크기 임계치 초과 시 fail, 신규 postinstall 스크립트 발견 시 머지 차단.

차단. 원인 분석보다 확산 차단이 먼저다. 문제 브랜치 배포 파이프라인 일시 중지, 에이전트 write 권한 read-only로 강등, 민감 토큰 즉시 rotate, 최근 자동 생성 커밋 범위 격리. 여기서 시간을 끌면 사고보다 2차 피해(재현 불가, 책임 추적 실패)가 커진다.

복구. 마지막 신뢰 가능한 태그로 롤백하고, lint/build/E2E 스모크를 재검증하고, 영향 범위(페이지/기능/사용자)를 문서화하고, 재배포는 승인 2인 체계로. 속도보다 검증 순서다.

학습. 탐지가 왜 늦었는지, 차단 명령에 누락·중복은 없었는지, PR 템플릿과 체크리스트에 무엇을 반영할지. 비난 문서가 아니라 운영 개선 문서를 만든다.

이 게이트들이 허공에 떠 있지 않게, 나는 일상 쪽에 먼저 걸어두었다. confluence-studio와 damon에서 API 토큰은 평문 환경변수가 아니라 OS 키체인에 보관한다 — Rust 스택을 고른 이유 중 하나가 키체인 1급 지원이었다. 에이전트의 파괴적 행위는 read-only 기본 권한 위에서 사람 승인으로만 열린다. 상주 스케줄러의 안정성까지 포함한 이 선택 이력은 2년 회고에 남아 있다. 공급망 사고 대응은 그때의 절차가 아니라 평소의 권한 구조가 절반을 해결한다 — 그게 내 결론이다.

7. 세션 로그 — 장애 대응의 기억장치

드릴 로그와 장애 대응 카드가 쌓이는 곳이 마지막 조각이다. 회고의 Prevention 항목은 쌓여 있을 때만 의미가 있다. 재발했을 때 다음 대응의 출발점이 되니까.

내 경우 그 기억장치는 세션 로그다. 첫 편에서 214개 세션을 0.42초에 훑어 실패 케이스를 회수하는 장면을 보였다. 이 검색이 가능한 이유가 따로 있다. 세션 로그는 SQLite + FTS5 trigram 색인으로 돌고, 이 조합으로 사용처의 90%는 만족한다. 나머지, 한글 노트의 정밀 검색은 Tantivy와 형태소 분석기로 별도 계층을 만들었다. 이 이중 구조를 정리한 게 한글 검색 이중 해법 글이다.

장애 대응 관점에서 세션 로그의 가치는 이런 곳에서 나온다. #0612 세션은 프로토콜 v2 스키마를 설계할 때의 트레이드오프를 기록해 둔 것인데, 비슷한 결정을 다시 내려야 하는 순간 검색어 하나로 회수된다. 그때 왜 그렇게 정했는지가 남아 있으면 재논의가 아니라 확인으로 끝난다. 장애 회고도 똑같이 쌓는다. 그러면 “예전에도 이런 증상이”가 기억이 아니라 기록이 된다.

시작 체크리스트

온콜 루프를 만든다면, 이 순서다.

  1. 다음 배포 전에 Error/UX/Business 지표 세 가지를 고정한다
  2. 배포 후 48시간을 세 구간으로 나눠 관측 로그를 남긴다
  3. 장애는 사용자 흐름으로 재현하고, AI에는 증거 묶음만 준다
  4. P0~P3 분류 규칙을 팀 언어로 문서화해 둔다
  5. 분기에 한 번 온콜 드릴을 돌리고 MTTD/MTTR을 직접 잰다

남는 것

기능을 빨리 만드는 건 이제 누구나 한다. 차이는 터진 다음에 나는데, 그 차이도 그날의 재능이 아니라 미리 만든 시스템이 만든다. 48시간 관측, 대응 카드, 트리아지 규칙, 드릴, 세션 로그 — 다섯 개가 하나의 루프로 묶여야 “장애 대응 체계”라는 말을 할 수 있다.

장애만큼 큰 나머지 리스크는 ‘큰 변경’이다. 마이그레이션과 디자인 시스템 변경을 리허설로 겪는 법, 그리고 이 모든 기록을 증거로 바꾸는 법은 이어지는 글에서 다룬다.

Related