토픽 설정

토픽 설정 (Topic Configs)

토픽 관련 설정은 서버 기본값(server default)과 선택적인 토픽별 재정의(per-topic override)를 둘 다 가져요. 토픽별 설정을 주지 않으면 서버 기본값을 사용해요. 토픽 생성 시점에 하나 이상의 --config 옵션을 줘서 재정의를 설정할 수 있어요. 다음 예시는 커스텀 최대 메시지 크기와 플러시율을 가진 my-topic이라는 토픽을 만드는 예시예요.

$ bin/kafka-topics.sh --bootstrap-server localhost:9092 --create --topic my-topic --partitions 1 \
  --replication-factor 1 --config max.message.bytes=64000 --config flush.messages=1

재정의는 alter configs 명령으로 나중에 변경하거나 설정할 수도 있어요. 다음 예시는 my-topic의 최대 메시지 크기를 갱신해요.

$ bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type topics --entity-name my-topic \
  --alter --add-config max.message.bytes=128000

토픽에 설정된 재정의를 확인하려면 다음과 같이 해요.

$ bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type topics --entity-name my-topic --describe

재정의를 제거하려면 다음과 같이 해요.

$ bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type topics --entity-name my-topic \
  --alter --delete-config max.message.bytes

출처: 문서

본문

아래는 토픽 설정 항목들이에요. 각 항목의 서버 기본 구성 값은 "서버 기본 속성(Server Default Property)" 헤더에 나와 있어요. 주어진 서버 기본 구성 값은 토픽에 명시적인 토픽 설정 재정의가 없을 때만 적용돼요.

• cleanup.policy — 로그 세그먼트에 사용할 보존 정책을 지정해요. delete(기본값) 정책은 보존 시간이나 크기 한도에 도달하면 오래된 세그먼트를 버려요. compact 정책은 로그 컴팩션을 활성화해 각 키의 최신 값을 보존해요. 두 정책을 쉼표로 구분해 함께 지정하는 것도 가능해요(예: delete,compact). 이 경우 보존 시간·크기 설정에 따라 오래된 세그먼트가 버려지고, 남은 세그먼트는 컴팩션돼요. 빈 목록은 무한 보존을 뜻해요 — 어떤 정리 정책도 적용되지 않고 로그 세그먼트가 무기한 보존돼요. 원격 저장소(remote storage)가 활성화되면 로컬 보존 한도(log.local.retention.ms, log.local.retention.bytes)가 여전히 로컬 세그먼트에 적용된다는 점에 유의해요.
  • 유형: list / 기본값: delete / 유효 값: [compact, delete] / 서버 기본 속성: log.cleanup.policy / 중요도: medium
• compression.gzip.level — compression.type이 gzip으로 설정된 경우 사용할 압축 수준.
  • 유형: int / 기본값: -1 / 유효 값: [1,...,9] 또는 -1 / 서버 기본 속성: compression.gzip.level / 중요도: medium
• compression.lz4.level — compression.type이 lz4로 설정된 경우 사용할 압축 수준.
  • 유형: int / 기본값: 9 / 유효 값: [1,...,17] / 서버 기본 속성: compression.lz4.level / 중요도: medium
• compression.type — 주어진 토픽의 최종 압축 유형을 지정해요. 표준 압축 코덱(gzip, snappy, lz4, zstd)을 받아요. 추가로 압축 없음을 뜻하는 uncompressed, 그리고 프로듀서가 설정한 원래 압축 코덱을 유지한다는 뜻의 producer도 받아요.
  • 유형: string / 기본값: producer / 유효 값: [uncompressed, zstd, lz4, snappy, gzip, producer] / 서버 기본 속성: compression.type / 중요도: medium
• compression.zstd.level — compression.type이 zstd로 설정된 경우 사용할 압축 수준.
  • 유형: int / 기본값: 3 / 유효 값: [-131072,...,22] / 서버 기본 속성: compression.zstd.level / 중요도: medium
