그냥 기억하기 싫어서 기록하는 블로그

kcat(이전 명칭: kafkacat)은 Kafka를 테스트하고 디버깅하는 데 매우 유용한 명령줄 도구입니다. Kafka 클러스터, 토픽, 파티션 등에 대한 메타데이터 조회 기능을 제공하며, Producer 및 Consumer 모드에서 각각 메시지를 전송하고 수신하는 기능을 가지고 있습니다. 

Producer 모드에서 kcat은 표준 입력 또는 파일로부터 메시지를 읽어 지정된 Kafka 클러스터에 토픽 파티션으로 전송할 수 있습니다. Consumer 모드에서는 Kafka 토픽 파티션으로부터 메시지를 읽어 표준 출력으로 내보내며, 이를 통해 메시지 스트림의 내용을 실시간으로 모니터링하고 분석할 수 있습니다.

kcat은 kafka-console-consumer.sh와 kafka-console-producer.sh와 같은 Kafka의 기본 제공 명령줄 도구들과 유사해 보일 수 있지만, 더 다양하고 고급 기능을 제공합니다. 이 문서에서는 kcat의 설치 방법부터 기본적인 사용법에 대하여 다루었습니다.

kcat 설치 방법

kcat을 사용하기 전에, 시스템에 설치되어 있지 않다면 먼저 설치 과정을 거쳐야 합니다. 여기서는 macOS와 Ubuntu 시스템에서 kcat을 설치하는 방법에 대하여 작성하였습니다.

macOS 설치

macOS에서 kcat을 설치하는 가장 간단한 방법은 Homebrew를 사용합니다. Homebrew는 macOS 용 패키지 관리자입니다. Homebrew의 명령어를 이용하여 터미널에서 kcat을 설치할 수 있습니다

> brew update
> brew install kcat

Ubuntu 설치

Ubuntu에서 kcat을 설치하는 과정은 apt 패키지 관리자를 통해 간단하게 수행할 수 있습니다.

> sudo apt-get update
> sudo apt-get -y install kafkacat

설치가 완료되었다면 다음과 같이 명령어를 통하여 정상적으로 잘 설치가 되었는지 확인할 수 있습니다.

> kcat -V

Create Topic

Kcat은 Kafka 클러스터와 상호작용하는 데 매우 유용한 도구이지만, 아쉽게도 직접적으로 토픽을 생성하는 기능을 제공하지 않습니다. Kafka 토픽 생성은 일반적으로 Kafka의 내장 명령줄 도구인 kafka-topics.sh를 사용하여 수행됩니다. 토픽을 생성할 때는 토픽의 이름, 파티션 수, 복제 계수(replication factor)와 같은 중요한 설정을 지정해야 합니다. 예를 들어, my-topic이라는 이름의 토픽을 파티션 3개와 복제 계수 2로 설정하여 생성하기 위해서는 다음과 같은 명령어를 사용할 수 있습니다.

토픽생성 명령어

# kafka-topics.sh --create --bootstrap-server <브로커 주소> --replication-factor <복제본개수> --partitions <파티션개수> --topic <토픽명>
> kafka-topics.sh --create --bootstrap-server localhost:9092 --replication-factor 2 --partitions 3 --topic my-topic

이 명령어는 Kafka 클러스터의 브로커 주소를 --bootstrap-server 옵션을 통해 지정하고, --replication-factor와 --partitions 옵션으로 각각 복제본 수와 파티션 수를 설정하여 my-topic 토픽을 생성합니다.

메타데이터 출력

Kcat을 활용하여 Kafka 클러스터의 메타데이터를 조회가 가능하며 사용 가능한 토픽 목록과 같은 정보를 얻을 수 있습니다.

• '-L' 옵션을 사용하여 Kafka 클러스터의 메타데이터를 출력할 수 있습니다. 이 옵션은 클러스터에 대한 정보, 예를 들어 사용 가능한 토픽, 각 토픽의 파티션 정보, 리플리케이션 상태 등을 포함한 전반적인 상태 보고서를 제공합니다.
• Kafka 클러스터와의 연결을 설정하기 위해서는 '-b' 옵션을 통해 브로커 주소를 입력합니다.

# kcat -L -b 브로커주소
> kcat -L -b localhost:10000

Producer 사용법

kcat을 이용한 Kafka Producer의 기본 사용법에 대해 설명하겠습니다. kcat의 Producer 모드를 사용하면, 사용자는 Kafka 토픽으로 메시지를 쉽게 전송할 수 있습니다. 이 모드를 활성화하려면, 다음 단계를 따르면 됩니다.

기본 방식의 메시지 전송

먼저 '-P' 옵션을 사용하여 kcat을 Producer 모드로 설정합니다. 이 모드는 Kafka 토픽에 메시지를 전송하기 위한 것입니다. '-b' 옵션으로 Kafka 브로커의 주소를 지정합니다. 브로커는 Kafka 시스템에서 메시지를 받아 처리하는 서버를 말합니다. '-t' 옵션을 사용해 데이터를 전송할 토픽을 지정합니다.

