백엔드 데이터 인프라 95편 — Kafka Topic 설정 (Retention · Compression · Cleanup)

이 글은 백엔드 데이터 인프라 시리즈 130편 중 95편이에요. 94편 에서 broker(클러스터를 이루는 Kafka 서버) 설정을 잡았다면, 이번 95편은 Topic 레벨 설정이에요. broker default 를 topic 마다 override 하는 영역이고, 각 topic 의 retention(보존)·compression(압축)·cleanup(정리) 같이 자주 손대는 항목을 다뤄요.

Topic Config가 어렵게 느껴지는 이유

Broker config 와 이름이 비슷한 게 많아서 헷갈려요. log.retention.ms (broker) 와 retention.ms (topic) 처럼 접두사만 다른 짝이 대표 예시예요.

첫째, default vs override 관계예요. broker log.retention.hours=168 이 기본값이고, 특정 topic 만 retention.ms=86400000 (1일) 로 바꿀 수 있어요.

둘째, 언제 override 하는지가 명확하지 않아요. 일반 topic 은 default 를 그대로 따르고, 특수 topic 만 override 한다고 보면 돼요.

이 글에서 topic config 자주 조정하는 15가지와 Topic 생성·변경 패턴까지 정리해요.

Topic Config 의 자리

Topic 마다 별도 설정을 가질 수 있어요. 명시 안 하면 broker default 를 따라가요.

# Topic 생성 시
$ kafka-topics.sh --create --topic orders \
    --bootstrap-server localhost:9092 \
    --partitions 3 --replication-factor 3 \
    --config retention.ms=86400000 \
    --config compression.type=zstd

# 기존 Topic 변경
$ kafka-configs.sh --bootstrap-server localhost:9092 \
    --entity-type topics --entity-name orders \
    --alter --add-config "retention.ms=172800000"

# 조회
$ kafka-configs.sh --bootstrap-server localhost:9092 \
    --entity-type topics --entity-name orders --describe

1. Retention — 데이터 보존

retention.ms

retention.ms=604800000        # 7일 (broker 기본 = log.retention.hours)
retention.ms=-1                # 무제한

시간 기반 보존이에요. retention.ms 만 명시하면 시간 기반만 동작하고 크기는 무제한이에요.

retention.bytes

retention.bytes=1073741824    # 1GB per partition
retention.bytes=-1            # 무제한 (기본)

크기 기반 보존인데, partition(topic 을 나눠 저장하는 단위) 한 개당 기준이에요. topic 전체가 아니에요.

둘 다 명시

둘 중 먼저 도달한 쪽이 발동해요.

retention.ms=604800000        # 7일
retention.bytes=10737418240   # 10GB

7일 전 데이터든 10GB 초과든 먼저 발생한 것부터 삭제돼요.

여기서 시험 함정이 하나 있어요. retention.bytes 는 partition 단위라서, partition 10개에 retention.bytes=1GB 면 topic 전체로는 10GB 가 돼요.

2. Segment — 파일 분할

segment.bytes

segment.bytes=1073741824      # 1GB (기본)

84편에서 본 segment(로그를 잘라 저장하는 파일 단위) 크기예요. 크게 잡으면 open file 수가 줄고, 작게 잡으면 retention 이 정밀해져요.

segment.ms

segment.ms=604800000           # 7일 (기본)

시간 기반 segment roll(파일 새로 자르기) 이에요. 데이터가 적어도 7일이 지나면 새 segment 를 만들어요.

3. Compression

compression.type

compression.type=producer      # 기본, producer 가 보낸 그대로
# 또는
compression.type=zstd          # broker 가 재압축
compression.type=lz4
compression.type=snappy
compression.type=gzip
compression.type=uncompressed

대부분 producer 가 정답이에요. broker 가 다시 압축하는 비용이 없거든요. 정말 필요한 경우만 broker 재압축을 써요.

4. Cleanup Policy

cleanup.policy

cleanup.policy=delete          # 기본, 시간/크기 retention
# 또는
cleanup.policy=compact         # log compaction (107편)
# 또는
cleanup.policy=delete,compact  # 둘 다

Log Compaction (키별 최신 값만 남기는 정리 방식, 107편) 은 상태 저장·구성 데이터·CDC(Change Data Capture, 변경 데이터 캡처) 같은 자리에 어울려요.

