런북(runbook) 처음 만드는 법: 장애 시 “확인→완화→복구→검증” 템플릿과 작성 요령

알림이 울린 뒤 10분이 갈린다: 런북이 없는 팀의 공통 증상

장애 알림이 울리면 가장 먼저 나오는 말이 "누가 뭘 봐야 하지"인 경우가 많다.

모니터링 화면은 열었지만, 확인해야 할 지표와 순서가 정리되어 있지 않아 같은 시간을 반복해서 낭비한다.

결과적으로 완화는 늦어지고, 복구는 더 늦어지며, 복구 후 검증이 빠져 같은 장애가 다시 터진다.

런북을 처음 만들 때 자주 하는 착각은 "상세한 원인 분석 문서가 곧 런북"이라는 생각이다.

런북은 분석 보고서가 아니라, 장애 상황에서 사람들이 같은 순서로 움직이게 만드는 실행 문서에 가깝다.

장애 초기에 흔히 보이는 현장 문구를 예로 들면 다음과 같다.

10:12 알림: API 5xx 비율 8% 초과 (지속 3분)
10:14 문의: "결제 화면이 계속 로딩된다"
10:17 조치: 인스턴스 재시작 시도(근거 없음) → 증상 악화
10:21 뒤늦게 확인: DB 연결 수 제한 도달

이런 흐름은 "확인→완화→복구→검증"의 순서를 런북으로 고정하면 줄어든다.

런북이 고정하는 장애 대응 루프(확인→완화→복구→검증)

핵심 개념 2개로 시작하면 런북이 길을 잃지 않는다

개념 1) 런북(runbook)

정의: 특정 장애 신호가 발생했을 때, 사람이 따라 할 수 있는 확인 순서와 조치 선택지를 정리한 실행 문서다.

핵심 특징: "무엇을 보면 다음 행동이 결정되는지"가 문장으로 고정되어 있다.

핵심 특징: 담당자가 바뀌어도 동일한 결과에 가까워지도록, 경로와 기준이 함께 적혀 있다.

주의점: 가능한 모든 경우를 담으려다 길어지면, 장애 상황에서 읽히지 않는 문서가 된다.

개념 2) 단계 분리: 완화(mitigation)와 복구(recovery)

정의: 완화는 피해 확산을 멈추는 임시 조치이고, 복구는 정상 상태로 되돌리는 근본 조치다.

핵심 특징: 완화는 빠르게 적용되며, 안전장치가 함께 있어야 한다(예: 트래픽 우회, 기능 플래그 비활성화).

핵심 특징: 복구는 원인과 변경점을 동반하며, 되돌리기(롤백) 경로가 포함될수록 안정적이다.

주의점: 완화만 하고 검증을 생략하면 "일시적으로 잠잠해진 장애"가 더 큰 장애로 되돌아온다.

나쁜 템플릿 vs 좋은 템플릿: 문장 구조가 곧 속도다

런북 품질은 문서 길이가 아니라, 판단이 갈리는 지점에서 기준이 명확한지로 결정된다.

아래는 같은 내용을 담더라도 현장에서 효율이 크게 달라지는 예시다.

나쁜 예는 "해야 할 것"만 적고, 무엇을 보고 판단하는지가 비어 있다.

# 나쁜 예(요약만 존재)
- 모니터링 확인
- 로그 확인
- 서버 재시작
- 정상화 확인

나은 예는 "확인 경로 + 기준 + 다음 행동"이 한 덩어리로 붙어 있다.

# 나은 예(판단 포함)

[확인]
- 경로: 모니터링 대시보드 → 서비스/API → 5xx 비율
- 기준: 5xx > 3%가 5분 이상 지속되면 완화 단계로 이동
- 보조 확인: p95 지연시간, DB 연결 수, 큐 적체

[완화]

선택지 A: 읽기 전용 모드(기능 플래그 OFF)

선택지 B: 특정 엔드포인트 임시 차단(레이트 제한 강화)

안전장치: 적용 후 10분 내 되돌리기 조건 명시

[복구]

원인 후보별 조치 목록(예: DB 연결 풀 설정 조정, 배포 롤백)

롤백 절차와 확인 항목

[검증]

성공 조건: 5xx < 1%, p95 지연시간 정상 범위 회복, 오류 로그 급감

검증 실패 시: 완화 유지 + 복구 재시도 루프로 복귀

런북을 문서가 아닌 "실행 스크립트"로 보는 순간, 문장과 구조가 바뀐다.

