Kafka CLI 명령어 완벽 실습 가이드

카프카의 핵심 CLI 명령어를 실습 중심으로 학습합니다. 토픽 관리부터 메시지 송수신, 컨슈머 그룹 관리, 오프셋 제어, 브로커 설정 확인까지 터미널에서 직접 실행해보며 카프카의 동작 원리를 체득할 수 있습니다.

---

목차

1. 토픽 생성 조회 삭제
2. 콘솔 프로듀서로 메시지 전송
3. 콘솔 컨슈머로 메시지 확인
4. 컨슈머 그룹 상태 조회
5. 오프셋 관리 명령어
6. 브로커 설정 확인 명령어

---

1. 토픽 생성 조회 삭제

어느 날 김개발 씨가 새로운 마이크로서비스를 배포하려다 보니, 카프카에 토픽이 하나도 없다는 것을 깨달았습니다. "선배님, 토픽은 어떻게 만들까요?" 김개발 씨의 첫 CLI 실습이 시작됩니다.

토픽 관리 명령어는 카프카에서 가장 기본적이고 자주 사용하는 CLI 명령어입니다. 마치 도서관에 새로운 책장을 설치하고, 목록을 확인하고, 불필요한 책장을 정리하는 것과 같습니다.

이 명령어들을 익히면 카프카 클러스터의 토픽을 자유롭게 관리할 수 있습니다.

다음 코드를 살펴봅시다.

# 토픽 생성 - 3개 파티션, 복제 팩터 1
kafka-topics.sh --create \
  --topic order-events \
  --partitions 3 \
  --replication-factor 1 \
  --bootstrap-server localhost:9092

# 토픽 목록 조회
kafka-topics.sh --list \
  --bootstrap-server localhost:9092

# 토픽 상세 정보 조회
kafka-topics.sh --describe \
  --topic order-events \
  --bootstrap-server localhost:9092

# 토픽 삭제
kafka-topics.sh --delete \
  --topic order-events \
  --bootstrap-server localhost:9092

"Apache Kafka 완전 정복" 코스의 8번째 시간입니다. 지난 7화에서는 복제와 내결함성에 대해 학습하며, 카프카가 어떻게 데이터 유실 없이 안정적으로 동작하는지 살펴보았습니다.

이번에는 그동안 이론으로만 배웠던 카프카의 핵심 기능들을 터미널에서 직접 만져보겠습니다. 김개발 씨는 입사 3개월 차 주니어 개발자입니다.

이번 주부터 팀의 카프카 인프라를 담당하게 되었습니다. 첫 업무는 주문 도메인을 위한 토픽을 생성하는 것이었습니다.

하지만 막상 터미널을 열고 나니 어디서부터 시작해야 할지 막막했습니다. 박시니어 씨가 옆에서 화면을 보며 말했습니다.

"카프카를 다루려면 가장 먼저 토픽을 만들 줄 알아야 해요. kafka-topics.sh가 바로 그 명령어예요." 토픽 관리를 쉽게 비유하자면, 마치 대형 도서관에 새로운 장서 코너를 만드는 것과 같습니다.

토픽 생성은 새로운 코너를 여는 것이고, 조회는 어떤 코너들이 있는지 목록을 확인하는 것이며, 삭제는 더 이상 사용하지 않는 코너를 정리하는 것입니다. 가장 먼저 토픽을 생성해봅시다.

위 코드의 첫 번째 블록에서 --create 옵션으로 새 토픽을 만듭니다. 여기서 핵심은 --partitions와 --replication-factor입니다.

파티션 수는 동시 처리량을 결정하고, 복제 팩터는 데이터 안정성을 결정합니다. 지난 7화에서 배운 복제 개념이 여기서 실제 설정으로 연결됩니다.

토픽을 만든 후에는 --list로 전체 목록을 확인할 수 있습니다. 그리고 --describe를 사용하면 토픽의 파티션 수, 복제 상태, 리더 파티션 정보 등 상세한 메타데이터를 볼 수 있습니다.

