이 문서를 통해 아래 질문들에 답할 수 있게 됩니다.
- 기능 개발 PR에서 API와 DB 외에 event, mart, search, recommendation 영향을 어떻게 점검하는가?
- schema, enum, 상태 전이 변경이 downstream 품질 rule과 backfill에 어떤 영향을 주는가?
- 배포 전에 데이터 영향 체크리스트가 없으면 어떤 조용한 장애가 생기는가?
- 작은 프로젝트에서도 최소한 어떤 데이터 영향 기록을 남겨야 하는가?
개요
기능 개발은 API endpoint와 DB migration만으로 끝나지 않는다.
운영 데이터는 event, outbox, Kafka, batch, mart, search index, recommendation feature, quality rule로 이어진다.
따라서 기능 PR은 “서비스가 동작하는가”뿐 아니라 “이 변경을 downstream이 올바르게 해석할 수 있는가”를 확인해야 한다.
체크리스트가 필요한 변경
다음 변경은 데이터 영향 검토가 필요하다.
- 새 table 또는 column 추가.
- column 의미 변경.
- enum 또는 상태 전이 추가.
- soft delete, hard delete, 보관 기간 변경.
- 금액, 수량, 등급 계산 로직 변경.
- event payload field 추가, 삭제, rename.
- API 응답에는 작지만 mart grain을 바꾸는 변경.
- 검색 노출 조건, 추천 제외 조건 변경.
“DB migration이 작다”와 “데이터 영향이 작다”는 같은 말이 아니다.
PR 체크리스트
Data Impact Checklist
[ ] source table 또는 event가 새로 생기는가?
[ ] 기존 event schema나 enum 의미가 바뀌는가?
[ ] integration event version 변경이 필요한가?
[ ] mart grain, metric definition, aggregation 기준이 바뀌는가?
[ ] search index에 추가/삭제/비공개 반영이 필요한가?
[ ] recommendation feature에 포함하거나 제외할 조건이 바뀌는가?
[ ] quality rule을 추가하거나 threshold를 바꿔야 하는가?
[ ] 기존 데이터 backfill 또는 reprocessing이 필요한가?
[ ] owner, freshness SLA, replay range가 문서화되어 있는가?체크리스트는 모든 항목을 무겁게 처리하자는 뜻이 아니다.
영향 없음이라고 판단한 근거를 남기자는 뜻이다.
예시: 주문 상태 추가
change: orderStatus에 PARTIALLY_REFUNDED 추가
API:
- refund API에서 새 상태 반환
DB:
- orders.status enum 값 추가
Event:
- OrderRefunded v1 payload에 refundType 추가 필요
- 기존 consumer는 unknown refundType을 무시할 수 있는가?
Reporting:
- net_revenue 계산식 변경
- refund amount accuracy rule 추가
Search:
- 주문 검색 filter에는 영향 없음
Recommendation:
- partially refunded order를 positive purchase signal로 볼 것인지 결정 필요
Backfill:
- 최근 180일 refund event 재처리작은 enum 하나가 리포트와 추천 의미를 바꿀 수 있다.
배포 전 확인
배포 전에 확인할 것은 코드 통과만이 아니다.
- schema registry 또는 contract test가 통과했는가?
- consumer가 새 field를 무시하거나 처리할 수 있는가?
- quality rule SQL이 배포 순서에 맞게 준비됐는가?
- backfill은 dry run으로 row 수와 예상 시간을 확인했는가?
- 알림 owner와 runbook이 연결되어 있는가?
- rollback 대신 forward fix가 필요한 데이터 변경인가?
특히 데이터 변경은 code rollback으로 끝나지 않을 수 있다.
이미 발행된 event와 생성된 mart row는 별도 보정이 필요하다.
배포 후 확인
배포 후에는 다음 지표를 짧은 시간 동안 본다.
- outbox pending age.
- Kafka consumer lag.
- unknown enum 또는 schema parse failure.
- mart freshness.
- source와 target count 차이.
- quality rule failure.
- search index update lag.
- recommendation feature null ratio.
이 지표를 보지 않으면 API는 정상인데 downstream만 틀어진 상태를 놓친다.
작은 프로젝트 기준
개인 프로젝트에서는 문서 하나로 시작해도 된다.
feature: coupon refund
source change: orders.refund_amount 추가
event change: OrderRefunded v1 추가
downstream:
- daily revenue mart 재계산
- refund dashboard 추가
quality:
- source refund sum = mart refund sum
backfill:
- last 30 days
owner:
- backend + data중요한 것은 도구가 아니라 변경과 downstream 영향이 연결되어 있는 것이다.
운영 지표
data_checklist_completion_rate: 기능 PR 중 데이터 영향 체크가 완료된 비율.post_release_quality_failure_count: 배포 후 발생한 품질 rule 실패 수.backfill_required_after_release: 배포 후 뒤늦게 발견된 backfill 필요 건수.consumer_schema_failure_count: 배포 후 consumer schema 해석 실패 수.missing_owner_change_count: owner 없이 배포된 데이터 영향 변경 수.
이 지표는 체크리스트가 형식인지 실제 품질을 줄이는지 확인한다.
위험 신호!
- PR 설명에 API 변경만 있고 event와 mart 영향이 없다.
- enum 추가를 backward compatible하다고만 보고 metric 의미 변경을 놓친다.
- 삭제 정책 변경 후 search index 삭제 반영을 확인하지 않는다.
- backfill 필요성을 배포 후 대시보드 이상으로 처음 발견한다.
- 데이터 변경을 code rollback으로만 복구할 수 있다고 생각한다.
확인 질문
확인 질문
- 새 enum 값 하나가 reporting과 recommendation에 서로 다른 영향을 줄 수 있는 이유는 무엇인가?
- forward fix가 필요한 데이터 변경은 code rollback과 무엇이 다른가?
- 배포 후 outbox pending age와 quality rule을 함께 봐야 하는 이유는 무엇인가?
- 영향 없음 판단도 PR에 남겨야 하는 이유는 무엇인가?
참고 문서
- Spring for Apache Kafka Reference
- Apache Kafka Documentation
- PostgreSQL Documentation
- Martin Kleppmann, Designing Data-Intensive Applications