• delete.retention.ms — 로그 컴팩션된 토픽에 대한 삭제 툼스톤(tombstone) 마커를 보존하는 시간. 이 설정은 컨슈머가 오프셋 0부터 읽기 시작할 때 최종 단계의 유효한 스냅샷을 얻도록 보장하기 위해 읽기를 완료해야 하는 시간에도 상한을 줘요(그렇지 않으면 스캔을 끝내기 전에 삭제 툼스톤이 수집될 수 있어요).
  • 유형: long / 기본값: 86400000 (1일) / 유효 값: [0,...] / 서버 기본 속성: log.cleaner.delete.retention.ms / 중요도: medium
• file.delete.delay.ms — 파일을 파일시스템에서 삭제하기 전에 기다리는 시간.
  • 유형: long / 기본값: 60000 (1분) / 유효 값: [0,...] / 서버 기본 속성: log.segment.delete.delay.ms / 중요도: medium
• flush.messages — 로그에 쓰인 데이터를 강제로 fsync 하는 간격을 지정하는 설정. 예를 들어 1로 설정하면 메시지마다 fsync 하고, 5로 설정하면 메시지 5개마다 fsync 해요. 일반적으로 이 설정을 지정하지 않고 리플리케이션으로 내구성을 확보하며, 운영체제의 백그라운드 플러시 기능을 맡기는 걸 권장해요(더 효율적이어요). 이 설정은 토픽별로 재정의될 수 있어요.
  • 유형: long / 기본값: 9223372036854775807 / 유효 값: [1,...] / 서버 기본 속성: log.flush.interval.messages / 중요도: medium
• flush.ms — 로그에 쓰인 데이터를 강제로 fsync 하는 시간 간격을 지정하는 설정. 예를 들어 1000으로 설정하면 1000ms가 지난 뒤에 fsync 해요. 이 설정은 플러시 검사가 얼마나 자주 발생하는지 제어하는 브로커 레벨 구성 log.flush.scheduler.interval.ms에 의존해요. 일반적으로 이 설정을 지정하지 않는 걸 권장해요.
  • 유형: long / 기본값: 9223372036854775807 / 유효 값: [0,...] / 서버 기본 속성: log.flush.interval.ms / 중요도: medium
• follower.replication.throttled.replicas — 팔로워 쪽에서 로그 복제가 제한(throttle)되어야 하는 복제본 목록. [PartitionId]:[BrokerId],[PartitionId]:[BrokerId]:... 형식의 복제본 집합을 설명하거나, 와일드카드 *를 사용해 이 토픽의 모든 복제본을 제한할 수 있어요.
  • 유형: list / 기본값: "" / 유효 값: [partitionId]:[brokerId],[partitionId]:[brokerId],... / 서버 기본 속성: null / 중요도: medium
• index.interval.bytes — Kafka가 오프셋 인덱스와, 조건부로 시간 인덱스에 항목을 추가하는 빈도를 제어하는 설정. 기본 설정은 대략 4096바이트마다 메시지를 인덱싱해요. 더 자주 인덱싱하면 읽기가 로그의 정확한 위치에 더 가깝게 점프할 수 있지만 인덱스 파일이 커져요. 보통 바꿀 필요는 없어요. 참고: 시간 인덱스는 타임스탬프가 마지막으로 인덱싱된 타임스탬프보다 클 때만 삽입돼요.
  • 유형: int / 기본값: 4096 (4 kibibytes) / 유효 값: [0,...] / 서버 기본 속성: log.index.interval.bytes / 중요도: medium
• leader.replication.throttled.replicas — 리더 쪽에서 로그 복제가 제한되어야 하는 복제본 목록. [PartitionId]:[BrokerId],[PartitionId]:[BrokerId]:... 형식이거나 와일드카드 *를 사용할 수 있어요.
  • 유형: list / 기본값: "" / 유효 값: [partitionId]:[brokerId],[partitionId]:[brokerId],... / 서버 기본 속성: null / 중요도: medium
• local.retention.bytes — 파티션의 로컬 로그 세그먼트가 오래된 세그먼트를 삭제하기 전까지 커질 수 있는 최대 크기. 기본값 -2는 retention.bytes 값을 사용하라는 뜻이에요. 유효 값은 항상 retention.bytes 값보다 작거나 같아야 해요.
  • 유형: long / 기본값: -2 / 유효 값: [-2,...] / 서버 기본 속성: log.local.retention.bytes / 중요도: medium