실무에서는 이 명령어로 토픽의 건강 상태를 진단합니다. 토픽 삭제는 신중해야 합니다.

--delete 옵션을 실행하면 토픽이 삭제되며, server.properties에서 delete.topic.enable=true로 설정되어 있어야 정상 동작합니다. 운영 환경에서 실수로 토픽을 삭제하면 복구가 어려울 수 있으니 주의해야 합니다.

박시니어 씨가 덧붙였습니다. "프로덕션에서는 토픽 이름에 도메인 접두사를 붙이는 것이 좋아요.

order-events처럼요. 그래야 여러 서비스가共用하는 클러스터에서도 어떤 토픽이 어떤 서비스의 것인지 한눈에 파악할 수 있거든요." 김개발 씨는 고개를 끄덕이며 명령어를 하나씩 실행해보았습니다.

토픽이 생성되고, 목록에 나타나고, 상세 정보가 출력되는 것을 보니 감이 잡히기 시작했습니다. 실제 현업에서는 토픽 관리를 수동으로만 하지 않습니다.

Terraform이나 Ansible 같은 IaC 도구로 토픽을 코드로 관리하는 경우가 많습니다. 하지만 기본기는 CLI로 직접 실행해보는 것이 가장 확실합니다.

초보 개발자들이 흔히 하는 실수는 파티션 수를 너무 적게 설정하는 것입니다. 트래픽이 늘어난 뒤에는 파티션 수를 늘릴 수 있지만, 줄일 수는 없습니다.

따라서 초기 설계 시 향후 트래픽을 예측하여 적절히 설정하는 것이 중요합니다.

실전 팁

💡 - 토픽 이름은 소문자와 하이픈만 사용하세요 (예: order-events, user-signups)

• 파티션 수는 늘릴 수 있지만 줄일 수 없으므로 초기 설계에 신중하세요
• 운영 환경에서 토픽 삭제 전 반드시 사용 중인 프로듀서/컨슈머가 없는지 확인하세요

---

2. 콘솔 프로듀서로 메시지 전송

토픽을 만든 김개발 씨, 이번에는 토픽에 메시지를 넣어보려 합니다. "빈 토픽만 있다면 의미가 없죠." 박시니어 씨가 콘솔 프로듀서를 열어 메시지를 입력하는 방법을 알려줍니다.

콘솔 프로듀서는 별도의 코드 없이 터미널에서 직접 카프카로 메시지를 보낼 수 있는 도구입니다. 마치 편지함에 편지를 직접 넣어보는 것처럼 간단합니다.

카프카의 기본 동작을 이해하고 테스트하는 데 필수적인 도구입니다.

다음 코드를 살펴봅시다.

# 콘솔 프로듀서 실행 (대화형 모드)
kafka-console-producer.sh \
  --topic order-events \
  --bootstrap-server localhost:9092

# 프로듀서 모드에서 입력하는 메시지
>{"orderId": 1001, "product": "키보드", "price": 50000}
>{"orderId": 1002, "product": "모니터", "price": 300000}
>{"orderId": 1003, "product": "마우스", "price": 25000}

# 파이프로 메시지 전송 (배치 모드)
echo '{"orderId": 1004, "product": "웹캠", "price": 80000}' | \
  kafka-console-producer.sh \
  --topic order-events \
  --bootstrap-server localhost:9092

# 파일에서 메시지 일괄 전송
cat orders.json | kafka-console-producer.sh \
  --topic order-events \
  --bootstrap-server localhost:9092

토픽이 준비되었습니다. 이제 그 토픽에 데이터를 넣어야 합니다.

카프카 세계에서 데이터를 보내는 역할을 하는 것이 바로 프로듀서입니다. 5화에서 프로듀서 API를 학습했지만, 코드를 작성하기 전에 CLI로 먼저 감을 잡아보는 것이 좋습니다.

김개발 씨가 콘솔 프로듀서를 실행하자, 터미널에 커서가 깜빡이며 입력 대기 상태가 되었습니다. 마치 채팅 프로그램의 입력창 같았습니다.

