런북 & 운영 문서
AI 에이전트가 장애 대응에 참고하는 런북 구조 — 조건-행동-확인의 선언적 작성법
런북(Runbook)은 장애 발생 시 누가 읽어도 동일한 결과를 낼 수 있도록 작성하는 운영 문서입니다. AI 에이전트가 장애 대응을 보조하는 시대에는, 산문형 위키가 아닌 구조화된 조건-행동-확인 형식이 필수입니다.
왜 이 문서가 AI 시대에 중요한가
핵심 변화
런북은 더 이상 사람만 읽는 문서가 아닙니다. AI 에이전트가 실시간으로 런북을 파싱하여 장애 진단, 조치 제안, 에스컬레이션 판단을 수행합니다.
기존 런북의 문제는 암묵적 판단에 의존한다는 점입니다. "상황을 보고 판단한다", "심각하면 팀장에게 연락한다" 같은 서술은 사람도 해석이 다르고, AI는 아예 처리할 수 없습니다.
AI 시대 런북이 중요한 이유:
- 자동 장애 대응: AI 에이전트가 런북을 읽고 1차 진단/조치를 자동 수행
- 일관된 판단 기준: 에스컬레이션, 롤백 조건을 수치로 명시하면 AI가 정확히 판단
- 24/7 대응: AI가 런북 기반으로 야간/주말 장애를 1차 처리
- 온콜 부담 감소: 구조화된 런북 + AI = 주니어도 시니어 수준의 대응 가능
AI-readable 런북 작성 원칙
1. 선언적 단계: "이 조건이면 이 행동"
모든 조치를 if-then 형식으로 작성합니다. 산문형 서술을 제거하고, AI가 조건을 평가하여 행동을 선택할 수 있게 합니다.
## 조치
- **조건**: CPU 사용률 > 90% 상태가 5분 이상 지속
- **행동**: 해당 Pod를 재시작 (`kubectl rollout restart deployment/{name}`)
- **확인**: CPU 사용률이 70% 이하로 복귀 (3분 내)2. 판단 기준의 수치화
"심각하면", "오래되면" 같은 모호한 표현 대신 구체적 수치를 사용합니다.
| 모호한 표현 | 수치화된 표현 |
|---|---|
| 응답이 느리면 | 응답 시간 > 3초 (p95 기준) |
| 에러가 많으면 | 에러율 > 5% (5분 rolling window) |
| 오래 지속되면 | 10분 이상 지속 |
| 심각한 장애 | Severity 1: 전체 서비스 불가 |
3. 에스컬레이션 조건 명시
## 에스컬레이션 매트릭스
| 레벨 | 조건 | 대상 | 채널 |
|---|---|---|---|
| L1 | 자동 조치로 해결 불가 (10분) | 온콜 엔지니어 | Slack #oncall |
| L2 | L1 대응 후 30분 미해결 | 팀 리드 | 전화 + Slack |
| L3 | 서비스 전면 중단 > 1시간 | CTO + 전체 엔지니어링 | War room |4. 롤백 기준과 절차 분리
롤백은 별도 섹션으로 분리하고, 롤백 트리거 조건을 명확히 합니다.
## 롤백 기준
- 배포 후 에러율이 이전 대비 2배 이상 증가
- 주요 API 응답 시간이 이전 대비 50% 이상 증가
- 배포 후 10분 내 Sev1 장애 발생Before/After 비교
# DB 장애 대응
DB가 느려지면 먼저 슬로우 쿼리를 확인합니다.
커넥션 풀이 꽉 찬 것 같으면 늘려주세요.
그래도 안 되면 DBA에게 연락합니다.
심각한 경우 읽기 트래픽을 레플리카로 돌릴 수 있습니다.
상황을 보고 판단해주세요.문제점:
- "느려지면"의 기준이 없음
- "꽉 찬 것 같으면"은 AI가 판단 불가
- "심각한 경우"의 정의가 없음
- 실행 순서가 불명확
# 런북: DB 응답 지연
## 트리거
- DB 평균 응답 시간 > 500ms (5분 rolling)
- 알림: Grafana alert `db-slow-response`
## 증상
- API 타임아웃 증가 (5xx 에러율 상승)
- 커넥션 풀 사용률 > 80%
## 진단
| 순서 | 확인 항목 | 명령어 | 정상 기준 |
|---|---|---|---|
| 1 | 슬로우 쿼리 | `SHOW PROCESSLIST` | 10초 이상 쿼리 없음 |
| 2 | 커넥션 수 | `SHOW STATUS LIKE 'Threads_connected'` | < 최대의 80% |
| 3 | 레플리카 지연 | `SHOW SLAVE STATUS` | Seconds_Behind_Master < 5 |
## 조치
- **조건**: 슬로우 쿼리 존재
- **행동**: `KILL {process_id}`로 해당 쿼리 종료
- **확인**: 응답 시간 < 200ms 복귀 (3분 내)
---
- **조건**: 커넥션 풀 사용률 > 90%
- **행동**: `max_connections`을 현재의 1.5배로 증가
- **확인**: 커넥션 풀 사용률 < 70%
---
- **조건**: 위 조치 후에도 응답 시간 > 500ms
- **행동**: 읽기 트래픽을 레플리카로 전환 (config flag: `DB_READ_REPLICA=true`)
- **확인**: Primary DB 부하 50% 이상 감소
## 에스컬레이션
- 조치 3단계 후에도 미해결 (15분): DBA 호출 (#dba-oncall)
- 서비스 전면 중단: Sev1 선언 → L3 에스컬레이션런북 템플릿
복사해서 사용하세요
아래 템플릿을 복사하여 팀의 런북 기반으로 활용합니다. 모든 필드를 채워야 AI가 정확히 파싱합니다.
---
title: "런북: {서비스명} - {장애 유형}"
severity: "{sev1|sev2|sev3}"
services: ["{서비스1}", "{서비스2}"]
last_tested: "{YYYY-MM-DD}"
owner: "{팀/담당자}"
---
# 런북: {서비스명} - {장애 유형}
## 트리거
- {어떤 조건에서 이 런북을 실행하는가}
- 알림: {모니터링 알림 이름/ID}
## 증상
- {사용자가 경험하는 증상 1}
- {내부 메트릭 이상 징후 1}
## 영향 범위
- **영향 서비스**: {서비스 목록}
- **영향 사용자**: {전체/특정 기능 사용자}
- **비즈니스 영향**: {매출 손실 추정, SLA 위반 등}
## 진단
| 순서 | 확인 항목 | 명령어/도구 | 정상 기준 |
|---|---|---|---|
| 1 | {항목} | `{명령어}` | {기준} |
| 2 | {항목} | `{명령어}` | {기준} |
## 조치
### 조치 1: {조치 이름}
- **조건**: {이 조치를 실행하는 조건}
- **행동**: {구체적 명령어 또는 절차}
- **확인**: {성공 기준과 확인 시간}
- **롤백**: {이 조치를 되돌리는 방법}
### 조치 2: {조치 이름}
- **조건**: {조치 1로 미해결 시}
- **행동**: {구체적 명령어 또는 절차}
- **확인**: {성공 기준과 확인 시간}
- **롤백**: {이 조치를 되돌리는 방법}
## 에스컬레이션
| 조건 | 대상 | 채널 | SLA |
|---|---|---|---|
| {조건} | {담당자/팀} | {Slack/전화} | {응답 시간} |
## 사후 처리
- [ ] 포스트모템 작성 (24시간 내)
- [ ] 근본 원인 분석
- [ ] 재발 방지 조치 등록
- [ ] 런북 업데이트 (필요 시)
## 변경 이력
| 날짜 | 변경 내용 | 작성자 |
|---|---|---|
| {YYYY-MM-DD} | 초안 작성 | {이름} |AI 프롬프트 예시
AI가 실패하는 패턴
| 실수 | AI가 실패하는 이유 | 수정 방법 |
|---|---|---|
| "상황을 보고 판단한다" | AI가 주관적 판단 불가 | 수치 기준 명시 ("CPU > 90% 5분") |
| 에스컬레이션 없이 조치만 | AI가 해결 못하면 무한 반복 | 레벨별 에스컬레이션 조건 명시 |
| 롤백 방법 생략 | 조치 실패 시 원상복구 불가 | 모든 조치에 롤백 단계 포함 |
| "로그를 확인한다" | 어떤 로그, 어디서, 무엇을 찾는지 모름 | 구체적 명령어와 정상/비정상 기준 제공 |
프롬프트 1: 기존 위키를 런북으로 변환
다음 장애 대응 위키 문서를 구조화된 런북 형식으로 변환해줘.
요구사항:
1. 모든 판단 기준을 수치로 명시
2. "이 조건이면 이 행동" 형식의 선언적 조치
3. 각 조치에 확인 기준과 롤백 방법 포함
4. 에스컬레이션 매트릭스 추가
기존 문서:
{위키 내용 붙여넣기}프롬프트 2: 장애 시나리오별 런북 생성
다음 서비스 아키텍처를 기반으로 주요 장애 시나리오별 런북을 생성해줘.
서비스: {서비스명}
아키텍처: {간단한 구성 설명}
모니터링: {사용 중인 모니터링 도구}
각 런북에 포함할 항목:
- 트리거 조건 (메트릭 기준)
- 진단 단계 (명령어 포함)
- 조치 (조건-행동-확인-롤백)
- 에스컬레이션 매트릭스프롬프트 3: 런북 검증 및 개선
다음 런북을 검토하고 개선해줘.
검토 기준:
1. 모호한 표현이 남아있는가? (수치로 대체)
2. AI가 조건을 자동 평가할 수 있는가?
3. 에스컬레이션 조건이 명확한가?
4. 롤백 절차가 모든 조치에 포함되어 있는가?
5. 진단 단계에 구체적 명령어가 있는가?
런북:
{런북 내용 붙여넣기}체크리스트
트리거 조건이 명확한가?
- 모니터링 알림과 연결되어 있다
- 수치 기반 트리거 조건이 정의되어 있다
- AI가 자동으로 트리거를 감지할 수 있다
진단 단계가 구체적인가?
- 각 단계에 실행할 명령어가 포함되어 있다
- 정상/비정상 기준이 수치로 명시되어 있다
- 진단 순서가 우선순위에 따라 정렬되어 있다
조치가 선언적인가?
- 모든 조치가 "조건-행동-확인" 형식이다
- 조건이 수치 기반으로 AI가 평가 가능하다
- 각 조치에 롤백 방법이 명시되어 있다
- 조치 간 순서/의존 관계가 명확하다
에스컬레이션이 정의되어 있는가?
- 레벨별 조건이 시간/상태 기준으로 명시되어 있다
- 각 레벨의 담당자와 연락 채널이 있다
- 응답 SLA가 정의되어 있다
메타데이터가 충분한가?
- severity, services, owner가 frontmatter에 있다
- 최종 테스트 날짜(
last_tested)가 기록되어 있다 - 변경 이력이 관리되고 있다