Compaction 관련 추가 설정

min.compaction.lag.ms=0        # 압축 전 최소 보존 시간
max.compaction.lag.ms=...       # 압축 트리거 최대 대기
min.cleanable.dirty.ratio=0.5   # dirty ratio 기준 (0.5 = 50%)
delete.retention.ms=86400000    # tombstone 보존 (1일)

dirty ratio 는 compaction 대상 비율이고, tombstone 은 삭제 표시 메시지예요. 자세히는 107편에서 풀어요.

5. Replication

min.insync.replicas

min.insync.replicas=2          # 86·89편 참고

Topic 별로 broker default 를 override 할 수 있어요. 중요 topic 만 강화하는 방식이에요.

unclean.leader.election.enable

unclean.leader.election.enable=false

이것도 Topic 단위 override 예요. 금융 topic 만 false 로 유지하는 식의 패턴을 자주 써요.

6. 메시지 크기

max.message.bytes

max.message.bytes=1048588      # 1MB (broker 기본과 동일)

이 topic 만 큰 메시지를 허용하려면 이렇게 늘려요.

max.message.bytes=10485760     # 10MB

여기서 정말 중요한 자리예요. broker 의 message.max.bytes 도 함께 늘려야 해요. Topic 만 늘리면 broker 가 거부해요.

7. Index 설정

index.interval.bytes

index.interval.bytes=4096      # 4KB (기본)

.index 파일의 entry 간격이에요. 작게 잡으면 lookup 이 빠른 대신 index 크기가 커져요.

segment.index.bytes

segment.index.bytes=10485760   # 10MB (기본)

Index 파일 최대 크기예요.

8. 메시지 timestamp

message.timestamp.type

message.timestamp.type=CreateTime    # 기본, producer 가 박은 시간
# 또는
message.timestamp.type=LogAppendTime  # broker 가 받은 시간

LogAppendTime 은 broker 시계 기반이에요. 시계 동기화가 보장되니까 시간 기반 retention 이나 seek(특정 시점으로 이동) 이 정확해져요.

CreateTime 은 producer 가 박은 시간이라 비즈니스 시각에 맞아요.

message.timestamp.difference.max.ms

message.timestamp.difference.max.ms=...

CreateTime 모드에서 broker 시간과 producer 시간 차이 한계예요. 한계를 넘으면 거부해요.

9. Replica Throttle

leader.replication.throttled.replicas·follower.replication.throttled.replicas

특정 partition 의 replica(복제본) 동기화 속도 제한이에요. rebalance(파티션 재배치) 나 새 broker 추가 시 네트워크 부담을 분산할 때 써요.

$ kafka-configs.sh --bootstrap-server localhost:9092 \
    --entity-type topics --entity-name orders \
    --alter --add-config "leader.replication.throttled.replicas=*"

운영 도구라 자주 안 써요.

10. 자주 조정하는 15가지 요약

자주 쓰는 Topic 유형별 권장

일반 이벤트 (orders·payments·logs)

retention.ms=604800000              # 7일
compression.type=producer
min.insync.replicas=2

Stream Processing 중간 topic

Stream Processing 은 스트림 단위로 데이터를 처리하는 패턴이에요. 그 사이를 잇는 중간 topic 은 짧게 살리고 자주 삭제해요.

retention.ms=86400000               # 1일 (중간 결과만)
segment.ms=3600000                  # 1시간 (자주 roll → 빨리 삭제)
compression.type=zstd

Compacted Topic (config·state)

Compacted Topic 은 키별 최신 값만 남기는 topic 이에요.

cleanup.policy=compact
min.compaction.lag.ms=0
delete.retention.ms=86400000
segment.bytes=104857600             # 100MB (작은 segment, 자주 compact)

큰 메시지 Topic (이미지 메타·파일 정보)

max.message.bytes=10485760          # 10MB
compression.type=zstd
retention.ms=2592000000             # 30일

매우 중요 (결제·법적)

min.insync.replicas=3
replication.factor=5                 # broker 한 대 더 있음
unclean.leader.election.enable=false
retention.ms=-1                      # 무제한

Topic Config 변경 시 영향

여기까지 따라오셨다면 한 가지 의문이 생겨요. "변경하면 즉시 적용?" — 답은 이래요.