"여기에 JSON 형태로 메시지를 입력하면 돼요." 박시니어 씨가 설명했습니다. "각 줄이 하나의 메시지가 됩니다.

엔터를 치는 순간 카프카로 전송되는 거예요." 프로듀서를 편지 배달부에 비유할 수 있습니다. 편지(메시지)를 작성해 배달부(프로듀서)에게 건네면, 배달부는 그 편지를 지정된 우체국(토픽)으로 가져다줍니다.

콘솔 프로듀서는 가장 간단한 형태의 배달부입니다. 대화형 모드에서는 한 줄씩 메시지를 입력합니다.

위 코드에서 보듯 JSON 형태의 메시지를 세 개 입력했습니다. 각 메시지는 엔터를 치는 즉시 카프카 브로커로 전송됩니다.

더 흥미로운 기능은 파이프를 활용한 배치 전송입니다. echo 명령어의 출력을 파이프로 프로듀서에 연결하면, 별도로 프로그램을 실행하지 않고도 메시지를 보낼 수 있습니다.

이 방식은 스크립트 자동화에 매우 유용합니다. cat 명령어로 파일의 내용을 프로듀서에 전달할 수도 있습니다.

orders.json 파일에 여러 줄의 메시지가 있다면, 파일 전체를 한 번에 토픽으로 보냅니다. 대량의 테스트 데이터를 넣을 때 이 방법을 자주 사용합니다.

박시니어 씨가 옆에서 조언했습니다. "실무에서는 메시지에 **키(Key)**를 함께 보내는 경우가 많아요.

키가 있으면 같은 키를 가진 메시지는 항상 같은 파티션으로 가거든요. 순서 보장이 필요할 때 필수적이죠." 키를 포함해서 보내려면 --property parse.key=true --property key.separator=: 옵션을 추가합니다.

그러면 orderId:1001:{"product":"키보드"} 형식으로 키와 값을 구분해서 전송할 수 있습니다. 초보 개발자들이 자주 하는 실수 중 하나는 대용량 메시지를 콘솔 프로듀서로 보내려는 것입니다.

콘솔 프로듀서는 테스트용이므로, 대량의 데이터를 전송할 때는 프로듀서 API를 사용하는 것이 효율적입니다. 김개발 씨는 몇 개의 메시지를 더 입력해보며, 터미널에서 카프카로 데이터가 전송되는 과정을 체감했습니다.

"생각보다 정말 간단하네요!" 김개발 씨의 얼굴에 자신감이 생겼습니다.

실전 팁

💡 - --property parse.key=true로 메시지 키를 설정할 수 있습니다

• 콘솔 프로듀서는 테스트용이며, 대량 전송에는 프로듀서 API를 사용하세요
• 메시지는 반드시 한 줄에 하나씩 입력해야 합니다 (멀티라인은 별도 파싱 필요)

---

3. 콘솔 컨슈머로 메시지 확인

메시지를 보냈으니 이제 확인해야 합니다. 김개발 씨는 컨슈머를 실행해보려는데, 박시니어 씨가 "시작 위치를 정하는 것이 중요해요"라고 말합니다.

어디서부터 읽어올까요?

콘솔 컨슈머는 토픽에 저장된 메시지를 터미널에서 직접 읽어볼 수 있는 도구입니다. 마치 편지함에 도착한 편지를 읽어보는 것과 같습니다.

--from-beginning 옵션으로 처음부터 읽을지, 최신부터 읽을지 결정할 수 있습니다.

다음 코드를 살펴봅시다.

# 최신 메시지부터 실시간 수신 (기본)
kafka-console-consumer.sh \
  --topic order-events \
  --bootstrap-server localhost:9092

# 처음부터 모든 메시지 읽기
kafka-console-consumer.sh \
  --topic order-events \
  --from-beginning \
  --bootstrap-server localhost:9092

# 특정 파티션만 읽기
kafka-console-consumer.sh \
  --topic order-events \
  --partition 0 \
  --from-beginning \
  --bootstrap-server localhost:9092

