[Kafka] 브로커 핵심 매개변수 레퍼런스

 

참고: 카프카 핵심 가이드 기준 / Apache Kafka 3.x / server.properties

 

---

1. 핵심 브로커 매개변수

브로커 자체의 동작 방식을 결정하는 파라미터입니다. 토픽 레벨에서 오버라이드할 수 없으며, 대부분 변경 시 브로커 재시작이 필요합니다.

 

---

broker.id

항목	내용
기본값	-1 (자동 할당)
재시작 필요	O

클러스터 내 브로커를 식별하는 고유 정수 ID입니다. 기본값은 자동 할당이지만 운영 환경에서는 직접 지정하는 것을 권장합니다. 브로커 교체나 복구 시 동일한 ID를 재사용하면, 파티션 재배치 없이 기존 역할을 그대로 이어받을 수 있습니다.

broker.id=1

 

---

listeners

항목	내용
기본값	PLAINTEXT://:9092
재시작 필요	O

브로커가 바인딩할 네트워크 주소와 포트 목록입니다. 프로토콜://호스트:포트 형식으로 쉼표 구분하여 복수 지정이 가능합니다.

 

도커, 클라우드처럼 내부 주소와 외부 주소가 다른 환경에서는 advertised.listeners를 반드시 함께 설정해야 클라이언트가 올바른 주소로 접근할 수 있습니다.

# 단일 리스너
listeners=PLAINTEXT://:9092

# 내부/외부 분리 (도커, 클라우드 환경)
listeners=INTERNAL://:9092,EXTERNAL://:9093
advertised.listeners=INTERNAL://broker1.internal:9092,EXTERNAL://broker1.example.com:9093
listener.security.protocol.map=INTERNAL:PLAINTEXT,EXTERNAL:SSL

 

---

log.dirs

항목	내용
기본값	/tmp/kafka-logs
재시작 필요	O

메시지 로그 세그먼트가 저장되는 디렉터리 경로입니다. 쉼표로 구분하여 여러 경로를 지정하면 Kafka가 파티션을 분산 배치해 디스크 I/O 부하를 나눌 수 있습니다.

 

운영 환경에서는 /tmp가 아닌 전용 데이터 경로를 반드시 지정해야 합니다.

# 단일 디렉터리
log.dirs=/data/kafka

# 복수 디렉터리 (디스크 분산)
log.dirs=/data/kafka-1,/data/kafka-2,/data/kafka-3

 

---

num.recovery.threads.per.data.dir

항목	내용
기본값	1
재시작 필요	O

브로커 시작 시 로그 디렉터리를 복구하는 데 사용할 디렉터리당 스레드 수입니다. 정상 시작과 비정상 종료 후 복구, 두 상황 모두에 적용됩니다.

 

log.dirs에 경로가 3개라면 실제 스레드 수는 설정값 × 3이 됩니다. 파티션이 많거나 복구 시간을 줄여야 할 때 값을 높이고, 복구 완료 후 다시 낮추는 방식으로 활용합니다.

num.recovery.threads.per.data.dir=4

 

---

auto.create.topics.enable

항목	내용
기본값	true
재시작 필요	O

존재하지 않는 토픽에 프로듀서가 메시지를 쓰거나 컨슈머가 구독을 시도할 때, 토픽을 자동으로 생성할지 여부를 결정합니다.

 

개발 환경에서는 편리하지만, 운영 환경에서는 오타나 실수로 의도치 않은 토픽이 만들어질 수 있습니다. 토픽은 명시적으로 생성하고 false로 설정하는 것이 일반적입니다.

# 운영 환경 권장
auto.create.topics.enable=false

 

---

auto.leader.rebalance.enable

항목	내용
기본값	true
재시작 필요	O

파티션 리더가 특정 브로커에 몰릴 경우 자동으로 리더를 재분배할지 여부를 결정합니다. 브로커 재시작 후 리더가 원래 브로커로 돌아오지 않아 부하가 편중되는 상황을 자동으로 해소합니다.

 

재분배 주기는 leader.imbalance.check.interval.seconds(기본 300초), 불균형 임계값은 leader.imbalance.per.broker.percentage(기본 10%)로 조정합니다.

auto.leader.rebalance.enable=true
leader.imbalance.check.interval.seconds=300
leader.imbalance.per.broker.percentage=10

 

---

delete.topic.enable

항목	내용
기본값	true
재시작 필요	O

kafka-topics.sh --delete 명령으로 토픽을 삭제할 수 있는지 여부를 결정합니다. false로 설정하면 삭제 요청이 무시되고 토픽이 실제로 제거되지 않습니다.

 

실수로 인한 토픽 삭제를 막기 위해 false로 설정하는 경우도 있지만, 관리 복잡도가 높아지므로 ACL(접근 권한 제어)로 관리하는 방식이 더 일반적입니다.

delete.topic.enable=true

 

---

2. 토픽별 기본값

토픽 생성 시 적용되는 브로커 레벨 기본값입니다. 토픽 생성 시 --config 옵션으로 개별 오버라이드가 가능하며, kafka-configs.sh --alter로 동적 변경도 지원합니다.

---

num.partitions

항목	내용
기본값	1
토픽 오버라이드	O
동적 변경	O (늘리기만 가능)

