운영의 언어, 런북과 포스트모템 - 개발자를 위한 기술문서 입문 ep.07

운영 문서는 평소엔 안 읽힙니다. 읽힐 때는 누군가 잠에서 깬 새벽 3시이거나, 무언가가 막 망가진 직후입니다.

그래서 톤이 다릅니다. 친절할 필요가 없습니다. 군더더기가 없어야 합니다. 감정이 빠져 있어야 합니다. 사실이 우선해야 합니다. 이번 편이 다룰 두 문서, 런북(Runbook) 과 포스트모템(Postmortem) 은 둘 다 차가운 글쓰기입니다.

런북: 새벽 3시에 호출된 사람을 위한

런북은 인시던트가 진행 중일 때 읽는 글입니다. 독자는 보통 다음 상태입니다.

막 잠에서 깬 채로 노트북을 열었다
알람의 텍스트만 보고 무엇이 문제인지 모른다
시간이 흐르고 있다 — 그리고 그 시간이 곧 비용이다
평소 그 시스템을 깊이 모를 수도 있다

이 상태의 독자에게 필요한 건 교육이 아닙니다. 행동입니다. 그래서 런북은 튜토리얼이 아니라 카드 묶음에 가깝습니다.

런북의 응급 카드 구조

좋은 런북 하나는 다음 네 구간으로 구성됩니다.

각 구간을 짧게 풀어봅니다.

알람 헤더: 어떤 알람이고, 심각도가 무엇이고, 누가 on-call인지가 맨 위에 있어야 합니다. 잠에서 깬 사람이 지금 자기 일이 맞는지 30초 안에 판단할 수 있어야 합니다.
First Action (30초 안에): 가장 자주 효과가 있는 즉시 행동. 일단 출혈을 멈추는 것. 진단 없이도 안전하게 할 수 있는 것이어야 합니다.
Diagnose: 결정 트리 형태가 좋습니다. “이게 보이면 → A로, 저게 보이면 → B로.” 길지 않게. 3~5 분기면 충분합니다.
Mitigate: 결정 트리의 각 가지가 가리키는 완화 액션. 복사해서 실행할 수 있는 명령어가 있어야 합니다. 그리고 검증 — 이게 됐는지 어떻게 확인하는가 — 가 같이 있어야 합니다.

런북에서 빠뜨리지 말아야 할 것

에스컬레이션 경로: “이 절차로 안 풀리면 누구에게 연락하는가.” 이름·연락처·시간대까지. 새벽 3시에 동료의 휴대폰 번호를 검색하지 않게.
시간 추정: “이 절차는 약 N분 안에 완료됩니다.” 마지막에 두는 것을 권장. 시간이 한계를 넘으면 다른 길을 시도하라는 신호.
부작용 경고: “이 명령은 5분간 X% 트래픽을 거부합니다” 같은. 작성자가 알고 있는 비싼 비용을 명시.
금지 액션: “이 상황에서 절대 하지 말 것”이라는 음의 가이드. 흔히 잊히지만 재앙을 막는 단 한 줄이 되곤 합니다.

런북이 발견되는 자리

좋은 런북은 글이 좋은 것만으로는 부족합니다. 알람이 울린 30초 안에 손에 닿아야 합니다. 운영 도구별로 그 결합이 다릅니다.

PagerDuty: 인시던트 자체에 Runbook URL 필드가 있고, 알람을 정의할 때 해당 알람 → 런북 매핑을 박을 수 있습니다. 알람 SMS에서 한 번의 탭으로 런북에 가는 길이 가장 가까운 형태입니다.
Grafana · Datadog · PromQL 알람: 알람 정의의 annotations 또는 runbook_url 필드에 URL 한 줄. 알람 본문에 자동으로 따라옵니다. Prometheus Alertmanager의 표준 관습이기도 합니다.
Confluence · Notion: 카탈로그 역할이 강합니다. 런북 페이지마다 service·severity·last-drilled 같은 프로퍼티를 두고, 데이터베이스 뷰로 6개월 이상 드릴되지 않은 런북을 자동으로 떠올립니다. 글이 묻히지 않게 하는 장치.
GitHub의 docs/runbooks/: 코드와 같은 저장소에 두고, 알람의 runbook_url이 GitHub 영구 링크를 가리키게 합니다. 코드와 런북이 같은 PR로 갱신되는 가장 단단한 결합 — 다만 새벽 3시 노트북에서 GitHub 로그인이 막히지 않도록 공개 또는 SSO 우선으로 두는 게 안전합니다.