# 메시지 키와 타임스탬프 함께 출력
kafka-console-consumer.sh \
  --topic order-events \
  --from-beginning \
  --property print.key=true \
  --property print.timestamp=true \
  --bootstrap-server localhost:9092

메시지를 토픽에 넣었습니다. 이제 그 메시지가 제대로 도착했는지 확인해야 합니다.

카프카에서 데이터를 꺼내오는 역할을 하는 것이 컨슈머입니다. 6화에서 컨슈머 API와 컨슈머 그룹을 학습했는데, CLI로 실제 동작을 확인해보겠습니다.

김개발 씨가 기본 옵션으로 컨슈머를 실행했습니다. 하지만 화면에는 아무것도 출력되지 않았습니다.

"선배님, 메시지를 보냈는데 왜 안 나올까요?" 박시니어 씨가 미소를 지으며 설명했습니다. "기본적으로 컨슈머는 현재 시점 이후에 도착하는 새로운 메시지만 읽어요.

이미 보낸 메시지를 보려면 --from-beginning 옵션을 줘야 해요." 이것은 카프카의 핵심 설계 철학과 연결됩니다. 카프카는 메시지를 소비해도 삭제하지 않습니다.

대신 **오프셋(Offset)**이라는 포인터를 관리하여 컨슈머가 어디까지 읽었는지 추적합니다. --from-beginning은 오프셋을 처음으로 되돌려 읽는 것입니다.

편지함 비유를 이어가보겠습니다. 보통 편지함에서는 새 편지부터 읽죠.

하지만 "처음부터 모든 편지를 다시 읽고 싶어"라고 말하면, 우체부가 첫 번째 편지부터 다시 보여주는 것과 같습니다. --from-beginning을 주고 실행하자, 아까 프로듀서로 보낸 세 개의 주문 메시지가 순서대로 출력되었습니다.

김개발 씨의 눈이 반짝였습니다. "이게 바로 내가 보낸 메시지네요!" 특정 파티션만 읽고 싶다면 --partition 옵션을 사용합니다.

디버깅할 때 특정 파티션의 데이터만 확인하고 싶을 때 유용합니다. 예를 들어 파티션 0에만 특정 키의 메시지가 들어가는지 확인할 수 있습니다.

--property print.key=true를 주면 메시지의 키도 함께 출력됩니다. 그리고 --property print.timestamp=true를 추가하면 각 메시지의 타임스탬프까지 볼 수 있습니다.

이 옵션들은 문제를 추적할 때 매우 유용합니다. 컨슈머를 실행한 상태에서 다른 터미널로 프로듀서를 실행하면, 실시간으로 메시지가 수신되는 것을 확인할 수 있습니다.

이 방식으로 카프카의 실시간 스트리밍 동작을 눈으로 직접 관찰할 수 있습니다. 박시니어 씨가 한 가지 더 알려주었습니다.

"컨슈머를 종료하려면 Ctrl+C를 누르면 돼요. 그리고 다시 실행하면 마지막으로 읽은 위치부터 이어서 읽게 됩니다.

이게 카프카의 오프셋 관리 덕분이에요." 초보 개발자들이 헷갈리는 부분 중 하나는 컨슈머 그룹입니다. 콘솔 컨슈머에 --group 옵션을 주지 않으면 매번 임의의 그룹으로 실행됩니다.

동일한 테스트를 반복하려면 --group을 지정하여 일관된 그룹에서 실행하는 것이 좋습니다.

실전 팁

💡 - --from-beginning으로 과거 메시지를 모두 읽어보세요 (디버깅에 필수)

• Ctrl+C로 컨슈머를 종료하면 마지막 읽은 오프셋이 저장됩니다
• --property print.key=true, print.timestamp=true로 디버깅 정보를 함께 출력하세요

---

4. 컨슈머 그룹 상태 조회