데이터 입력이 완료되면, Ctrl+D를 눌러 데이터 전송을 완료하고 kcat 명령을 종료합니다. 이는 표준 입력의 끝을 나타내며, kcat이 메시지 전송을 마무리하고 종료하도록 합니다.

kcat -P -b localhost:10000 -t my-topic
aaa
bbb
ccc

Key 값을 이용한 Partitioner 메시지 전송

추가적으로 kcat의 '-K:' 옵션을 사용하면 제공된 키를 사용하여 메시지를 특정 파티션으로 라우팅합니다. 이 기능은 Kafka의 키 기반 메시지 분할(partitioning) 메커니즘을 활용하는 것으로, 같은 키를 가진 메시지들이 항상 같은 파티션에 할당되도록 보장합니다. 이는 메시지의 순서를 유지하거나, 관련 메시지를 동일한 파티션에 그룹화하는 데 유용합니다.

'-K:' 옵션을 사용할 때는 메시지를 "키:값" 형식으로 작성하여 전송해야 합니다. 이때, 키와 값 사이에는 콜론(':')을 사용하여 구분합니다. 예를 들어, '1:Hello World'와 같은 형식으로 메시지를 작성하면, '1'이 메시지의 키가 되고, 'Hello World'가 메시지의 값이 됩니다. 메시지를 전송할 때 해당 키가 항상 동일한 파티션에 할당됩니다. 이는 데이터의 일관성과 순서를 유지할 수 있습니다.

kcat -P -b localhost:10000 -t my-topic -K:

파일 형식의 메시지 전송

위와 같은 방법으로도 Kafka에 메시지를 전송하는 과정은 매우 간단하고 직관적이지만, 수동으로 반복하여 메시지를 전송하거나 대량의 데이터를 한 번에 전송하는 경우 불편함을 겪을 수 있습니다. 이러한 작업을 효율적으로 처리하기 위해 kcat은 파일을 통해 미리 입력된 데이터를 전송하는 기능을 제공합니다.

kcat -P -b localhost:10000 -t my-topic -l data.txt

Consumer 사용법

기본 방식의 메시지 수신

kcat에서 '-C' 옵션은 Consumer 모드를 활성화하여 지정된 Kafka 토픽의 데이터를 가져오고, 이를 표준출력으로 출력하는 기능을 제공합니다. 이 옵션을 사용하면, Kafka 토픽에 저장된 메시지를 실시간으로 읽어 볼 수 있습니다. 여기서 -b 옵션은 Kafka 브로커의 주소를 지정하며, -t 옵션은 데이터를 가져올 토픽의 이름을 지정합니다. 이 명령을 실행하면, kcat은 my-topic 토픽으로부터 메시지를 읽어 표준 출력으로 내보냅니다. 이 과정은 Ctrl+C를 눌러 중단할 수 있습니다.

kcat -C -b localhost:10000 -t my-topic

Consumer Group 사용법

kcat에서 '-G' 옵션은 Consumer Group 모드를 활성화하여, 여러 개의 Consumer가 속한 Group을 지정하고, Kafka 토픽의 데이터를 여러 Consumer에 분산해서 처리할 수 있게 합니다. 이 기능은 Kafka의 Consumer Group 메커니즘을 활용하는 것으로, 메시지의 부하를 여러 Consumer 사이에 균등하게 분산시켜 처리할 수 있게 해주며, 데이터 처리의 확장성과 안정성을 높일 수 있습니다.

'-G'옵션을 적용했다면 위와는 다르게 '-t' 옵션을 제거해야 합니다.

kcat -C -G my-group -b localhost:10000 my-topic

Kafka에서 같은 Consumer Group에 속한 여러 Consumer를 사용할 경우, Consumer 리밸런싱이라는 과정을 통해 각 Consumer에게 특정 파티션들이 자동으로 할당되어 지정된 파티션으로 부터 데이터를 수신할 수 있습니다.

Consumer 출력 포맷 설정

kcat을 사용할 때, Consumer로 출력되는 데이터 포맷을 사용자가 지정할 수 있어, 출력 데이터를 더욱 보기 쉽고, 분석하기 용이하게 만들 수 있습니다. 이러한 출력 포맷은 kcat의 다양한 옵션을 통해 커스터마이징될 수 있으며, 메시지의 키, 값, 타임스탬프, 파티션 정보 등 다양한 메타데이터를 포함할 수 있습니다. 출력 포맷 설정에 대한 자세한 옵션은 kcat -h 명령어를 실행함으로써 확인할 수 있습니다.

kcat -C  -b localhost:10000 -t my-topic -f 'Topic[%t] Partition[%p] Offset[%o] %k:%s\n'

참조

https://docs.confluent.io/platform/current/tools/kafkacat-usage.html