대부분 즉시 반영돼요. 다만 기존 segment 의 압축 방식은 바뀌지 않고 새 segment 부터 적용돼요.

동적 변경 모니터링

$ kafka-configs.sh --bootstrap-server localhost:9092 \
    --entity-type topics --entity-name orders --describe

Dynamic configs for topic orders are:
  retention.ms=86400000 sensitive=false synonyms={...}
  compression.type=zstd sensitive=false synonyms={...}

sensitive=false 면 일반 설정이라 조회가 가능하고, sensitive=true 면 보안 설정이라 조회 시 *** 로 표시돼요.

한계·실무 함정

1. retention.bytes 가 partition 단위

위에서 강조한 그대로예요. topic 전체 크기는 partitions × retention.bytes 로 계산해야 해요.

2. max.message.bytes 와 broker

Topic 만 늘리면 broker 가 거부해요. 둘 다 같이 늘려야 통해요.

3. cleanup.policy 변경 시 데이터 영향

delete 에서 compact 로 바꾸면 기존 데이터는 그대로 보존되고, 새 메시지부터 compaction 이 시작돼요. 기존 데이터가 즉시 compact 되지는 않아요.

4. segment.bytes 너무 작으면 file 폭증

100KB segment 로 잡으면 segment 파일이 수만 개로 늘어나서 파일 시스템에 부담을 줘요.

5. compression.type=producer + producer 가 압축 안 함

producer 가 압축을 안 보내면 브로커도 비압축으로 저장해요. 디스크 사용량이 폭증하니까 producer 쪽 설정도 함께 확인해야 해요.

시험 직전 한 번 더 — Kafka Topic Config 함정 압축 노트

• Topic 마다 broker default override 가능
• 명령 = kafka-topics.sh --config (생성 시) · kafka-configs.sh --alter (변경)
• 조회 = kafka-configs.sh --describe
• retention.ms = 시간 기반 보존
• retention.bytes = partition 당 크기 (topic 전체 X)
• 둘 다 명시 = 먼저 도달 발동
• segment.bytes = segment 파일 크기 (1GB 기본)
• segment.ms = 시간 기반 roll
• compression.type = producer (기본, 효율) vs broker 재압축
• cleanup.policy = delete (기본) vs compact (107편) vs delete,compact
• Compaction 관련 = min.compaction.lag.ms·max.compaction.lag.ms·min.cleanable.dirty.ratio·delete.retention.ms
• min.insync.replicas = topic 단위 override (중요 topic 강화)
• unclean.leader.election.enable = topic 단위 override
• max.message.bytes = topic 별 큰 메시지 허용, broker 도 함께 늘려야
• message.timestamp.type = CreateTime (producer) vs LogAppendTime (broker)
• LogAppendTime = 시간 기반 retention/seek 정확
• Topic 유형별 권장 — 일반 / Stream 중간 / Compacted / 큰 메시지 / 매우 중요
• 변경 적용 시점 — 대부분 즉시, 기존 segment 압축 변경 X
• 함정 — retention.bytes partition 단위
• 함정 — max.message.bytes broker 와 함께
• 함정 — cleanup.policy delete→compact 시 기존 데이터 즉시 X
• 함정 — segment.bytes 너무 작으면 file 폭증
• 함정 — compression.type=producer + producer 무압축 = 비압축 저장

공식 문서: Kafka Topic Configs 에서 자세한 사양을 확인할 수 있어요.

시리즈 다른 편 (앞뒤 글 모음)

이전 글:

• 90편 — Kafka API 5종 종합 (Producer · Consumer · Streams · Connect · Admin)
• 91편 — Kafka Producer API 깊이 (Serializer · Callback · Interceptor)
• 92편 — Kafka Consumer API 깊이 (Commit · Rebalance · Seek)
• 93편 — Kafka Admin Client API (Topic·ACL·Consumer Group 관리)
• 94편 — Kafka Broker 설정 30가지 (실무 핵심)

다음 글:

• 96편 — Kafka Producer 설정 20가지 (Batching · Retries · Idempotence)
• 97편 — Kafka Consumer 설정 25가지 (Group · Commit · Fetch)
• 98편 — Kafka Admin Client 설정 (간결 정리)
• 99편 — Kafka 운영 기본 (Topic·Partition·Reassign·Rolling Restart)
• 100편 — Kafka Monitoring (JMX 메트릭 30가지)