비교 항목	읽히지 않는 런북	현장에서 쓰이는 런북
핵심 구성	해야 할 일 나열	경로·기준·다음 행동 세트
완화/복구 구분	섞여 있어 우왕좌왕한다	완화 먼저, 복구는 조건 충족 후 진행
검증 기준	"정상인지 확인"으로 끝난다	수치/로그/사용자 흐름으로 성공 조건 명시
권한/책임	누가 해도 되는지 불명확하다	수행자/승인자/에스컬레이션 경로가 있다

두 가지 스택으로 보는 런북 템플릿: Git형과 위키형

런북을 어디에 두느냐에 따라 운영 방식이 달라진다.

처음에는 한 곳에 정착시키는 것이 낫고, 이후 팀 문화에 맞춰 확장하면 된다.

스택 1) Git 저장소(변경 이력 중심) 템플릿

코드와 함께 움직이는 런북은 변경 이력이 남고, PR로 리뷰가 된다.

운영자가 찾기 쉬우려면 파일명과 디렉터리 규칙이 먼저 필요하다.

# 예시 경로
/runbooks/
  api-5xx-spike.md
  db-connection-exhausted.md
  queue-backlog.md

나쁜 예는 문서가 길고, 행동 단위가 뭉쳐 있다.

# 나쁜 예(핵심이 흩어짐)
- 상황 설명(길게)
- 추정 원인(길게)
- 여러 조치(혼재)

나은 예는 장애 단계가 파일 상단에 고정되어 "스크롤 최소"로 실행된다.

# api-5xx-spike.md (요약 템플릿)

## 확인
- 경로: 모니터링 → API → 5xx, p95
- 기준: 5xx > 3% (5분) AND p95 상승이면 완화로 이동

## 완화

기능 플래그: checkout_enabled=false

임시 제한: /checkout 레이트 제한 강화

되돌리기 조건: 5xx < 1%가 10분 유지되면 원복

## 복구

최근 배포 롤백: deploy-2026-01-05 → deploy-2026-01-04

DB 연결 풀 상한 점검: max_conns, pool_size

## 검증

5xx < 1%, p95 정상, 오류 코드 감소

사용자 흐름 점검: 로그인→결제 1회 성공

## 에스컬레이션

15분 내 완화 실패 시: SRE 온콜 호출

스택 2) 위키/노션(검색·협업 중심) 템플릿

위키형은 비개발자도 쉽게 편집할 수 있고, 링크 구조로 탐색이 편하다.

대신 버전 관리가 흐려지기 쉬워 "최종본 표시"와 "작성 규칙"이 있어야 한다.

# 나은 예(위키형 섹션 순서 고정)

[상단 고정]
- 장애 이름 / 대상 서비스 / 마지막 수정일 / 담당자
- 바로가기: 대시보드 링크, 로그 검색 링크, 배포 기록 링크

[확인]
- 알림 조건, 확인할 지표 3개, 정상 범위

[완화]
- 즉시 적용 가능한 조치 2~3개 + 부작용

[복구]
- 원인 후보별 조치 + 롤백

[검증]
- 수치 기준 + 사용자 시나리오 1개

[사후]
- 재발 방지 항목, 후속 작업 티켓 링크

두 스택 모두 "확인→완화→복구→검증"을 문서 상단부터 고정하는 것이 핵심이다.

YES/NO 체크리스트로 런북 초안을 빠르게 합격시키는 기준

런북 초안이 "실제로 실행 가능한 문서인지"는 아래 질문으로 갈린다.

• YES: 확인 단계에 "경로"가 있다(대시보드/로그/배포 기록을 어디서 여는지 명시)
• YES: 확인 단계에 "기준"이 있다(어떤 수치면 완화로 넘어가는지 명시)
• YES: 완화 조치에 "되돌리기 조건"이 있다(언제 원복할지 한 줄로 고정)
• YES: 복구 조치에 "변경 범위"가 있다(롤백, 설정 변경, 스케일 조정 중 무엇인지 명확)
• YES: 검증 단계에 "성공 조건"이 있다(지표 + 사용자 흐름 1개)
• NO: "로그를 확인한다"로 끝나고 무엇을 찾는지 적혀 있지 않다
• NO: 완화와 복구가 섞여 있어 어떤 것을 먼저 해야 하는지 헷갈린다
• NO: 검증이 "정상 확인"처럼 모호하고, 실패 시 다음 행동이 없다

런북 작성 절차 흐름도(확인→완화→복구→검증)

작성 요령을 실행으로 바꾸는 절차: "어디를 눌러 무엇을 확인하나"

런북을 처음 만드는 사람에게 가장 어려운 부분은 "확인 경로"를 구체적으로 적는 일이다.

도구가 무엇이든 공통 흐름을 고정하면 문구가 자연스럽게 채워진다.

