이 글은 Kafka S3 Sink Connector Small Files 문제 시리즈의 2편입니다.
TL;DR
- 문제: BACKWARD 모드 설정에도 S3 Sink Connector가 파일을 계속 쪼갬
- 원인:
connect.meta.data=true(기본값)로 인해 메타데이터 차이가 “다른 스키마”로 판정 - 해결:
value.converter.connect.meta.data=false설정 추가 - 결과: Projection이 정상 동작하여 파일 rotation 방지
1편에서 원인을 찾고, schema.compatibility=BACKWARD로 설정을 바꿨습니다. 테스트 환경에서 검증만 하면 된다고 생각했습니다.
BACKWARD 호환이란?
새 스키마가 이전 스키마로 작성된 데이터를 읽을 수 있는 호환성 모드입니다. 예를 들어, 필드가 추가된 v2 스키마는 v1 데이터를 읽을 수 있어야 합니다.
그런데 테스트 환경에서 설정을 바꾸고 확인해보니… 여전히 파일이 쪼개져 있었습니다.
“분명히 문서 설정대로 했는데?”
알고 보니 공식 문서에서 인지하기 어려운 설정 하나, connect.meta.data라는 복병이 기다리고 있었습니다.
사용 중인 기술 스택
1편과 동일한 파이프라인 구조입니다.
이번 편에서 주목할 구성 요소:
- AvroConverter: Avro 포맷과 Connect 내부 스키마(Connect Schema) 간 변환을 담당하는 컴포넌트
- connect.meta.data: AvroConverter가 메타데이터를 포함할지 결정하는 설정 (이번 편의 주인공!)
무엇이 문제였을까?
BACKWARD 모드의 기대 동작을 먼저 정리해보겠습니다.
| 상황 | 기대 동작 |
|---|---|
| 신규 스키마(v2) 메시지 도착 | 새 파일 생성 (정상) |
| 이전 스키마(v1) 메시지 도착 | v2로 Projection하여 같은 파일에 기록 |
Projection은 이전 버전 스키마의 메시지를 최신 스키마에 맞춰 변환하여 같은 파일에 쓰는 기능입니다. 이게 제대로 동작해야 불필요한 파일 생성을 막을 수 있죠.
1편에서 결정한 대로 schema.compatibility=BACKWARD를 적용하고, QA 환경에서 이 동작을 검증하기로 했습니다.
테스트 시나리오
이 가설을 검증하기 위해 QA 환경에서 직접 테스트해보기로 했습니다. 시나리오는 간단했습니다.
| 단계 | 작업 | 예상 결과 |
|---|---|---|
| 1 | 신규 스키마 v2 등록 | - |
| 2 | Producer 재시작 → v2로 발행 | - |
| 3 | S3 확인 | 새 파일 생성 (신규 버전이므로 정상) |
| 4 | Producer가 캐시된 v1 스키마로 발행 | - |
| 5 | S3 확인 | 같은 파일에 기록되어야 함 (Projection) |
3단계까지는 예상대로였습니다. 문제는 5단계에서 발생했습니다.
예상과 다른 결과
5단계에서 새 파일이 생성되어버렸습니다.
v2 파일: topic-name+0+0000351342.snappy.parquet (즉시 flush)
v1 파일: topic-name+0+0000351343.snappy.parquet ← 새로 생성됨!BACKWARD 모드임에도 이전 버전 스키마가 Projection되지 않고 파일 rotation이 발생했습니다.
“왜지? 설정은 분명히 맞는데…”
원인을 찾아서
첫 번째 의심: 커넥터 설정 문제
처음에는 커넥터 설정을 의심했습니다. 혹시 schema.compatibility 설정이 잘못되었나?
하지만 schema.compatibility=BACKWARD는 정확히 설정되어 있었습니다.
두 번째 의심: Schema Registry 문제
그렇다면 Schema Registry에서 버전 관리가 잘못된 걸까요? Schema Registry를 확인해봤지만, 스키마 버전들이 정상적으로 등록되어 있었습니다.
진짜 원인: 소스 코드 추적
추측으로는 한계가 있었습니다. 결국 S3 Sink Connector의 소스 코드(StorageSchemaCompatibility.java)를 살펴봤습니다.
간략화된 스키마 비교 흐름:
1. 스키마 타입 비교 → 동일
2. 스키마 이름 비교 → 동일
3. 스키마 parameters 비교 → 불일치! 🔴 (여기서 rotation)
4. 스키마 버전 비교 ← 도달하지 못함스키마 버전 비교까지 도달하기도 전에, parameters 비교에서 이미 “다른 스키마”로 판정되고 있었습니다.
Connect Schema의 parameters란?
AvroConverter가 변환 과정에서 doc, default, version 등의 메타데이터를 저장하는 Connect Schema의 Map 필드입니다.
connect.meta.data=true일 때 이 필드가 채워지며, 스키마 비교 시 이 parameters까지 비교하면 메타데이터 차이만으로도 “다른 스키마”로 판정됩니다.
connect.meta.data의 정체
범인은 connect.meta.data=true (기본값) 설정이었습니다.
이 설정이 true일 때, AvroConverter는 다음 메타데이터를 Connect Schema의 parameters에 추가합니다:
doc(문서화 주석)versiondefault value- 기타 메타정보
문제는 스키마 버전 간에 doc 필드나 기타 메타데이터가 다르면, parameters 비교에서 불일치로 판정된다는 점이었습니다.
핵심 문제:
- 실제 필드 구조는 호환 가능한데
- 메타데이터 차이 때문에 “다른 스키마”로 인식
- Projection 로직까지 도달하지 못하고 새 파일 생성
해결책
해결책은 간단합니다.
// 관련 설정 발췌 (실제 커넥터에는 더 많은 필수 설정이 필요합니다)
{
"value.converter": "io.confluent.connect.avro.AvroConverter",
"value.converter.schema.registry.url": "http://schema-registry:8081",
"value.converter.connect.meta.data": "false",
"schema.compatibility": "BACKWARD"
}value.converter.connect.meta.data=false를 추가하면 됩니다.
동작 변화
| 설정 | parameters 포함 | 스키마 비교 방식 | 결과 |
|---|---|---|---|
true (기본값) | O | doc 등 메타데이터까지 비교 | Projection 실패 |
false | X | 실제 필드 구조만 비교 | Projection 정상 동작 |
손실되는 것은?
- Connect Schema에서 doc 주석이 제외됨 → Schema Registry에서 확인 가능
- Connect 내부 version 정보 → Schema Registry 버전과 별개
실제 데이터에는 영향이 없습니다.
적용 후 확인
설정 변경 후 동일한 테스트를 다시 진행했습니다.
Before vs After
| 상황 | Before (connect.meta.data=true) | After (connect.meta.data=false) |
|---|---|---|
| v2 메시지 | 새 파일 생성 | 새 파일 생성 |
| v1 메시지 | 새 파일 생성 (문제!) | v2 파일에 Projection (정상!) |
드디어 BACKWARD 모드가 의도한 대로 동작했습니다.
참고 자료
GitHub Issues
GitHub 이슈에서도 직관적이지 않은 BACKWARD 동작을 지적하고 있고, connect.meta.data=false로 수정하는 것을 안내하고 있습니다.
Confluent 공식 문서
- Avro Converter - connect.meta.data (AvroConverter 설정 옵션)
- S3 Sink Connector Configuration
시리즈를 마치며
1편과 2편을 통해 Kafka S3 Sink Connector의 Small Files 문제를 해결했습니다.
두 편에 걸친 트러블슈팅 끝에 결국 설정 두 줄로 문제를 해결했습니다. 간단한 해결책이었지만, 그 과정에서 S3 Sink Connector의 스키마 비교 로직을 깊이 이해하게 되었습니다.
핵심 설정 요약
# 1편에서 발견: 스키마 호환 모드 설정
schema.compatibility=BACKWARD
# 2편에서 발견: 메타데이터 비교 비활성화
value.converter.connect.meta.data=false자주 묻는 질문
Q: connect.meta.data=false로 설정하면 데이터 손실이 있나요?
A: 실제 데이터에는 영향이 없습니다. Connect Schema 내부의 doc, version 등 메타데이터만 제외되며, 이 정보는 Schema Registry에서 확인할 수 있습니다.
Q: schema.compatibility=BACKWARD만 설정하면 되는 거 아닌가요?
A: BACKWARD 설정만으로는 부족합니다. connect.meta.data=true(기본값)일 때 메타데이터 차이로 인해 Projection이 동작하지 않습니다. 두 설정을 함께 사용해야 합니다.
Q: 이 설정은 S3 Sink Connector에만 해당하나요?
A: connect.meta.data는 AvroConverter의 설정이므로, Avro 포맷을 사용하는 다른 Storage Connector(GCS, Azure Blob 등)에서도 동일한 문제가 발생할 수 있습니다.