카프카 쉘 스크립트 CLI 종류 및 사용법
카프카 CLI 종류
Kafka CLI 도구는 카프카 설치 시 bin 폴더에 포함된 쉘 스크립트 (.sh 또는 .bat) 실행 파일입니다.
카프카 클러스터 운영 및 관리 기능들을 CLI (Command Line Interface) 형태로 제공합니다.
| kafka-server-start.sh | 카프카 브로커 실행 |
| kafka-server-stop.sh | 카프카 브로커 종료 |
| zookeeper-server-start.sh | 주키퍼 서버 실행 |
| zookeeper-server-stop.sh | 주키퍼 서버 종료 |
| kafka-topics.sh | 토픽 생성, 삭제, 조회, 설정 변경 등 관리 |
| kafka-console-producer.sh | 터미널에서 메시지를 입력하고 전송하는 프로듀서 실행 |
| kafka-console-consumer.sh | 터미널에서 메시지를 실시간으로 읽는 컨슈머 실행 |
| kafka-consumer-groups.sh | 컨슈머 그룹 상태 조회, 오프셋 이동 등 |
| kafka-configs.sh | 사용자/브로커/토픽 등 설정값 변경 |
| kafka-acls.sh | ACL 설정 (접근 제어) |
| kafka-reassign-partitions.sh |
파티션 재할당 작업 특정 브로커에 리터 파티션이 몰리는 경우 사용하면 좋은 명령어입니다. 리더 파티션을 각 브로커에 균등하게 재분배하여 네트워크 통신으로 인한 리소스 부하를 분산합니다. |
| kafka-preferred-replica-election.sh | 선호 리더 선출 실행 |
| kafka-run-class.sh | 임의의 Kafka 클래스 실행 (고급용) |
| kafka-verifiable-consumer.sh | 테스트용 컨슈머 (정합성 테스트) |
| kafka-verifiable-producer.sh | 테스트용 프로듀서 (정합성 테스트) |
| connect-standalone.sh | 커넥트 단일 모드 실행 |
| connect-distributed.sh | 커넥트 클러스터 모드 실행 |
| kafka-producer-perf-test.sh | 프로듀서 성능 테스트 |
| kafka-consumer-perf-test.sh | 컨슈머 성능 테스트 |
| kafka-storage.sh | 로그 디렉터리 포맷 및 검증 |
| kafka-metadata-shell.sh | 메타데이터 수동 조회 (고급 기능) |
카프카 토픽 관련 CLI
토픽 생성
-- 필수 옵션만 포함하여 토픽 생성
kafka-topics.sh --create --bootstrap-server localhost:9092 --topic 토픽명
-- 파티션 수, 복제 수, 리텐션 주기 지정하여 토픽 생성
kafka-topics.sh --create --bootstrap-server localhost:9092 --topic 토픽명 --partitions 3 --replication-factor 2 --config retention.ms=172800000
토픽 리스트 확인
kafka-topics.sh --bootstrap-server localhost:9092 --list
로컬 카프카 브로커에 생성된 토픽 이름 리스트를 출력합니다.
–bootstrap-server 옵션 추가 시, 카프카 클러스터 내 브로커 1대에 요청합니다.
토픽 설정 확인
kafka-topics.sh --bootstrap-server localhost:9092 --topic 토픽명 --describe
토픽에 설정된 옵션 (파티션 수, 복제 수, 세그먼트 크기 등) 을 확인할 수 있습니다.
각 파티션의 리더 파티션과 복제본이 위치한 브로커 ID, ISR 정보도 알 수 있습니다.
토픽 파티션 수 변경
kafka-topics.sh --bootstrap-server localhost:9092 --topic 토픽명 --alter --partitions 4
한번 늘린 파티션 수는 줄일 수 없으므로, 신중하게 늘려야 합니다.
토픽 옵션 추가
kafka-topics.sh --bootstrap-server localhost:9092 --topic 토픽명 --alter --add-config min.insync.replicas=2
토픽에 min.insync.replicas (ISR 최소 개수) 옵션을 추가합니다.
카프카 브로커 관련 CLI
브로커 설정 확인
kafka-configs.sh --bootstrap-server localhost:9092 --broker 브로커ID --all --describe
특정 브로커에 설정된 옵션 값들을 모두 확인할 수 있습니다.
카프카 프로듀서 관련 CLI
토픽 메시지 값 전송
kafka-console.producer.sh --bootstrap-server localhost:9092 --topic 토픽명
가 나오면, 엔터로 구분하여 메시지 키가 null인 메시지 값을 여러개 보낼 수 있습니다.
메시지 키가 null인 경우, 라운드 로빈 방식으로 전송하여 여러 파티션에 고르게 분배됩니다.
토픽 메시지 키-값 전송
kafka-console.producer.sh --bootstrap-server localhost:9092 --topic 토픽명 --property "parse.key=true" --property "key.separator=:"
가 나오면, 엔터로 구분하여 메시지 키:값 레코드를 여러개 보낼 수 있습니다.
메시지 키는 동일한 파티션 매핑, 메시지 순서 보장★, 데이터 그룹화에 사용되는 값입니다.
카프카 컨슈머 관련 CLI
토픽 메시지 값 조회
kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic 토픽명 --from-beginning
from-beginning 옵션으로 토픽에 저장된 가장 처음 메시지부터 모든 값을 순차 출력합니다.
Ctrl + C로 실시간 보기를 나갈 수 있습니다.
토픽 메시지 키-값 조회
kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic 토픽명 --property parse.key=true --property key.separator="-" --from-beginning
토픽에 저장된 모든 메시지 키-값을 순차 출력합니다.
토픽 메시지 최대 N개 조회
kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic 토픽명 --from-beginning --max-messages 1
토픽에 저장된 모든 메시지 중, 가장 처음부터 최대 1개의 메시지만 출력하는 예시입니다.
특정 파티션 메시지 조회
kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic 토픽명 --partition 2 --from-beginning
2번 파티션에 저장된 메시지만 출력하는 예시입니다.
컨슈머 그룹 지정하여 메시지 조회
kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic 토픽명 --group 컨슈머그룹ID --from-beginning
지정된 컨슈머 그룹에 속한 컨슈머가 메시지를 처음부터 마지막으로 커밋된 오프셋까지 순차적으로 읽습니다.
지정한 컨슈머 그룹이 없으면 새로 만들어집니다.
컨슈머 그룹이 어느 메시지(레코드)까지 읽었는지는 __consumer_offsets 토픽에 저장됩니다.
마지막으로 커밋된 오프셋 이후부터 조회
kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic 토픽명 --group 컨슈머그룹ID
컨슈머 그룹이 이전에 읽고 커밋한 레코드들을 제외하고, 프로듀서가 이후에 보낸 메시지들을 순차적으로 읽습니다.
카프카 컨슈머 그룹 관련 CLI
컨슈머 그룹 리스트 확인
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --list
현재 생성되어 있는 컨슈머 그룹 이름 목록을 볼 수 있습니다.
console-sonsumer는 kafka-console-consumer.sh 사용 시 일시적으로 생성되는 기본 컨슈머 그룹입니다.
더 이상 사용되지 않으면 Kafka에서 GC 대상이 되어 삭제될 수 있습니다.
컨슈머 그룹 상태 확인
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --group 컨슈머그룹ID --describe
특정 컨슈머 그룹이 어떤 토픽 레코드를 어디까지 조회했는지 모니터링할 수 있습니다.
일회성 조회이므로, 실제 모니터링 시에는 외부 모니터링 툴로 컨슈머 랙을 수집하고 시각화하는 것이 좋습니다.
컨슈머 랙 모니터링 아키텍처
| 버로우 | 컨슈머 랙 상태 체크 오픈소스 모니터링 툴 |
| 텔레그래프 | 버로우 REST API를 주기적으로 호출하여 컨슈머 랙 데이터 수집 |
| 엘라스틱서치 | 수집된 컨슈머 랙 데이터 저장 및 분석 |
| 그라파나 | 엘라스틱서치에 저장한 컨슈머 랙 데이터 시각화 |
컨슈머 그룹 상태 정보
| GROUP | 컨슈머 그룹명 |
| TOPIC | 연결된 토픽명 |
| PARTITION | 토픽 내 파티션 번호 |
| CURRENT-OFFSET | 컨슈머가 마지막으로 커밋한 오프셋 (마지막으로 읽은 위치) |
| LOG-END-OFFSET | 해당 파티션의 가장 최신 메시지 오프셋 (프로듀서가 보낸 가장 마지막 메시지 위치) |
| LAG ★ |
컨슈머가 아직 읽지 못한 메시지 수. 컨슈머 랙 (LOG-END-OFFSET - CURRENT-OFFSET) 프로듀서 처리량 대비 컨슈머 처리량이 낮아 지연이 발생하는지 판단하는 모니터링 지표 컨슈머 랙은 컨슈머 그룹-토픽-파티션 단위로 생성됨 컨슈머 처리 지연 및 장애 여부 확인을 위해서 컨슈머 랙 모니터링은 필수★ 프로듀서 전송량이 증가하면 파티션, 컨슈머 수를 늘려 병렬 처리량을 높이는 것이 좋은 대응 방안 컨슈머 장애 시 파티션 수만큼 컨슈머 수를 늘려 병렬 처리하는 것이 바람직함 |
| CONSUMER-ID | 해당 파티션을 현재 읽고 있는 컨슈머 ID |
| HOST | 컨슈머가 실행 중인 서버 IP |
| CLIENT-ID | 컨슈머 클라이언트 ID |
컨슈머 렉, 컨슈머 호스트 정보 등을 알 수 있어서 유용합니다.
컨슈머 그룹 오프셋 리셋
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --group 컨슈머그룹ID --topic 토픽명 --reset-offsets --to-earliest --execute
컨슈머 그룹의 현재 오프셋을 리셋하고, 특정 위치부터 데이터를 읽도록 설정합니다. to-earliest은 토픽의 가장 첫 번째 메시지 오프셋 (0번째) 부터 읽도록 하는 옵션입니다.
오프셋 리셋 종류
| to-earliest | 가장 처음 오프셋으로 리셋 |
| to-latest | 가장 마지막 오프셋으로 리셋 |
| to-current | 현재 커밋된 오프셋으로 리셋 |
| to-datetime {YYYY-MM-DDTHH:mmSS.sss} | 레코드 타임스탬프 기준, 특정 시간 이후 첫 오프셋으로 리셋 |
| to-offset {long} | 특정 오프셋으로 리셋 |
| shift-by {+/- long} | 현재 컨슈머 오프셋에서 앞/뒤로 리셋 |
기타 CLI
카프카 프로듀서 퍼포먼스 측정
kafka-producer-perf-test.sh --producer-props bootstrap-servers=localhost:9092 --topic 토픽명 --num-records 10 --throughput 1 --record-size 100 --print-metrics
카프카 프로듀서 퍼포먼스를 측정할 때 사용되는 스크립트입니다.
토픽에 10개의 레코드를 초당 1개씩, 각 100바이트 크기로 전송하며 성능을 측정합니다.
브로커로 전송되는 레코드 전송 속도, 레이턴시, 전송 처리량 등 메트릭을 확인할 수 있습니다.
네트워크 전송이 정상적인지 확인하는 테스트 용도로도 사용 가능합니다.
카프카 컨슈머 퍼포먼스 측정
kafka-consumer-perf-test.sh --bootstrap-server localhost:9092 --topic 토픽명 --messages 10 --show-detailed-stats
카프카 컨슈머 퍼포먼스를 측정할 때 사용되는 스크립트입니다.
토픽에서 10개의 메시지를 읽으며 레이턴시, 처리량 등 통계 정보를 출력합니다.
리더 파티션 분배
kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --reassignment-json-file 파티션재배치계획파일명.json --execute
리더 파티션이 특정 브로커에 몰려있는 경우, 다른 브로커에 수동 분배할 수 있습니다.
파티션 재배치 계획 파일을 생성하고 스크립트를 실행하면 됩니다.
{
"version": 1,
"partitions": [
{
"topic": "토픽명",
"partition": 0,
"replicas": [1, 2, 3]
},
{
"topic": "토픽명",
"partition": 1,
"replicas": [2, 3, 4]
}
]
}
범위 레코드 삭제
kafka-delete-records.sh --bootstrap-server localhost:9092 --offsers-file 삭제오프셋파일명.json --execute
토픽의 파티션별 특정 범위 레코드를 수동 삭제하는 스크립트입니다.
삭제 오프셋 파일 예시
{
"partitions": [
{
"topic": "토픽명",
"partition": 0,
"offset": 100
},
{
"topic": "토픽명",
"partition": 1,
"offset": 50
}
],
"version": 1
}
파티션 0번에서 100번 오프셋 이전의 모든 레코드를 삭제하고,
파티션 1번에서 50번 오프셋 이전의 모든 레코드를 삭제하는 파일 예시입니다.
카프카 덤프 로그 확인
kafka-dump-log.sh --files 카프카폴더/data/토픽명-파티션번호/00000000000000000000.log --deep-iteration
운영 이슈가 생겼을 때 특정 세그먼트 파일을 지정해서 상세 로그를 확인할 수 있습니다.