1. 경로: 알림 시스템 → 알림 상세 → "대상 서비스/지표/기간" 확인
2. 체크 포인트: 알림이 무엇을 기준으로 울렸는지(5xx, 지연시간, 오류 코드)를 문장으로 고정한다.
3. 경로: 모니터링 대시보드 → 서비스 선택 → 에러율/지연시간/트래픽 3종 그래프
4. 체크 포인트: 기준을 한 줄로 만든다(예: "5xx>3% 5분 지속 + p95 상승이면 완화").
5. 경로: 로그 검색 화면 → request_id 또는 오류 코드로 필터 → 상위 에러 메시지 확인
6. 체크 포인트: "찾을 문구"를 적는다(예: "DB connection limit", "timeout", "upstream reset").
7. 경로: 배포 기록/릴리즈 노트 → 최근 변경 목록 확인 → 장애 시작 시점과 겹치는지 비교
8. 체크 포인트: 겹치면 복구 후보에 "롤백"을 포함하고, 겹치지 않으면 인프라/외부 의존성 후보로 이동한다.
9. 경로: 완화 선택지 실행 → 적용 시간 기록 → 10분 단위로 지표 재확인
10. 체크 포인트: 완화 성공/실패 판정 기준을 수치로 적는다(예: "5xx<1% 10분 유지").
11. 경로: 복구 조치 실행(롤백/설정 변경/스케일 조정) → 되돌리기 가능 여부 확인
12. 체크 포인트: 변경 전후 값을 기록하고, 되돌리기 경로를 런북에 남긴다.
13. 경로: 검증 단계 → 지표 확인 + 사용자 흐름 1회 실행 → 고객 문의 감소 여부 확인
14. 체크 포인트: "수치 2개 + 흐름 1개"가 충족되면 종료, 아니면 완화 유지 후 재진입한다.

실전 예시 1개: 결제 API 5xx 급증 런북을 처음 만들 때

문제: 결제 API 5xx가 8%로 상승했고, 고객이 "로딩이 끝나지 않는다"라고 문의한다.

왜 발생: 장애 시작 10분 전 배포가 있었고, 특정 외부 결제 호출에서 타임아웃이 증가했다.

어떤 선택이 적합: 즉시 완화로 결제 진입을 제한하거나 대체 경로로 우회해 피해 확산을 막고, 동시에 배포 롤백 여부를 검토하는 구성이 맞다.

잘못 쓰면 어떤 문제: 근거 없이 재시작만 반복하면 장애가 길어지고, 정상 사용자까지 결제 실패가 누적된다.

확인/해결: 알림 상세에서 지표 조건을 고정하고, 대시보드에서 5xx/p95/트래픽을 함께 본 뒤, 로그에서 타임아웃 문구를 확인해 완화 후 복구(롤백 또는 타임아웃 설정 조정)로 이동한다.

실전 예시에는 현장감 있는 한 줄이 들어가면 판단이 쉬워진다.

검색 문구: "timeout" AND route="/checkout"
관측: timeout 로그가 1분당 120건 수준으로 급증, latency_ms p95=2400 이상

결론

런북은 장애 대응을 빠르게 만드는 실행 문서이며, 확인→완화→복구→검증의 순서를 고정할수록 효과가 난다.

좋은 템플릿은 경로와 기준이 붙어 있어 "다음 행동"이 자동으로 결정된다.

완화와 복구를 분리하고, 검증 성공 조건을 수치와 사용자 흐름으로 고정하면 재발 가능성이 줄어든다.

연계 주제 제안: 알림 임계값을 오탐/미탐 관점에서 조정하는 방법, 장애 보고서(포스트모템) 작성 구조가 다음 단계로 이어지기 좋다.

FAQ

런북은 얼마나 자세해야 하나?

장애 상황에서 2~3분 안에 "무엇을 보고 무엇을 할지"가 결정되면 충분한 수준이다.

세부 분석은 별도 문서로 분리하고, 런북에는 경로·기준·조치·검증만 남기는 편이 읽힌다.

완화 조치가 서비스 품질을 떨어뜨리면 어떻게 하나?

완화는 피해 확산을 막는 임시 조치이므로, 부작용과 되돌리기 조건을 함께 적어두는 방식이 필요하다.

완화 후 즉시 복구 후보를 진행할 수 있도록 런북에 복구 루트를 붙여두면 흔들림이 줄어든다.

처음 만드는 런북은 어디에 두는 것이 좋나?

팀이 코드 중심이라면 Git 저장소형이, 협업과 링크 탐색이 강점이라면 위키형이 맞을 수 있다.

어느 쪽이든 "확인→완화→복구→검증"의 섹션 순서를 고정하고, 경로와 기준을 먼저 채우는 것이 출발점이 된다.