김개발 씨의 팀에서는 세 대의 서버가 동일한 토픽에서 메시지를 소비하고 있었습니다. 어느 날 한 대가 느려지자, 나머지 두 대에 부하가 집중되는 문제가 발생했습니다.

"어떤 서버가 어떤 파티션을 담당하고 있는지 확인할 수 있을까요?"

컨슈머 그룹 상태 조회는 여러 컨슈머가 토픽의 파티션을 어떻게 나누어 소비하는지 확인하는 명령어입니다. 마치 회사에서 각 팀원이 어떤 업무를分担하고 있는지 현황판을 보는 것과 같습니다.

이 명령어로 리밸런싱 문제와 파티션 할당 상태를 진단할 수 있습니다.

다음 코드를 살펴봅시다.

# 컨슈머 그룹 목록 조회
kafka-consumer-groups.sh --list \
  --bootstrap-server localhost:9092

# 특정 그룹의 상세 상태 조회
kafka-consumer-groups.sh --describe \
  --group order-consumer-group \
  --bootstrap-server localhost:9092

# 출력 예시
# GROUP, TOPIC, PARTITION, CURRENT-OFFSET, LOG-END-OFFSET, LAG
# order-consumer-group, order-events, 0, 15, 20, 5
# order-consumer-group, order-events, 1, 20, 20, 0
# order-consumer-group, order-events, 2, 10, 20, 10

# 멤버 정보까지 포함한 상세 조회
kafka-consumer-groups.sh --describe \
  --group order-consumer-group \
  --members \
  --verbose \
  --bootstrap-server localhost:9092

카프카를 운영하다 보면 "지금 컨슈머들이 정상적으로 동작하고 있는가?"라는 질문에 답해야 하는 순간이 반드시 옵니다. 바로 이럴 때 컨슈머 그룹 상태 조회 명령어가 필요합니다.

김개발 씨가 팀의 모니터링 대시보드를 보다가 알람을 발견했습니다. order-consumer-group의 랙(LAG)이 계속 증가하고 있다는 경고였습니다.

"선배님, 랙이 뭔가요? 왜 계속 늘어나는 거죠?" 박시니어 씨가 터미널을 열고 컨슈머 그룹 상태를 조회했습니다.

"랙은 소비되지 못하고 대기 중인 메시지의 수예요. 생산 속도가 소비 속도보다 빠르면 랙이 늘어나죠.

이건 곧 문제의 신호예요." 컨슈머 그룹을 한 직장의 팀에 비유해봅시다. 팀원들이 업무(파티션)를 나누어 처리하고 있는데, 한 팀원이 느리면 그 팀원의 업무가 밀리게 됩니다.

이 밀린 업무가 바로 랙입니다. 위 코드의 출력 예시를 보면 세 개의 파티션 각각에 대해 CURRENT-OFFSET, LOG-END-OFFSET, LAG가 표시됩니다.

파티션 0은 랙이 5로, 아직 5개의 메시지가 처리되지 않았음을 의미합니다. 반면 파티션 1은 랙이 0으로 모든 메시지가 처리되었습니다.

이 정보만으로도 현재 시스템의 건강 상태를 파악할 수 있습니다. 랙이 일정 수준 이상 지속되면 컨슈머를 추가하거나, 컨슈머의 처리 속도를 개선해야 합니다.

카프카 운영에서 랙 모니터링은 가장 중요한 지표 중 하나입니다. --members --verbose 옵션을 사용하면 각 컨슈머 인스턴스의 세부 정보를 볼 수 있습니다.

어떤 서버가 어떤 파티션을 할당받았는지, 컨슈머의 호스트 정보, 할당된 파티션 목록 등을 확인할 수 있습니다. 장애 진단 시 매우 유용합니다.

리밸런싱이 일어난 후에 이 명령어를 실행하면 파티션 할당이 어떻게 변경되었는지 즉시 확인할 수 있습니다. 컨슈머가 추가되거나 장애로 빠졌을 때 카프카는 자동으로 리밸런싱을 수행하는데, 이 명령어로 그 결과를 검증할 수 있습니다.