도구가 무엇이든 알람 본문에 한 줄의 링크만큼 강력한 건 없습니다. 그리고 그 링크가 깨지지 않게 한 명이 분기마다 점검해야 합니다.

런북이 자주 무너지는 지점

만들어두고 갱신되지 않는다.
가장 흔하고 가장 치명적입니다. 6개월 전의 명령어가 그대로 적혀 있으면 잠 깬 on-call은 하다가 안 됩니다. 분기마다 한 번씩 드릴(drill) 로 검증하는 것을 권장.
너무 친절하다.
”이 명령어는 PostgreSQL의 …” 같은 설명이 끼어들면 새벽 3시 독자는 읽다가 잠이 듭니다. 설명은 별도 문서로 빼고 링크만 둡니다.
결정 트리가 없다.
단순한 절차서면 상황에 안 맞으면 그대로 멈춥니다. 적어도 두세 가지 분기는 있어야 합니다.
검증 단계가 없다.
”이 명령 실행” 후 진짜 됐는지 어떻게 아는지가 없으면 on-call은 증상이 사라진 줄 알고 자러 갑니다.
알람과 런북이 연결되어 있지 않다.
알람 본문이나 PagerDuty 노트에 해당 런북 링크가 없으면 잠 깬 사람은 검색하느라 5분을 씁니다.

공개된 운영 런북을 살펴보자

런북은 보통 사내 깊숙이 묻혀 있어 외부에서 볼 일이 적습니다. 다만 공개된 런북 묶음이 몇 곳 있고, 처음 런북을 쓰기 시작한 팀이 어휘와 디렉터리 구조를 그대로 흉내 내기에 좋습니다.

Prometheus Operator runbooks: Kubernetes 알람 한 건당 한 마크다운 파일이 디렉터리에 누적됩니다. 알람 정의의 runbook_url 필드가 바로 이 저장소의 해당 파일을 가리키게 두는 표준 사례. 위에서 본 Prometheus Alertmanager의 표준 관습이 실전에서 어떻게 굳어졌는지를 볼 수 있는 가장 가까운 자료입니다.
GitLab Production runbooks: GitLab.com SRE 팀이 실제로 운영하는 런북 묶음을 그대로 공개해 둔 저장소. docs/·dashboards/·mimir-rules/·legacy-cookbooks/가 한 저장소에 같이 사는 모습은 본문에서 권한 GitHub docs/runbooks/ 결합 — 코드와 런북이 같은 PR로 갱신된다 — 의 살아 있는 예시입니다.
PagerDuty Incident Response: 런북 한 편이 아니라 런북·인시던트 대응을 어떻게 조직 차원으로 굴리는가의 핸드북. 본문에서 쓰는 Severity · On-call · Escalate 어휘의 거의 원전이고, 사내에서 처음 인시던트 절차를 세울 때 이 사이트의 페이지 구조를 그대로 가져다 쓰는 팀이 많습니다.

세 사례의 공통점은 셋입니다. (1) 알람이 글의 시작점입니다 — 런북은 알람의 부록이지 서비스의 매뉴얼이 아닙니다. (2) 디렉터리 컨벤션이 곧 검색 도구입니다 — 파일명·경로·태그만으로 새벽 3시에 필요한 한 편이 잡힙니다. (3) 어휘가 통일되어 있습니다 — Severity·Mitigation·Escalation 같은 단어의 의미가 모든 런북에서 같습니다. 사내 런북을 처음 만들 때 이 셋 중 하나의 어휘와 디렉터리 컨벤션을 그대로 빌려오는 것이 가장 빠른 시작입니다.

짧은 시나리오 — PaymentService 팀의 분기 gameday

가상의 PaymentService 팀이 분기마다 하루를 잡아 gameday를 합니다. 인시던트가 나기를 기다리지 않고, 의도적으로 장애를 주입해 런북이 실제로 동작하는지 확인합니다.

이번 분기의 시나리오는 다음 세 줄로 시작합니다.