자동 생성 토픽의 기본 파티션 수입니다. 파티션 수는 컨슈머 그룹 내 최대 병렬 처리 수와 직결됩니다.

 

파티션은 늘릴 수만 있고 줄일 수 없으므로, 처음부터 적절한 수로 설정하는 것이 중요합니다. 예상 처리량, 컨슈머 수, 브로커 수를 함께 고려해 결정합니다.

num.partitions=6

 

---

default.replication.factor

항목	내용
기본값	1
토픽 오버라이드	O

자동 생성 토픽의 기본 복제본 수입니다. 브로커 장애 시 데이터 유실을 막으려면 최소 2 이상, 운영 환경에서는 3이 권장됩니다. 복제본 수는 브로커 수를 초과할 수 없습니다.

# 운영 환경 권장 (3노드 이상)
default.replication.factor=3

 

---

log.retention.ms

항목	내용
기본값	미설정 시 log.retention.hours 적용
관련 파라미터	log.retention.hours (기본 168, 7일)
토픽 오버라이드	O
동적 변경	O

메시지를 보존하는 기간입니다. log.retention.ms > log.retention.minutes > log.retention.hours 순으로 우선 적용됩니다. 보존 기간이 지난 세그먼트는 삭제 대상이 되며, 실제 삭제는 세그먼트 단위로 수행됩니다. -1로 설정하면 무기한 보존합니다.

# 3일 보존
log.retention.ms=259200000

# 또는
log.retention.hours=72

 

---

log.retention.bytes

항목	내용
기본값	-1 (무제한)
적용 단위	파티션 단위
토픽 오버라이드	O
동적 변경	O

파티션당 보존할 최대 로그 크기입니다. log.retention.ms와 독립적으로 동작하며, 둘 중 하나라도 조건을 만족하면 삭제가 트리거됩니다. 토픽 전체 크기를 제어하려면 파티션 수 × log.retention.bytes로 계산합니다.

# 파티션당 10GB 보존
log.retention.bytes=10737418240

 

---

log.segment.bytes

항목	내용
기본값	1073741824 (1GB)
토픽 오버라이드	O
동적 변경	O

로그 세그먼트 파일 하나의 최대 크기입니다. 세그먼트가 이 크기에 도달하면 새 세그먼트 파일로 롤링됩니다.

보존 기간 만료 체크는 세그먼트 단위로 수행되므로, 세그먼트가 크면 기간이 지난 메시지도 더 오래 남아있을 수 있습니다. 메시지 생성 속도가 느린 토픽은 세그먼트 크기를 줄이면 보존 기간이 더 정확하게 적용됩니다.

log.segment.bytes=536870912

 

---

log.roll.ms

항목	내용
기본값	미설정 시 log.roll.hours 적용 (기본 168시간)
토픽 오버라이드	O

크기와 무관하게 세그먼트를 강제로 롤링하는 주기입니다. 메시지가 거의 없어 세그먼트가 오랫동안 열려 있을 경우, 보존 기간 기반 삭제가 트리거되지 않는 문제를 방지합니다.

 

log.segment.bytes 조건과 OR로 동작하며, 둘 중 먼저 만족하는 조건에 따라 롤링됩니다.

# 1일마다 강제 롤링
log.roll.ms=86400000

---

min.insync.replicas

항목	내용
기본값	1
토픽 오버라이드	O
동적 변경	O

프로듀서의 acks=all 설정 시, 쓰기 성공으로 인정받기 위한 최소 ISR(In-Sync Replica) 수입니다. ISR 수가 이 값 미만이면 브로커가 NotEnoughReplicasException을 반환하고 쓰기를 거부합니다.

 

replication.factor=3, min.insync.replicas=2 조합이 운영 환경의 일반적인 권장 설정입니다. 브로커 1대가 내려가도 쓰기가 가능하고, 2대가 내려가면 쓰기를 거부해 데이터 유실을 막습니다.

주의: 프로듀서의 acks=all과 함께 설정해야 효과가 있습니다. acks=1이면 이 값은 무시됩니다.

# 브로커 수: 3, 복제본: 3, 최소 ISR: 2
min.insync.replicas=2

 

---

message.max.bytes

항목	내용
기본값	1048588 (~1MB)
토픽 오버라이드	O (max.message.bytes로 설정)
동적 변경	O

브로커가 허용하는 단일 메시지(압축 후 배치 기준)의 최대 크기입니다. 이 값을 변경할 경우 연관된 파라미터도 함께 조정해야 합니다.

 

연관 파라미터	위치	설명
replica.fetch.max.bytes	브로커	복제 시 최대 페치 크기. message.max.bytes 이상으로 설정
fetch.max.bytes	컨슈머	컨슈머 응답 최대 크기
max.request.size	프로듀서	프로듀서 요청 최대 크기
max.partition.fetch.bytes	컨슈머	파티션당 최대 페치 크기

 

# 브로커
message.max.bytes=10485760

# 함께 설정 필요
replica.fetch.max.bytes=10485760

 

---

참고

• Apache Kafka 공식 설정 문서
• 카프카 핵심 가이드 (Kafka: The Definitive Guide)

---

작성 기준: Apache Kafka 3.x / 오탈자·수정 제안은 댓글로 남겨주세요