05. 데이터 파이프라인 설계 리뷰 템플릿 상세

이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.

• 데이터 파이프라인 설계 리뷰에서 source, key, schema, SLA, replay, quality rule을 어떻게 빠짐없이 확인하는가?
• 설계 문서가 도구 구성도에서 끝나지 않고 실패 모델과 운영 책임까지 포함하려면 무엇이 필요한가?
• Java/Spring 백엔드 서비스가 producer일 때 어떤 event 계약과 transaction 경계를 리뷰해야 하는가?
• 리뷰 결과를 배포 체크리스트, runbook, 품질 rule로 어떻게 연결하는가?

개요

데이터 파이프라인 설계 리뷰는 “Kafka를 쓸 것인가, Airflow를 쓸 것인가”를 고르는 회의가 아니다.

source가 무엇이고, key와 schema가 안정적인지, 실패했을 때 어디부터 다시 처리할 수 있는지, 완료를 어떤 rule로 확인할지를 검토하는 절차다.

좋은 리뷰 템플릿은 설계자가 놓친 운영 질문을 강제로 드러낸다.

1. 목적과 사용자

pipeline_name:
business_goal:
primary_users:
wrong_data_impact:
freshness_expectation:

먼저 이 파이프라인이 누구의 어떤 의사결정에 쓰이는지 쓴다.

사용자가 없으면 SLA도 severity도 정할 수 없다.

2. Source 계약

확인할 질문:

• source는 운영 DB table인가, event topic인가, 외부 API인가?
• source owner는 누구인가?
• source schema 변경은 어떻게 공지되는가?
• eventTime과 ingestionTime은 각각 무엇인가?
• 삭제, 취소, 환불, 만료는 어떻게 표현되는가?

source:
  type: kafka_topic
  name: order-paid
  owner: order-service
  event_time: payment approved time
  schema_version: OrderPaid v2
  delete_policy: OrderCanceled event

3. Key와 Grain

key와 grain은 재처리와 중복 방지의 기준이다.

primary_key: eventId
business_key: orderId
partition_key: orderId
target_grain: one row per paid order per event version
dedup_key: consumerName + eventId

리뷰 질문:

• 같은 business key에서 여러 event가 나올 수 있는가?
• update event와 append event를 구분하는가?
• target row는 event grain인가, daily aggregate grain인가?
• partition key가 hot key를 만들 가능성이 있는가?

4. Schema와 Compatibility

확인할 질문:

• optional field 추가는 consumer가 무시할 수 있는가?
• required field 삭제나 rename이 있는가?
• enum 추가 시 unknown value 처리 기준이 있는가?
• 개인정보 field가 downstream에 불필요하게 전달되지 않는가?
• schema registry 또는 contract test가 있는가?

schema 변경은 코드 컴파일보다 늦게 터질 때가 많다.

consumer가 실제 payload를 해석할 수 있는지 별도로 확인해야 한다.

5. 처리 경계

백엔드 producer라면 transaction 경계가 특히 중요하다.

확인할 질문:

• API DB commit과 event 기록은 같은 transaction에 묶이는가?
• outbox 또는 CDC를 사용하는가?
• broker publish 실패는 어디에 기록되는가?
• consumer DB commit과 offset commit 순서는 무엇인가?
• 외부 side effect가 consumer transaction 밖에 있는가?

이 경계가 불명확하면 장애 때 중복, 누락, phantom event를 설명하기 어렵다.

6. Failure Mode

failure_modes:
  - source schema changed without notice
  - outbox publisher delayed
  - Kafka consumer poison message
  - target DB write timeout
  - quality rule accuracy failed

각 failure mode마다 다음을 적는다.

• 어떻게 감지하는가?
• 누가 owner인가?
• 자동 retry 대상인가?
• DLT 또는 failed table로 격리하는가?
• 재처리 시작점은 어디인가?

7. Replay와 Backfill

확인할 질문:

• replay 가능한 source 보관 기간은 얼마인가?
• checkpoint는 offset, timestamp, id range 중 무엇인가?
• target writer는 idempotent한가?
• backfill batch size와 throttle 기준이 있는가?
• 완료 검증 query가 있는가?

재처리 설계가 없으면 파이프라인은 운영 가능한 설계가 아니다.

8. Quality Rule

최소 rule:

• freshness: 최신 event가 지연 기준 안에 있는가?
• completeness: source와 target count 차이가 허용 범위 안인가?
• accuracy: 금액, 수량, 핵심 metric 합계가 맞는가?
• validity: null, enum, range가 계약 안에 있는가?
• consistency: 관련 mart와 같은 정의를 쓰는가?

SELECT abs(source.amount - mart.amount) / nullif(source.amount, 0) AS diff_ratio
FROM source_daily_amount source
JOIN mart_daily_amount mart USING (order_date);

품질 rule은 “나중에 운영하면서 추가”가 아니라 설계 리뷰에서 최소 기준을 정해야 한다.

9. 운영 문서

설계 승인 전에 다음 문서가 있어야 한다.

• event catalog 또는 source contract.
• owner와 escalation path.
• runbook.
• backfill command 예시.
• quality rule SQL.
• dashboard 또는 alert 목록.

문서가 많아야 한다는 뜻이 아니다.

장애 중 필요한 정보가 한 곳에서 찾아져야 한다는 뜻이다.

리뷰 결과

decision: approved with conditions
conditions:
  - add unknown enum handling in consumer
  - add outbox pending age alert
  - document replay range 180 days
  - add freshness and amount accuracy rules
owner: data-platform
due: before production release

리뷰 결과는 회의록으로 끝나지 않고 배포 조건으로 연결되어야 한다.

위험 신호!

• 설계 문서가 도구 구성도와 happy path만 설명한다.
• key와 grain이 한 문장으로 정리되어 있지 않다.
• replay와 backfill을 “필요하면 다시 돌림”으로만 적는다.
• quality rule이 운영 후 과제로 밀린다.
• owner와 alert가 없어 장애 때 담당자를 찾는다.

확인 질문

확인 질문

• 파이프라인 설계에서 key와 grain을 먼저 확정해야 하는 이유는 무엇인가?
• outbox publisher lag와 consumer lag는 각각 어떤 실패를 나타내는가?
• replay source 보관 기간이 설계 리뷰에 포함되어야 하는 이유는 무엇인가?
• 설계 리뷰 결과가 배포 조건으로 연결되지 않으면 어떤 문제가 남는가?

참고 문서

• Apache Kafka Documentation
• Apache Airflow Documentation
• Spring for Apache Kafka Reference
• Martin Kleppmann, Designing Data-Intensive Applications