2026-04-15 14:00 KST — staging 환경에서 결제 게이트웨이 응답을 임의로 60% 차단한다. on-call rotation의 다음 차례인 현우가 아무런 사전 정보 없이 알람을 받는다. 목표는 30분 안에 완화까지 가는 것.

알람이 울리고 30초 안에 현우는 PagerDuty에서 런북 링크를 탭합니다. 첫 5분이 지나고 발견된 문제 두 가지:

런북의 Diagnose 결정 트리에서 Q2가 가리키는 그라파나 대시보드 링크가 깨져 있다. 누군가 dashboard UID를 바꿨는데 런북이 갱신되지 않은 것. → 액션: 런북에 dashboard UID 대신 슬러그로 링크.
First Action 단계의 kubectl rollout undo가 새 배포 시스템(Argo Rollouts) 도입 후로는 동작하지 않는다. → 액션: 런북의 First Action을 kubectl argo rollouts undo로 갱신, 둘이 공존하는 시기에는 둘 다 적어두기.

30분이 지나기 전에 현우는 서킷 브레이커 토글까지 도달해 완화에 성공합니다. gameday가 끝나고 팀은 gameday 자체의 포스트모템을 짧게 씁니다. 런북의 두 곳이 갱신되고, Last Drilled: 2026-04-15 라벨이 런북 상단에 박힙니다.

이 시나리오의 핵심은 인시던트가 나기를 기다리지 않는다는 점입니다. 분기마다 한 명을 모르는 상태로 던져 보면, 글로만 좋아 보이는 런북의 깨진 부분이 30분 안에 드러납니다. 그게 새벽 3시에 처음 드러나는 것보다 훨씬 싸게 발견됩니다.

런북 템플릿

# Runbook: [알람/상황 이름]

**Severity**: SEV-N
**Service**: [서비스 이름]
**On-call**: [팀 이름]
**Last Drilled**: YYYY-MM-DD

## 알람의 의미

[이 알람이 트리거되는 조건. 트리거 임계치도 명시.]

## First Action (30초 안에)

[진단 없이 안전하게 실행할 수 있는 즉시 행동.]

```bash
[명령어]
```

## Diagnose

### Q1. [확인 1]

```bash
[조회 명령]
```

- → 결과 A: [다음 단계] (Mitigate A)
- → 결과 B: [다음 단계] (Mitigate B)

### Q2. ...

## Mitigate

### A. [완화 방법 A]

```bash
[명령어]
```

**검증**: [어떻게 확인하는가]
**실패 시**: [다음 시도]

### B. ...

## 절대 하지 말 것

- [재앙적 액션]
- [재앙적 액션]

## Escalate

이 절차로 N분 안에 풀리지 않으면 다음으로 연락:

1. [이름 · 채널 · 시간대]
2. [이름 · 채널]

## 관련

- [관련 ADR]
- [아키텍처 다이어그램]
- [최근 인시던트 포스트모템]

포스트모템: 실패에서 배우는 글쓰기

인시던트가 끝나고 며칠 안에 쓰는 글이 포스트모템입니다. 목적은 단순합니다. 다음에 같은 일이 안 일어나게 하는 것.

그런데 이 단순한 목적이 자주 망가집니다. 누가 잘못했는지를 찾는 글로 변질되기 때문입니다. 그 순간 포스트모템은 처벌의 도구가 되고, 다음 인시던트의 진실은 숨겨집니다. 다음 인시던트는 더 늦게 발견되고, 더 크게 터집니다.

좋은 포스트모템의 첫째 원칙은 비난 없음(Blameless) 입니다.

비난 없는 글쓰기는 무엇인가

비난 없는 글쓰기는 “아무도 잘못한 사람이 없다고 적기”가 아닙니다. 사람이 한 행동은 정확히 적되, 그 사람을 비난하지 않는다는 뜻입니다.

비난하는 문장:
> 김OO이 단위를 잘못 설정해 인시던트가 발생했다.

비난 없는 문장:
> 환경 변수 POOL_SIZE의 단위가 변경되었으나 변수명이 단위를 명시하지 않아,
> 작성자와 리뷰어 모두 새 단위 기준을 인지하지 못했다.
> 이는 "단위가 변수명에 없음" 이라는 시스템적 결함을 드러낸다.