• local.retention.ms — 로컬 로그 세그먼트가 삭제되기 전까지 보관하는 밀리초 수. 기본값 -2는 retention.ms 값을 사용하라는 뜻이에요. 유효 값은 항상 retention.ms 값보다 작거나 같아야 해요.
  • 유형: long / 기본값: -2 / 유효 값: [-2,...] / 서버 기본 속성: log.local.retention.ms / 중요도: medium
• max.compaction.lag.ms — 메시지가 로그에서 컴팩션 부적격으로 남아 있을 수 있는 최대 시간. 컴팩션되는 로그에만 적용돼요.
  • 유형: long / 기본값: 9223372036854775807 / 유효 값: [1,...] / 서버 기본 속성: log.cleaner.max.compaction.lag.ms / 중요도: medium
• max.message.bytes — Kafka가 허용하는 가장 큰 레코드 배치 크기(압축이 활성화된 경우 압축 후).
  • 유형: int / 기본값: 1048588 / 유효 값: [0,...] / 서버 기본 속성: message.max.bytes / 중요도: medium
• message.timestamp.after.max.ms — 메시지 타임스탬프와 브로커 타임스탬프 사이의 허용 가능한 타임스탬프 차이를 설정하는 구성. 메시지 타임스탬프는 브로커 타임스탬프보다 나중이거나 같을 수 있고, 최대 허용 차이는 이 구성의 값으로 정해져요. message.timestamp.type=CreateTime이면 타임스탬프 차이가 이 임계값을 넘으면 메시지가 거부돼요. message.timestamp.type=LogAppendTime이면 이 구성은 무시돼요.
  • 유형: long / 기본값: 3600000 (1시간) / 유효 값: [0,...] / 서버 기본 속성: log.message.timestamp.after.max.ms / 중요도: medium
• message.timestamp.before.max.ms — 브로커 타임스탬프와 메시지 타임스탬프 사이의 허용 가능한 타임스탬프 차이를 설정하는 구성. 메시지 타임스탬프는 브로커 타임스탬프보다 이전이거나 같을 수 있고, 최대 허용 차이는 이 구성의 값으로 정해져요. message.timestamp.type=CreateTime이면 타임스탬프 차이가 이 임계값을 넘으면 메시지가 거부돼요. message.timestamp.type=LogAppendTime이면 이 구성은 무시돼요.
  • 유형: long / 기본값: 9223372036854775807 / 유효 값: [0,...] / 서버 기본 속성: log.message.timestamp.before.max.ms / 중요도: medium
• message.timestamp.type — 메시지의 타임스탬프가 메시지 생성 시간인지 로그 추가 시간인지 정의해요.
  • 유형: string / 기본값: CreateTime / 유효 값: [CreateTime, LogAppendTime] / 서버 기본 속성: log.message.timestamp.type / 중요도: medium
• min.cleanable.dirty.ratio — 로그 컴팩터가 로그를 정리하려 시도하는 빈도를 제어하는 구성(로그 컴팩션이 활성화된 경우). 기본적으로 로그의 50% 이상이 컴팩션된 로그는 정리하지 않아요. 이 비율은 중복으로 인해 로그에서 낭비되는 최대 공간에 상한을 둘 수 있어요(50%에서 로그의 최대 50%가 중복일 수 있어요). 더 높은 비율은 더 적고 효율적인 정리를 의미하지만 로그에 더 많은 공간 낭비를 의미해요. max.compaction.lag.ms나 min.compaction.lag.ms 구성도 지정되면, 로그 컴팩터는 다음 두 경우 중 하나일 때 로그를 컴팩션 대상으로 간주해요: (i) 더티 비율 임계값이 충족되고 로그에 최소 min.compaction.lag.ms 기간 동안 더티(미컴팩션) 레코드가 있었던 경우, 또는 (ii) 로그에 최대 max.compaction.lag.ms 기간 동안 더티(미컴팩션) 레코드가 있었던 경우.
  • 유형: double / 기본값: 0.5 / 유효 값: [0,...,1] / 서버 기본 속성: log.cleaner.min.cleanable.ratio / 중요도: medium