박시니어 씨가 말했습니다. "운영 환경에서는 이 명령어를 크론이나 모니터링 스크립트로 주기적으로 실행해서 랙 추이를 기록하는 것이 좋아요.

랙이 급증하는 시점을 알면 장애를 조기에 감지할 수 있거든요." 김개발 씨는 각 필드의 의미를 노트에 정리했습니다. CURRENT-OFFSET은 컨슈머가 마지막으로 읽은 위치, LOG-END-OFFSET은 토픽에 가장 최근에 쓰인 위치, LAG은 둘의 차이라는 것을 확실히 이해했습니다.

실전 팁

💡 - 랙(LAG)이 지속적으로 증가하면 컨슈머 성능을 점검하거나 인스턴스를 추가하세요

• --members --verbose로 각 컨슈머의 파티션 할당 상태를 상세히 확인할 수 있습니다
• 리밸런싱 후 반드시 이 명령어로 파티션 재할당 결과를 검증하세요

---

5. 오프셋 관리 명령어

김개발 씨가 배포한 새 버전에 버그가 있었습니다. 잘못된 메시지를 처리한 상태에서, 다시 처음부터 읽어와야 합니다.

"오프셋을 되돌릴 수 있나요?" 박시니어 씨가 오프셋 리셋 명령어를 꺼냅니다.

오프셋 관리 명령어는 컨슈머의 읽기 위치를 수동으로 변경할 수 있는 도구입니다. 마치 책에서 책갈피를 다른 페이지로 옮기는 것과 같습니다.

버그로 인한 재처리나 데이터 복구 시 반드시 필요한 명령어입니다.

다음 코드를 살펴봅시다.

# 현재 오프셋 위치 확인
kafka-consumer-groups.sh --describe \
  --group order-consumer-group \
  --bootstrap-server localhost:9092

# 모든 파티션을 처음부터 다시 읽기
kafka-consumer-groups.sh --reset-offsets \
  --to-earliest \
  --group order-consumer-group \
  --topic order-events \
  --execute \
  --bootstrap-server localhost:9092

# 특정 오프셋으로 이동
kafka-consumer-groups.sh --reset-offsets \
  --to-offset 5 \
  --group order-consumer-group \
  --topic order-events \
  --execute \
  --bootstrap-server localhost:9092

# 특정 타임스탬프 이후의 메시지부터 읽기
kafka-consumer-groups.sh --reset-offsets \
  --to-datetime 2026-04-09T10:00:00.000 \
  --group order-consumer-group \
  --topic order-events \
  --execute \
  --bootstrap-server localhost:9092

오프셋 리셋은 카프카 운영에서 가장 신중하게 다뤄야 하는 작업 중 하나입니다. 잘못하면 데이터 중복 처리나 누락이 발생할 수 있기 때문입니다.

하지만 필요할 때 정확히 사용할 줄 알아야 합니다. 김개발 씨의 상황을 다시 생각해봅시다.

새 버전 배포 후 버그를 발견했습니다. 일부 메시지가 잘못 처리되었습니다.

다행히 메시지는 카프카에 그대로 보존되어 있으므로, 오프셋을 이전 위치로 되돌려 다시 처리할 수 있습니다. 오프셋을 책갈피에 비유하면 이해하기 쉽습니다.

독서를 하다가 중간에 실수로 페이지를 넘겼다면, 책갈피를 다시 이전 페이지로 옮겨 다시 읽으면 됩니다. 카프카의 오프셋 리셋도 같은 원리입니다.

가장 자주 사용하는 옵션은 --to-earliest입니다. 이 옵션은 모든 파티션의 오프셋을 처음(0)으로 되돌립니다.

전체 데이터를 처음부터 다시 처리해야 할 때 사용합니다. 위 코드에서 --execute를 붙여야 실제로 리셋이 실행됩니다.

--execute를 빼면 dry-run 모드로 결과만 보여주고 실제 변경은 하지 않습니다. 특정 오프셋으로 정밀하게 이동하려면 --to-offset을 사용합니다.