후자는 같은 사실을 적되, 문제를 시스템에 위치시킵니다. 김OO은 자기 이름을 보지 않습니다. 시스템은 고칠 거리를 얻습니다.

이 글쓰기가 어색하다면 다음 규칙이 도움이 됩니다.

이름 대신 역할. “김OO이 …” → “On-call 엔지니어가 …”
사람의 실수 대신 시스템의 빈틈. “잘못 입력했다” → “입력 검증이 없었다”
비난 가능 동사 회피. “실수했다”, “놓쳤다”, “잘못했다” 대신 “예상하지 못했다”, “탐지되지 않았다”

공개 포스트모템을 읽어보자

비난 없는 글쓰기가 추상적으로 느껴진다면, 외부에 공개된 포스트모템을 한두 편 직접 읽어보는 게 가장 빠릅니다. 위에서 살펴본 Timeline · 5 Whys · What Worked · Action Items 가 실제로 어떻게 채워지는지 한 편씩 다른 각도에서 보여줍니다.

Cloudflare — Details of the Cloudflare outage on July 2, 2019: WAF 정규식의 catastrophic backtracking으로 글로벌 트래픽이 약 27분 영향을 받은 사건. 본문 다이어그램의 5 Whys가 실전에서 어떻게 정규식 한 줄 → 배포 절차 → 테스트 부재 → 정책 부재까지 깊어지는지의 정직하게 보여줍니다. 원인뿐 아니라 27분이 27분에서 멈춘 이유까지 같이 적혀 있는 점이 인상적입니다.
GitHub — October 21 post-incident analysis: 약 24시간을 넘긴 다중 리전 데이터베이스 인시던트. Background → Impact → Timeline → Root Cause → Next Steps 골격이 정확히 그대로 채워져 있어 포맷의 한 편으로 가장 흉내 내기 쉽습니다. Next Steps가 단순 목록이 아니라 카테고리(technical · process · resilience) 로 묶여 있어 액션 아이템을 어떻게 그룹화할지의 참고가 됩니다.
AWS — Summary of the Amazon S3 Service Disruption (Feb 28, 2017): us-east-1의 S3가 약 4시간 영향을 받은 사건. 사람 이름이 한 번도 등장하지 않고 시스템 차원의 조치만 남는 차가운 톤을 잘 보여줍니다. “an authorized S3 team member … entered the command incorrectly”라는 한 줄에 오타에 대한 비난 대신 왜 이 명령이 그렇게 큰 영향을 줬는지가 곧장 이어 붙는 흐름이 비난 없는 글쓰기의 표본입니다.
GitLab — Postmortem of the database outage of January 31: 한 엔지니어가 잘못된 호스트에서 rm -rf를 실행해 primary DB가 사라진 사건. 인시던트가 진행 중일 때 구글 닥과 유튜브 스트림으로 외부에 실시간으로 공개됐다는 점에서 특이합니다. 비난 없는 글쓰기가 회사 바깥까지 노출됐을 때도 어떻게 가능한지의 가장 강한 증거이고, What Went Well · What Went Wrong · Where We Got Lucky 라는 세 갈래 회고 구조는 흔치 않은 변형입니다.
Slack — Slack’s Outage on January 4th 2021: 새해 첫 출근일 캐스케이딩 실패. AWS Transit Gateway 스케일링 실패 → 내부 서비스 디스커버리 폭주 → 대시보드까지 함께 마비되는 연쇄가 분 단위로 추적됩니다. What Worked에 해당하는 단락이 한 자리에 모이지 않고 인시던트 곳곳에 흩어져 있어, 본문이 권한 “잘 작동한 시스템을 보호해야 한다”는 원칙을 실전 글의 구조로 보여주는 변형 사례입니다.

다섯 글의 공통점은 셋입니다. (1) 개인 이름이 거의 등장하지 않거나 등장해도 직책·팀 단위입니다. (2) Timeline · What Worked · Action Items의 위치가 거의 같습니다 — 다섯 글을 나란히 펴두면 같은 골격이 보입니다. (3) Root Cause가 사람이 아니라 시스템에 닿습니다 — 누가 명령을 잘못 입력했는지가 아니라 왜 그 명령이 그런 영향을 줄 수 있었는지까지 갑니다. 처음 포스트모템을 쓸 때 비난조 검토를 혼자 하기 어려우면, 이 다섯 글을 옆에 켜두고 톤을 그대로 흉내 내는 것이 가장 빠른 우회로입니다.