• min.compaction.lag.ms — 메시지가 로그에서 미컴팩션 상태로 남아 있을 수 있는 최소 시간. 컴팩션되는 로그에만 적용돼요.
  • 유형: long / 기본값: 0 / 유효 값: [0,...] / 서버 기본 속성: log.cleaner.min.compaction.lag.ms / 중요도: medium
• min.insync.replicas — 프로듀서가 acks를 all(또는 -1)로 설정했을 때 쓰기가 성공하려면 필요한 동기화된 복제본(in-sync replicas, ISR)(리더 포함)의 최소 수를 지정해요. acks=all의 경우, 모든 동기화된 복제본이 쓰기를 승인해야 성공으로 간주돼요. 예를 들어 토픽의 replication.factor가 3이고 ISR 집합에 세 복제본이 모두 포함되면, min.insync.replicas가 3보다 작더라도 acks=all 쓰기가 성공하려면 세 복제본 모두가 승인해야 해요. acks=all이고 현재 ISR 집합에 min.insync.replicas보다 적은 멤버가 있으면 프로듀서는 예외(NotEnoughReplicas 또는 NotEnoughReplicasAfterAppend)를 일으켜요. acks 설정과 무관하게 메시지는 모든 동기화된 복제본에 복제되고 min.insync.replicas 조건이 충족될 때까지 컨슈머에게 보이지 않아요. 함께 사용하면 min.insync.replicas와 acks는 더 강한 내구성 보장을 강제할 수 있어요. 일반적인 시나리오는 복제 팩터 3의 토픽을 만들고, min.insync.replicas를 2로 설정하고, acks를 all로 프로듀스하는 것이에요. 이렇게 하면 복제본 과반수가 쓰기를 영속해야 프로듀서가 성공으로 간주하고 컨슈머가 볼 수 있어요. 참고: Eligible Leader Replicas(ELR) 기능이 활성화되면 이 구성의 의미가 바뀌어요. 자세한 내용은 ELR 섹션을 참고해요.
  • 유형: int / 기본값: 1 / 유효 값: [1,...] / 서버 기본 속성: min.insync.replicas / 중요도: medium
• preallocate — 새 로그 세그먼트를 만들 때 디스크에 파일을 미리 할당(preallocate)할지 여부.
  • 유형: boolean / 기본값: false / 유효 값: — / 서버 기본 속성: log.preallocate / 중요도: medium
• remote.log.copy.disable — 토픽의 티어드 데이터가 읽기 전용이 되어 더 이상 데이터가 업로드되지 않게 할지 결정해요. 이 구성이 true로 설정되면 로컬 보존 구성(local.retention.ms/bytes)은 무의미해지고, 모든 데이터 만료는 토픽 전체 보존 구성(retention.ms/bytes)을 따르게 돼요.
  • 유형: boolean / 기본값: false / 유효 값: — / 서버 기본 속성: null / 중요도: medium
• remote.log.delete.on.disable — 토픽에서 티어드 스토리지가 비활성화된 후 토픽의 티어드 데이터를 삭제할지 결정해요. remote.storage.enable을 true에서 false로 설정할 때 이 구성을 활성화해야 해요.
  • 유형: boolean / 기본값: false / 유효 값: — / 서버 기본 속성: null / 중요도: medium
• remote.storage.enable — 토픽에 티어드 스토리지를 활성화하려면 이 구성을 true로 설정해요. 활성화된 토픽의 티어드 스토리지를 비활성화하려면 false로 설정해요. 비활성화할 때는 remote.log.delete.on.disable도 반드시 true로 설정해야 해요.
  • 유형: boolean / 기본값: false / 유효 값: — / 서버 기본 속성: null / 중요도: medium