예를 들어 --to-offset 5로 설정하면 파티션의 5번 오프셋부터 다시 읽기 시작합니다. 정확히 어디서부터 다시 처리해야 하는지 알고 있을 때 유용합니다.

가장 실무적인 옵션은 --to-datetime입니다. 특정 시점 이후의 메시지부터 다시 읽을 수 있습니다.

예를 들어 "2026년 4월 9일 오전 10시 이후에 들어온 주문만 다시 처리하고 싶다"면 이 옵션을 사용합니다. 장애 발생 시간을 기준으로 정확하게 복구할 수 있습니다.

박시니어 씨가 경고했습니다. "오프셋 리셋을 실행하기 전에 반드시 dry-run으로 먼저 확인하세요.

--execute를 빼고 실행하면 어떻게 변경될지 미리 보여줘요. 그리고 컨슈머가 모두 중지된 상태에서 리셋해야 안전합니다." 실무에서 오프셋 리셋이 필요한 상황은 크게 세 가지입니다.

첫째, 버그로 인한 재처리입니다. 둘째, 새로운 컨슈머 버전을 배포하고 처음부터 테스트해야 할 때입니다.

셋째, 데이터 분석을 위해 과거 데이터를 다시 읽어야 할 때입니다. 김개발 씨는 박시니어 씨의 조언에 따라, 먼저 --execute 없이 dry-run으로 결과를 확인한 후, 컨슈머를 중지하고 오프셋을 리셋했습니다.

컨슈머를 다시 시작하자 버그가 있던 메시지부터 올바르게 처리되기 시작했습니다. 초보 개발자들이 흔히 하는 실수는 컨슈머가 실행 중인 상태에서 오프셋을 리셋하는 것입니다.

이 경우 예상치 못한 동작이 발생할 수 있습니다. 반드시 컨슈머를 먼저 중지하고 리셋해야 합니다.

실전 팁

💡 - 오프셋 리셋 전 반드시 --execute를 빼고 dry-run으로 결과를 먼저 확인하세요

• 컨슈머가 모두 중지된 상태에서 오프셋을 리셋해야 합니다
• --to-datetime으로 장애 발생 시점을 기준으로 정밀한 복구가 가능합니다

---

6. 브로커 설정 확인 명령어

김개발 씨가 새로 합류한 팀의 카프카 클러스터를 인수받았습니다. 하지만 브로커 설정이 어떻게 되어 있는지 아무도 정확히 모른다고 했습니다.

"클러스터의 현재 설정을 전부 확인할 수 있는 방법이 있을까요?"

브로커 설정 확인 명령어는 카프카 브로커의 동적 설정과 클러스터 정보를 조회하는 도구입니다. 마치 서버의 설정 파일을 열어보는 것과 같습니다.

클러스터 구성, 파티션 분포, 동적 설정 변경 등 운영에 필수적인 정보를 확인할 수 있습니다.

다음 코드를 살펴봅시다.

# 클러스터 정보 조회
kafka-broker-api-versions.sh \
  --bootstrap-server localhost:9092

# 브로커 동적 설정 조회
kafka-configs.sh --describe \
  --broker 0 \
  --bootstrap-server localhost:9092

# 토픽별 설정 조회
kafka-configs.sh --describe \
  --entity-type topics \
  --entity-name order-events \
  --bootstrap-server localhost:9092

# 클러스터 메타데이터 조회
kafka-metadata.sh --snapshot \
  --command-id 1 \
  --bootstrap-server localhost:9092

# 로그 디렉토리 상태 확인
kafka-log-dirs.sh --describe \
  --broker-list 0 \
  --bootstrap-server localhost:9092

클러스터를 인수받거나 새로운 환경에 투입되었을 때, 가장 먼저 해야 할 일은 현재 설정을 파악하는 것입니다. 카프카 브로커의 설정을 모르면 성능 문제가 발생했을 때 원인을 찾기 어렵습니다.