포스트모템의 구조

좋은 포스트모템은 다음 흐름을 따르는 경우가 많습니다.

1. Summary       — 무엇이 일어났나 (한 단락)
2. Impact        — 누가 얼마나 영향을 받았나
3. Timeline      — 시간순 사실 기록
4. Root Cause    — 근원적 원인 (5 Whys 또는 인과 다이어그램)
5. What Worked   — 잘 작동한 것
6. What Didn't   — 잘 작동하지 않은 것
7. Action Items  — 누가, 무엇을, 언제까지

타임라인과 5 Whys가 포스트모템의 두 기둥입니다.

Timeline — 감정 없이 사실만

타임라인은 법정 진술처럼 씁니다. 해석과 판단은 다른 섹션으로 미룹니다.

약한 타임라인:
> 14:23, 김OO이 너무 성급하게 배포를 한 것 같다.
> 14:31, 다행히도 알람이 발생해서 다행이었다.

강한 타임라인:
> 14:23 — payment-service v2.34.0 배포 (PR #4521)
> 14:31 — 5xx 에러율이 임계치(5%)를 초과
> 14:31 — PagerDuty 알람 발생, on-call 호출

후자는 형용사·부사가 없습니다. “성급하게”, “다행히도” 같은 단어가 들어가는 순간 글은 해석이 됩니다. 해석은 다음 섹션에 분리합니다.

Root Cause — 5 Whys로 거슬러 가기

근원적 원인을 찾는 가장 단순하고 강력한 도구가 5 Whys 입니다. 증상에서 시작해 “왜?”를 다섯 번 물으면 시스템의 빈틈이 드러납니다.

위 다이어그램의 5 Whys 예시에서 보듯, 근원은 보통 코드 한 줄의 버그가 아닙니다. 프로세스의 부재, 문서의 부재, 피드백 루프의 부재 같은 시스템 차원의 것입니다.

5 Whys의 흔한 실수 두 가지:

너무 일찍 멈춘다.
”코드 버그였다”에서 끝나면 왜 그 버그가 통과되었나까지 못 갑니다. 행동이 아니라 시스템에 닿아야 멈춥니다.
인간을 근원으로 둔다.
”사람이 잘못했다”가 답이면 다음 인시던트도 사람이 잘못해서 일어납니다. 시스템을 답으로 만듭니다.

근원이 여러 개일 수도 있습니다. 그 경우 각각을 별도로 5 Whys로 풉니다.

Action Items — 누가, 무엇을, 언제까지

가장 자주 무너지는 섹션입니다. “다음부터는 잘 합시다” 같은 문장으로 끝나면 포스트모템의 임무가 실패입니다.

좋은 액션 아이템은 세 가지를 명시합니다.

약한 액션 아이템:
- 배포 프로세스를 개선한다.
- 테스트를 강화한다.

강한 액션 아이템:
- [Owner: @platform-team] 모든 결제 서비스에 카나리 배포 (10%, 30%, 100%)
  적용. 마감: 2026-06-15. 이슈: #5234
- [Owner: @backend-team] 환경 변수 검증 단위 테스트 추가
  (POOL_SIZE는 정수 범위 검증). 마감: 2026-05-30. PR: #5235

오너, 마감일, 추적 가능한 링크. 이 셋이 없으면 액션은 추상이고, 추상은 실행되지 않습니다.

포스트모템이 자주 무너지는 지점

비난이 끼어든다.
한 문장만 비난조여도 분위기가 바뀝니다. 작성 후 비난 검토를 한 번 더.
타임라인에 해석이 섞인다.
”성급하게”, “운 좋게” 같은 단어를 검색해 지웁니다.
근원이 사람이다.
”사람이 잘못했다”는 근원이 아니라 증상입니다. 시스템에 닿을 때까지 더 파고듭니다.
액션 아이템이 추상적이다.
오너·마감·링크 없는 액션은 없는 것과 같습니다.
What Didn’t Work만 있다.
What Worked도 똑같이 중요합니다. 어떤 시스템·관행이 잘 작동해서 인시던트가 11분에 끝났는지도 적어둡니다. 그 시스템을 보호해야 합니다.
인시던트 후 너무 늦게 쓴다.
일주일이 지나면 디테일이 사라집니다. 24~72시간 안에 초안을 만드는 것을 권장.

포스트모템 템플릿

# Postmortem: [인시던트 제목]

**Date**: YYYY-MM-DD
**Duration**: HH:MM ~ HH:MM (총 N분)
**Severity**: SEV-N
**Author**: [이름]
**Status**: Draft | Reviewed | Published

## Summary

[한 단락으로 무엇이 일어났는가.]

## Impact

- 영향받은 사용자: ~N명 또는 N%
- 영향받은 트래픽: N%
- 비즈니스 임팩트: [실패한 거래, 미인식 매출 등]

## Timeline

| 시각 (KST) | 사건 |
| --- | --- |
| HH:MM | ... |
| HH:MM | ... |

## Root Cause

### 5 Whys

1. 왜 [증상]이 일어났나? → ...
2. 왜 ...?
3. 왜 ...?
4. 왜 ...?
5. 왜 ...? ← 근원

[근원의 짧은 설명]

## What Worked

[잘 작동한 시스템·관행·사람의 판단]

## What Didn't Work

[잘 작동하지 않은 부분]

## Action Items

| 작업 | 오너 | 마감 | 추적 |
| --- | --- | --- | --- |
| ... | @... | YYYY-MM-DD | #... |

## Lessons Learned

[조직 차원에서 기억할 것 — 미래의 다른 팀에게도 도움이 되는 것]

## Related

- [관련 런북]
- [관련 ADR]
- [관련 인시던트]

운영 문서의 공통 원칙

런북과 포스트모템을 관통하는 공통점 셋을 정리하며 마칩니다.

감정을 빼고 사실을 남긴다. 잠 깬 사람도, 인시던트 직후의 사람도, 두 달 뒤 그 글을 읽을 사람도 모두 사실에서 출발해야 결정할 수 있습니다.
시스템에 책임을 위치시킨다. 사람의 잘못을 찾는 글은 고칠 거리를 만들지 못합니다. 시스템의 빈틈을 찾는 글은 다음 인시던트를 막습니다.
살아 있는 문서로 둔다. 운영 문서는 한 번 쓰고 끝이 아닙니다. 분기마다 드릴로 런북을 검증하고, 포스트모템의 액션 아이템을 추적합니다. 추적되지 않는 액션은 액션이 아닙니다.

체크리스트

런북

알람 본문에 이 런북 링크가 있는가
맨 위에 심각도·서비스·on-call·드릴 일자가 있는가
30초 안에 할 수 있는 First Action이 있는가
결정 트리 형태의 진단이 있는가
각 완화 액션에 복사 가능한 명령과 검증이 있는가
절대 하지 말 것이 있는가
에스컬레이션 경로가 명시되어 있는가
분기마다 드릴되고 있는가

포스트모템

인시던트 후 72시간 안에 초안이 작성되었는가
타임라인에 형용사·부사·해석이 없는가
비난조 문장이 없는가 (이름 대신 역할, 사람 대신 시스템)
5 Whys가 사람이 아닌 시스템에 닿았는가
Action Item마다 오너·마감·추적 링크가 있는가
What Worked도 적혀 있는가
Action Item의 추적이 실제로 이루어지고 있는가

참고 자료

Google SRE Team. Site Reliability Engineering: Postmortem Culture. https://sre.google/sre-book/postmortem-culture/
Etsy. Code as Craft: Blameless PostMortems. https://www.etsy.com/codeascraft/blameless-postmortems/
Atlassian. Incident Management Handbook. https://www.atlassian.com/incident-management
Beyer, B., Jones, C., Petoff, J., & Murphy, N. R. (2016). Site Reliability Engineering. O’Reilly.
Allspaw, J. (2012). Blameless PostMortems and a Just Culture. https://www.etsy.com/codeascraft/blameless-postmortems/

다음 편 예고

ep.08 - 매일 쓰는 협업의 글, PR · 커밋 · 온보딩

다음 편은 매일 쓰는 글입니다. 좋은 커밋 메시지, 리뷰가 즐거워지는 PR, 첫 주를 단축시키는 온보딩 문서. 의식하지 않으면 형편없이 쓰이지만 의식하면 협업의 비용을 절반으로 줄이는 글들을 다룹니다.