데이터 파이프라인 디버깅은(는) 무엇을 하나요?
사용 시기
- 파이프라인 작업이 실패했거나, 출력 데이터가 잘못되었거나 누락/중복된 경우
- 대시보드가 오래되었거나 메트릭이 소스와 일치하지 않는 경우
- 이해관계자가 불일치를 보고하여 원인을 찾아야 하는 경우
debugging-dbt-runs/debugging-airflow-pipelines에서 이미 다루는 도구별 실행 오류에는 사용하지 마세요(해당 스킬로 먼저 시작하고, 데이터 정확성 문제는 이 스킬을 사용하세요).
워크플로우
- [ ] 증상을 정확히 정의 (어떤 테이블, 컬럼, 행, 시간 범위)
- [ ] 계보를 상위로 추적하여 데이터가 잘못된 첫 번째 단계 찾기
- [ ] 격리: 코드 버그, 잘못된 입력, 늦은 데이터, 실행 실패 중 무엇인가?
- [ ] 의심되는 단계를 소스와 대조 검증 (레코드 수/합계)
- [ ] 근본 원인 수정 후, 영향 받은 기간에 대한 멱등성 백필 계획
- [ ] 재발 방지를 위한 검사 추가
- 증상 고정. "2026-01-15 매출이
fct_orders에서 약 30% 낮음"은 디버깅 가능하지만 "숫자가 이상함"은 아닙니다. 테이블, 컬럼, 행, 시간 범위를 파악하세요. - 계보를 상위로 추적. 잘못된 출력에서 모델/태스크를 거꾸로 따라가며 데이터가 이미 잘못된 첫 번째 단계를 찾으세요. 모든 단계를 읽지 말고 DAG를 이진 탐색하세요.
- 원인 분류: 코드 변경, 잘못되거나 늦은 소스 데이터, 실패/부분 실행, 비멱등성 중복.
- 의심스러운 단계를 입력과 대조 검증 (행 수, 키 수, 합계)하여 차이가 발생한 지점을 확인하세요.
- 영향 받은 기간을 멱등하게 수정 및 백필 (
designing-backfills-and-replays참조). - 재발 방지를 위해 대상 데이터 품질 검사를 추가하세요.
패턴
계보 이진 탐색 — DAG 중간 단계를 확인합니다. 데이터가 정확하면 버그는 하위에, 잘못되었으면 더 상위로 올라갑니다. 반복합니다.
영향 기간에 대한 소스 대비 대상 검증:
-- 해당 기간에 대해 단계와 입력 간의 레코드 수/합계가 일치합니까?
SELECT 'source' AS layer, COUNT(*) n, SUM(amount) total
FROM staging.orders WHERE order_date = DATE '2026-01-15'
UNION ALL
SELECT 'target', COUNT(*), SUM(amount)
FROM marts.fct_orders WHERE order_date = DATE '2026-01-15';
레코드 수 차이 → 행이 드롭/필터링되었거나 부분 로드 실패. 레코드 수는 같고 합계 차이 → 변환/로직 버그. 대상 레코드 수가 더 높음 → 중복(비멱등성 로드).
타임라인 확인 — 사고 기간을 배포, 소스 스키마 변경, 실행 기록과 상관 분석합니다. 대부분의 사고는 변경 시점에 시작됩니다.
흔한 실수
- 증상을 하위에서만 수정 — 버그가 스테이징에 있을 때 마트만 패치하면 재발합니다; 첫 번째 잘못된 단계를 수정하세요.
- 프로덕션 데이터에 수동으로 일회성 수정 — 감사 불가능하고 재현 불가능; 대신 코드를 수정하고 멱등하게 재실행하세요.
- 전체 DAG를 선형으로 읽기 — 대신 계보를 이진 탐색하세요.
- 검증 단계 생략 — 데이터가 어디서 차이 나는지 추측하는 것은 시간 낭비; 단계별 레코드 수/합계를 측정하세요.
- 수정 후 예방 검사 누락 — 같은 유형의 버그가 발견되지 않고 재발합니다.