플랫폼 런북: 장애 triage, 지연 원인분석, 재처리 기준
런북이 없으면 장애 때마다 탐색부터 시작한다
데이터 플랫폼 장애는 기술적으로 단순한 경우도 있지만, 원인을 특정하기까지 시간이 걸린다. 파이프라인 지연이 발생했을 때 어디를 먼저 봐야 하는지, 재처리를 해야 한다면 어떤 범위로 해야 안전한지, 다운스트림에 어떻게 알려야 하는지 — 이 판단 과정이 런북으로 문서화되어 있지 않으면 매번 같은 탐색을 반복하게 된다.
런북은 온콜 엔지니어가 "지금 무엇을 해야 하는가"를 알 수 있게 하는 운영 지침이다. 이 장에서는 데이터 플랫폼에 특화된 런북의 세 가지 핵심 요소를 정리한다: 장애 triage, 지연 원인분석, 재처리 기준.
1. 장애 심각도 분류: Triage
모든 알림이 동일한 긴급도를 갖지 않는다. 온콜 엔지니어가 첫 5분 안에 결정해야 할 것은 "이것이 얼마나 급한가, 무엇에 영향을 미치는가"다. 심각도 분류(triage)는 이 판단을 빠르게 하기 위한 틀이다.
Triage 첫 5분 체크리스트
| 질문 | 확인 방법 |
|---|---|
| 어떤 파이프라인이 실패/지연되었는가? | Airflow DAG 뷰, 알림 링크 |
| 다운스트림에 이미 영향이 있는가? | BI 대시보드 오류, 서비스팀 슬랙 확인 |
| 최근 코드 배포나 스키마 변경이 있었는가? | Git 배포 기록, 스키마 변경 이력 |
| 같은 시간대에 다른 파이프라인도 영향받고 있는가? | 동일 인프라 공유 여부 확인 |
| 이전에 같은 장애가 있었는가? | 런북 이력, 이슈 트래커 검색 |
P0/P1 판단이 서면 즉시 장애 채널을 열고, 영향 받는 팀에 "현재 조사 중"임을 선제적으로 알린다. 원인이 밝혀지지 않은 상태에서도 먼저 소통하는 것이 다운스트림 팀의 불필요한 탐색을 막는다.
2. 지연 원인분석 트리
파이프라인이 늦거나 실패한 원인은 크게 네 가지 범주로 나눌 수 있다. 탐색 순서를 정해두면 시간이 절약된다.
범주별 진단 방법
① 업스트림 소스 문제
소스 DB나 API가 원인이면 파이프라인 자체를 고쳐도 해결되지 않는다. 먼저 소스 측 모니터링(MySQL slow query log, API 에러율, Kafka consumer lag)을 확인한다. 소스 데이터 볼륨이 평소보다 급증했다면 처리 시간이 늘어난 것일 수 있고, 이 경우 재처리보다 리소스 조정이 먼저다.
소스 스키마가 바뀐 경우(컬럼 추가, 타입 변경)는 ingestion 코드가 파싱에 실패하거나 NOT NULL 제약 위반으로 테이블 적재가 중단된다. 오류 메시지에서 schema mismatch, type error, column not found 패턴을 찾는다.
② 실행 환경 문제
Airflow에서는 Executor 큐가 가득 차면 task가 queued 상태에서 멈춘다. airflow tasks states-for-dag-run 으로 확인하고, Worker가 부족하면 동적 스케일링이나 pool 크기를 조정한다. Kubernetes에서 Pod이 OOMKilled로 재시작되었다면 kubectl logs --previous로 이전 로그를 확인한다. Spot 인스턴스 사용 환경에서는 cloud provider의 preemption 이벤트 기록을 함께 확인한다.
③ 데이터 품질 문제
파이프라인 실행 자체는 성공했지만 결과 테이블에 데이터가 없거나 이상한 경우다. row count가 0이거나 평소의 10% 이하라면 upstream에서 데이터가 오지 않았거나, 필터 조건에서 걸려서 전부 드롭된 것이다. 에러 로그에 validation failed, freshness check failed, uniqueness check failed 패턴을 찾는다.
④ 로직/코드 문제
최근 배포가 있었다면 가장 먼저 의심한다. Git diff에서 변경된 SQL 로직이나 DAG 구조를 확인한다. 파티션 스큐는 특정 executor만 오래 걸리는 패턴으로 나타난다(Spark UI에서 task duration의 편차가 크면 의심). 느린 쿼리는 실행 계획으로 확인하고, 인덱스 누락이나 풀스캔이 없는지 본다.
3. 재처리 기준: 언제, 어떻게 안전하게 하는가
지연이나 실패를 복구하는 방법은 크게 두 가지다: 재실행(re-run) 과 재처리(reprocessing/backfill). 이 둘은 다르다.
- 재실행: 같은 실행 주기(interval)를 다시 돌리는 것. 원인이 해결되었고 실행 자체가 멱등하면 안전하다.
- 재처리: 이미 처리된 과거 데이터 범위를 다시 처리하는 것. 범위가 넓거나 다운스트림에 이미 전달된 데이터가 있으면 신중해야 한다.
재처리 결정 전 확인 사항
| 확인 항목 | 이유 |
|---|---|
| 파이프라인이 멱등(idempotent)한가? | 같은 범위를 두 번 돌렸을 때 데이터가 중복되지 않아야 한다 |
| 재처리 범위(날짜/파티션)가 특정되었는가? | 범위를 모르면 과도한 재처리로 리소스를 낭비하거나 정상 데이터를 덮어쓸 수 있다 |
| 다운스트림이 이미 이 데이터를 소비했는가? | 이미 소비된 데이터를 바꾸면 다운스트림 불일치가 생긴다 — 다운스트림에 먼저 알려야 한다 |
| 재처리 중 다운스트림이 중간 상태 데이터를 읽을 수 있는가? | 쓰기 중간에 읽히면 불완전한 데이터가 노출된다. staging → swap 방식이 안전하다 |
| SLA 내에 완료 가능한가? | 재처리가 SLA보다 오래 걸리면 또 다른 SLA 위반을 만든다 |
멱등성 패턴
재처리를 안전하게 하려면 파이프라인이 멱등해야 한다. 가장 일반적인 패턴은 다음과 같다.
-- INSERT OVERWRITE (파티션 단위 덮어쓰기)
INSERT OVERWRITE TABLE events PARTITION (dt = '2026-06-30')
SELECT * FROM events_raw WHERE dt = '2026-06-30';
-- MERGE / UPSERT (중복 방지)
MERGE INTO orders AS target
USING orders_delta AS source
ON target.order_id = source.order_id
WHEN MATCHED THEN UPDATE SET ...
WHEN NOT MATCHED THEN INSERT ...;APPEND 방식으로 쌓는 파이프라인은 재처리 전에 기존 데이터를 먼저 삭제해야 한다. 삭제 없이 다시 쌓으면 중복이 생긴다. 이를 피하는 설계는 파티션 단위로 OVERWRITE하거나 MERGE를 쓰는 것이다.
재처리 범위 결정
부분 재처리 는 영향받은 파티션(날짜, 시간 범위)만 다시 처리하는 것이다. 범위가 명확하고 멱등성이 보장되면 가장 빠르고 안전하다. 범위를 특정하기 어렵거나 데이터 손상이 누적된 경우에는 전체 재처리(full backfill) 가 필요하다. 이때는 재처리 시간이 SLA에 영향을 미치지 않도록 별도 클러스터나 비업무 시간을 활용한다.
4. 실전 런북 구조
런북은 장황하면 장애 상황에서 읽히지 않는다. 핵심은 "지금 이 상황에서 무엇을 해야 하는가"를 빠르게 찾을 수 있는 구조다.
런북 필수 섹션
장애 유형별 증상 → 원인 매핑 테이블
| 증상 | 가장 많은 원인 | 첫 번째 확인 명령 |
|---|---|---|
| DAG task가 queued에서 안 넘어감 | Executor 큐 포화, Worker 부족 | airflow workers list, pod 상태 |
| task가 실행되다가 갑자기 killed | OOM, Spot 회수 | kubectl describe pod <pod> |
| 결과 테이블 row count가 0 | 소스 데이터 없음, 필터 오류 | 소스 row count 조회, WHERE 조건 검토 |
| 집계 값이 어제와 크게 다름 | 소스 중복, 스키마 변경 | COUNT(*), COUNT(DISTINCT id) 비교 |
| task가 반복적으로 재시도 후 실패 | 소스 타임아웃, 외부 서비스 불안 | 에러 로그 마지막 3줄, 외부 서비스 상태 |
파이프라인별 SLA와 재처리 절차
각 파이프라인의 SLA(최대 허용 지연 시간), 멱등성 여부, 안전한 재처리 명령을 기록해둔다.
# 예시: orders_daily DAG 재처리
# 멱등: YES (OVERWRITE 방식)
# 재처리 명령:
airflow dags backfill orders_daily \
--start-date 2026-06-28 \
--end-date 2026-06-30 \
--reset-dagruns에스컬레이션 기준
- 30분 내에 원인을 특정하지 못하면 → 팀 리드에게 에스컬레이션
- P0 장애가 1시간 내 해결 전망 없으면 → 관련 서비스팀과 비즈니스 오너에게 직접 알림
- 데이터 손상이 의심되면 → 스스로 복구 시도하지 않고 팀 리드 확인 먼저
5. 장애 후 처리: 포스트모템과 런북 업데이트
장애가 해결된 후에도 런북 작업이 남아 있다.
포스트모템 체크리스트
| 항목 | 내용 |
|---|---|
| 타임라인 | 감지 → 원인 파악 → 완화 → 완전 복구 시각 |
| 직접 원인 | 기술적 근본 원인 (what happened) |
| 기여 요인 | 왜 감지가 늦었는지, 왜 영향이 컸는지 |
| 영향 범위 | 지연 시간, 영향받은 파이프라인·테이블·팀 |
| 재발 방지 액션 | 알림 임계값 조정, 코드 가드 추가, 문서 업데이트 |
포스트모템은 비난이 아니라 시스템 개선을 위한 것이다. 런북에 이번 장애 패턴을 추가하고, 해당 파이프라인의 멱등성 여부와 재처리 절차를 검토한다. 런북이 장애 때마다 조금씩 업데이트되어야 실제 운영 상황을 반영한 살아있는 문서가 된다.
마무리: 런북은 다음 온콜 엔지니어를 위한 것이다
런북의 진짜 독자는 지금 글을 쓰는 사람이 아니라, 다음에 비슷한 상황을 처음 만나는 온콜 엔지니어다. "이 알림이 뜨면 이것을 먼저 확인한다", "재처리 전에 반드시 멱등성을 확인한다", "이 파이프라인은 OVERWRITE 방식이라 재처리가 안전하다" — 이런 정보가 런북에 있으면 장애 대응 시간이 크게 줄어든다.
데이터 플랫폼 운영의 성숙도는 장애가 얼마나 없느냐보다, 장애가 났을 때 얼마나 빠르고 체계적으로 대응하느냐에서 드러난다.
References
- Monte Carlo Data, "How to Conduct Data Incident Management for Data Teams," https://www.montecarlodata.com/blog-how-to-conduct-incident-management-on-your-data-pipelines/
- Google SRE Workbook, "Incident Response," https://sre.google/workbook/incident-response/
- Rootly, "Incident Response Runbooks: Templates, Examples & Guide," https://rootly.com/incident-response/runbooks
- Ariane Horbach, "Building Idempotent Data Pipelines: A Practical Guide to Reliability at Scale," https://medium.com/towards-data-engineering/building-idempotent-data-pipelines-a-practical-guide-to-reliability-at-scale-2afc1dcb7251
- Integrate.io, "ETL Error Handling and Monitoring Metrics — 25 Statistics Every Data Leader Should Know in 2026," https://www.integrate.io/blog/etl-error-handling-and-monitoring-metrics/
- incident.io, "Runbook automation tools 2026: the complete guide," https://incident.io/blog/runbook-automation-tools-2026-the-complete-guide