• retention.bytes — delete 보존 정책을 사용할 때, 공간을 확보하기 위해 오래된 로그 세그먼트를 버리기 전에 파티션(로그 세그먼트로 구성)이 커질 수 있는 최대 크기를 제어하는 구성. 기본적으로는 크기 제한 없이 시간 제한만 있어요. 이 한도는 파티션 레벨에서 강제되므로, 토픽 보존(바이트)을 계산하려면 파티션 수를 곱해요. 추가로 retention.bytes 구성은 segment.ms와 segment.bytes 구성과 독립적으로 동작해요. 또한 retention.bytes가 0으로 설정되면 새 세그먼트 롤링을 트리거해요.
  • 유형: long / 기본값: -1 / 유효 값: — / 서버 기본 속성: log.retention.bytes / 중요도: medium
• retention.ms — delete 보존 정책을 사용할 때, 공간을 확보하기 위해 오래된 로그 세그먼트를 버리기 전에 로그를 보존할 최대 시간을 제어하는 구성. 이것은 컨슈머가 데이터를 얼마나 빨리 읽어야 하는지에 대한 SLA를 나타내요. -1로 설정하면 시간 제한이 적용되지 않아요. 추가로 retention.ms 구성은 segment.ms와 segment.bytes 구성과 독립적으로 동작해요. 또한 retention.ms 조건이 충족되면 새 세그먼트 롤링을 트리거해요.
  • 유형: long / 기본값: 604800000 (7일) / 유효 값: [-1,...] / 서버 기본 속성: log.retention.ms / 중요도: medium
• segment.bytes — 로그의 세그먼트 파일 크기를 제어하는 구성. 보존과 정리는 항상 파일 단위로 이루어지므로 세그먼트 크기가 크면 파일 수는 적지만 보존에 대한 세밀한 제어는 줄어요.
  • 유형: int / 기본값: 1073741824 (1 gibibyte) / 유효 값: [1048576,...] / 서버 기본 속성: log.segment.bytes / 중요도: medium
• segment.index.bytes — 오프셋을 파일 위치에 매핑하는 인덱스의 크기를 제어하는 구성. 이 인덱스 파일을 미리 할당하고 로그가 롤된 후에만 줄여요. 보통 이 설정을 바꿀 필요는 없어요.
  • 유형: int / 기본값: 10485760 (10 mebibytes) / 유효 값: [4,...] / 서버 기본 속성: log.index.size.max.bytes / 중요도: medium
• segment.jitter.ms — 예약된 세그먼트 롤링 시간에서 빼는 최대 무작위 지터(jitter)로, 세그먼트 롤링의 썬더링 허드(thundering herd)를 피하기 위한 값.
  • 유형: long / 기본값: 0 / 유효 값: [0,...] / 서버 기본 속성: log.roll.jitter.ms / 중요도: medium
• segment.ms — 세그먼트 파일이 가득 차지 않았어도 Kafka가 로그 롤링을 강제하는 시간 간격을 제어하는 구성. 보존이 오래된 데이터를 삭제하거나 컴팩션할 수 있도록 보장하기 위한 거예요.
  • 유형: long / 기본값: 604800000 (7일) / 유효 값: [1,...] / 서버 기본 속성: log.roll.ms / 중요도: medium
• unclean.leader.election.enable — 최후의 수단으로 ISR 집합에 없는 복제본을 리더로 선출할지 여부를 나타내는 구성. 이렇게 하면 데이터 손실이 발생할 수 있어요. 참고: KRaft 모드에서 이 구성을 동적으로 활성화할 때는 unclean leader election 스레드가 주기적으로(기본 5분) 선출을 트리거하기를 기다려야 해요. 필요하면 unclean 옵션과 함께 kafka-leader-election.sh를 실행해 unclean leader election을 즉시 트리거해요.
  • 유형: boolean / 기본값: false / 유효 값: — / 서버 기본 속성: unclean.leader.election.enable / 중요도: medium

더 알아보기 (Learn more)

• 토픽별 설정은 kafka-configs.sh로 생성·확인·수정·삭제할 수 있어요.
• 보존·컴팩션·압축은 토픽 운영에서 가장 흔히 건드리는 설정이라, 각 항목의 기본값을 알아두면 도움이 돼요.