김개발 씨는 팀의 카프카 클러스터가 세 대의 브로커로 구성되어 있다는 것만 알고 있었습니다. 각 브로커의 설정이 어떻게 되어 있는지, 어떤 토픽이 어느 브로커에 배치되어 있는지 전혀 모르는 상태였습니다.

박시니어 씨가 말했습니다. "클러스터를 파악하려면 여러 가지 명령어를 조합해서 봐야 해요.

하나씩 확인해봅시다." 가장 먼저 kafka-configs.sh로 브로커 설정을 확인합니다. --broker 0을 지정하면 해당 브로커의 모든 설정 값을 볼 수 있습니다.

여기에는 로그 보존 기간, 메시지 크기 제한, 스레드 수 등 카프카 동작에 영향을 미치는 핵심 설정들이 포함되어 있습니다. 이것은 마치 자동차의 엔진 점검과 같습니다.

계기판만 보면 차가 달리는 것 같지만, 엔진을 열어보아야 실제 상태를 알 수 있습니다. 브로커 설정도 표면적으로는 잘 돌아가지만, 세부 설정을 확인해야 잠재적 문제를 발견할 수 있습니다.

토픽별 설정도 확인할 수 있습니다. --entity-type topics를 주면 특정 토픽에 설정된 커스텀 값을 볼 수 있습니다.

예를 들어 retention.ms(메시지 보존 시간)나 cleanup.policy(삭제 정책) 같은 토픽 단위 설정을 확인할 수 있습니다. kafka-log-dirs.sh는 디스크 사용량을 보여줍니다.

카프카는 메시지를 디스크에 저장하므로, 디스크 용량 관리가 매우 중요합니다. 이 명령어로 각 브로커의 로그 디렉토리 크기를 확인하고, 디스크가 가득 차기 전에 조치를 취할 수 있습니다.

실무에서는 이 명령어들을 모니터링 스크립트와 결합합니다. 예를 들어 매시간 브로커 설정을 조회하여 변경된 값이 있는지 비교하거나, 디스크 사용량이 80%를 넘으면 알람을 보내는 식으로 활용합니다.

박시니어 씨가 마지막으로 조언했습니다. "클러스터를 처음 파악할 때는 kafka-topics.sh --describe로 모든 토픽의 상태를 먼저 보고, 그다음 kafka-consumer-groups.sh --list로 활성 그룹을 확인하고, 마지막으로 kafka-configs.sh로 설정을 보는 순서로 하면 효율적이에요." 김개발 씨는 노트에 CLI 명령어 체크리스트를 만들었습니다.

토픽 조회, 컨슈머 그룹 확인, 브로커 설정 검사, 디스크 용량 점검. 이 네 가지만 숙지해도 클러스터의 전반적인 상태를 파악할 수 있었습니다.

카프카의 CLI 명령어는 처음에는 옵션이 많아 복잡해 보일 수 있습니다. 하지만 하나씩 실행해보면 각 명령어의 역할이 명확해집니다.

이번 시간에 배운 명령어들을 실제 환경에서 직접 실행해보며 손에 익히는 것이 가장 좋은 학습 방법입니다. 다음 카드뉴스에서는 이렇게 CLI로 배운 카프카의 동작 원리를 바탕으로, Java와 Spring Boot에서 카프카를 프로그래밍 방식으로 연동하는 방법을 다룹니다.

CLI로 감을 잡았다면 이제 코드로 제어해볼 차례입니다.

실전 팁

💡 - kafka-configs.sh로 브로커 설정을 정기적으로 점검하여 변경 사항을 추적하세요

• kafka-log-dirs.sh로 디스크 사용량을 모니터링하고 80% 임계치를 설정하세요
• 클러스터 파악 순서: 토픽 조회 -> 컨슈머 그룹 확인 -> 브로커 설정 검사 -> 디스크 점검
• 이 카드뉴스는 "Apache Kafka 완전 정복" 코스의 8/15편입니다. 다음 편에서는 Java/Spring Boot로 카프카를 연동하는 방법을 다룹니다

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!