kcat(kafkacat) 소개
kcat이란?
kcat은 아파치 카프카를 위한 non-JVM기반의 프로듀서, 컨슈머 기능을 제공하는 도구입니다. 최초 이름은 kafkacat이었으나 2021년 8월에 kcat으로 리네임 되었습니다.
카프카에서 제공하는 kafka-console-producer, kafka-console-consumer라는 명령어도 있지만, kcat은 보다 파워풀한 기능 등을 제공하고 있어, 카프카를 다루는 사용자들에게 유용한 도구라고 할 수 있습니다. 이번 글에서는 kcat의 설치와 kcat을 이용한 명령어들을 설명하고자 합니다. kcat을 사용하기 위해서는 대상의 카프카가 필요한데, 이전 글에서 설치한 카프카 환경을 그래도 이용하여 kcat을 설명합니다. 카프카 설치가 필요하신 분들은 이전 글을 참고하시어 먼저 카프카를 설치하시기 바랍니다.
kcat 설치
github에 공개된 kcat 공식 페이지를 방문하면, Debian, openSuse, Mac OS, Fedora 등 여러 운영체제에 알맞은 설치 가이드를 제공하고 있습니다. 모든 운영체제별 설치 과정을 다루기는 어렵고, 여기서는 대표적으로 Mac OS 기반으로 설치하는 방법을 설명하도록 하겠습니다.
그 외 운영체제에서 설치하고자 하시는 분들은 kcat 공식 페이지를 참고해주세요
Mac OS에서의 kcat 설치는 brew를 이용합니다. 다음의 명령어를 입력하여 kcat을 설치합니다.
❯ brew install kcat
설치가 완료되고 나면, 정상적으로 kcat이 설치되었는지 확인해야 하는데, kcat의 버전을 확인하는 -V 옵션을 이용해 확인합니다.
❯ kcat -V
다음과 같이 확인이 되면, kcat이 정상적으로 설치된 것입니다. 이제부터는 직접 실습을 진행하면서, kcat에서 제공하는 기능들을 살펴보겠습니다.
kcat 실습해보기
kcat에서 제공하는 전체 옵션을 살펴보려면 다음의 -help 옵션과 같이 입력합니다.
❯ kcat -help
출력된 내용을 살펴보면, kcat에서 많은 기능들을 제공하고 있음을 알 수 있습니다. 여기에서는 카프카의 토픽으로 메시지를 주고받으며 몇 가지 추가 옵션들에 대해 설명하겠습니다. kcat의 실습 과정은 크게 메타정보 확인, 메시지 전송하기, 메시지 가져오기로 나눌 수 있으며, 이와 같은 순서대로 진행하겠습니다. 앞에서도 언급하였지만, kcat의 실습은 기본적으로 대상 카프카가 미리 설치되어 있어야 합니다.
메타정보 확인
kcat을 이용하여, 브로커 또는 토픽의 메타정보 리스트를 출력할 수 있습니다. 먼저 브로커의 메타정보 리스트를 출력해보겠습니다. 메타정보 리스트를 의미하는 -L 옵션과 브로커를 의미하는 -b 옵션과 브로커의 정보인 localhost:9092를 입력한 후 다음과 같이 실행합니다.
❯ kcat -L -b localhost:9092
출력된 내용을 통해 우리는 전체 브로커 리스트, 카프카 클러스터 중 컨트롤러인 브로커, 토픽 리스트 및 메타 정보를 한눈에 파악할 수 있습니다. 하지만 카프카의 토픽이 많이 있다면, 출력된 내용이 많을 것입니다.
이번에는 전체가 아닌 특정 토픽으로 한정하여 정보를 출력해보겠습니다. 여기에서 지정하는 토픽의 이름은 peter-test01입니다. 토픽을 의미하는 -t 옵션과 peter-test01 토픽 이름을 같이 입력한 후 다음과 같이 실행합니다.
❯ kcat -L -b localhost:9092 -t peter-test01
출력된 내용을 살펴보면, peter-test01 토픽에 대한 파티션 수, 리더 정보, 리플리카 정보, isr의 정보 등 토픽 관련 메타 정보들을 확인할 수 있습니다. 이러한 정보들을 통해 현재 파티션의 리플리카 상태, 리더의 정보 등을 손쉽게 파악할 수 있습니다.
또 한 가지 kcat의 유용한 기능 중 하나는 timestamp 기준으로 오프셋을 확인할 수 있습니다. 이러한 기능은 timestamp 기준으로 offset을 리셋하거나 컨슈머가 수동으로 특정 offset부터 메시지를 가져올 때 유용합니다. 쿼리를 의미하는 -Q와 토픽을 의미하는 -t 옵션과 토픽명:파티션 번호:타임스탬프를 입력하면, 해당 타임스탬프에 해당하는 오프셋을 리턴합니다.
❯ kcat -Q -b localhost:9092 -t peter-test01:0:1651811644000
타임스탬프 변환에 어려움을 겪으시는 분들은 인터넷 웹사이트 EpochConverter를 참고하시기 바랍니다.
메시지 전송하기
이번에는 kcat을 이용하여 카프카의 토픽으로 메시지를 전송해보겠습니다. 기본적인 메시지 프로듀싱은 -P 옵션을 이용하여 전송하게 됩니다. 다음의 명령어를 입력하여 실행해보겠습니다.
❯ kcat -b localhost:9092 -t peter-test02 -P
명령어를 실행한 후 프로듀싱할 hello~ how are you? 메시지를 입력하고 엔터를 입력합니다.
hello~ how are you?
위의 명령어를 실행하면, 신규 토픽인 peter-test02를 생성하게 되고, 이후에 hello~ how are you? 메시지를 전송하게 됩니다. 메시지를 전송이 완료되었다면, ctrl+D 를 눌러 종료합니다.
이번에는 단문이 아닌 파일의 내용을 카프카 토픽으로 전송해보겠습니다. 현재 위치에서 vi 명령어를 이용하여 peter.txt라는 파일을 생성한 후 다음과 같이 test-message1, test-message2라는 두 개의 메시지를 추가한 후 저장합니다.
❯ vi peter.txt
test-message1
test-message2
peter.txt 파일을 저장한 후 카프카의 토픽으로 파일의 내용을 전송하겠습니다. kcat과 -l 옵션과 peter.txt 파일명을 입력한 후 다음과 같이 실행합니다.
❯ kcat -b localhost:9092 -t peter-test02 -P -l peter.txt
명령어 실행 후 아무런 에러 메시지가 없다면, 파일의 내용을 읽은 후 성공적으로 peter-test02 토픽으로 전송했을 것입니다. 지금 전송한 메시지들은 이후 컨슈머 실습에서 모두 확인해보겠습니다.
이번에는 key:value형태로 메시지를 프로듀싱해보겠습니다. 카프카는 key:value 형태로 메시지를 전송할 수 있는데, key는 optional 이므로 추가하지 않을 수도 있습니다. kcat에서 key를 지정하는 옵션은 -K 옵션이며, 다음과 같이 입력합니다.
❯ kcat -b localhost:9092 -t peter-test02 -P -K:
명령어를 실행한 후 프로듀싱할 메시지를 입력하고 엔터를 입력합니다. 총 두 개의 메시지를 전송하려고 하며, 전송할 메시지는 1(key):foo(value), 2(key):bar(value)입니다.
1:foo
2:bar
위와 같이 메시지 입력이 완료되면, ctrl+D 를 눌러 종료합니다.
지금 실습한 예제는 메시지마다 다른 key 값을 입력하였으나, 모든 메시지에 대해 하나의 key를 지정하여 메시지를 전송할 때에는 소문자 -k 옵션과 key 값을 입력한 후 전송하면, 이후 전송하는 모든 메시지는 3이라는 동일한 key 값을 갖게 됩니다.
❯ kcat -b localhost:9092 -t peter-test02 -P -k 3
지금까지 메시지 프로듀싱에 대해 설명하였는데, -z를 이용한 메시지 압축, -X를 이용한 transactional 전송 등 다양한 옵션 등을 kcat에서 제공하고 있으니, 참고하시기 바랍니다.
메시지 가져오기
이번에는 kcat을 이용하여 카프카의 토픽에서 메시지를 가져오겠습니다. 기본적인 메시지 가져오기는 -C 옵션을 이용합니다. 다음의 명령어를 입력하여 실행해보겠습니다.
❯ kcat -b localhost:9092 -t peter-test02 -C
출력 내용을 통해 지금까지 peter-test02 토픽으로 전송했던 메시지들을 모두 가져온 것을 확인할 수 있습니다. 종료를 위해 crtl + C 버튼을 입력하여 나옵니다. 기본적인 메시지 가져오기 기능은 실습했으니, kcat에서 제공하는 다양한 옵션들에 대해 하나씩 살펴보겠습니다.
먼저 자동 exit입니다. 메시지를 끝까지 읽은 후 대기 상태가 아닌 exit를 원하는 경우가 있을 수 있습니다. 이런 경우에는 -e 옵션을 추가하면 마지막 메시지를 읽은 후 자동으로 exit가 됩니다.
❯ kcat -b localhost:9092 -t peter-test02 -C -e
다음으로는 읽고 싶은 메시지 건수를 지정할 수 있습니다. -c 옵션과 원하는 메시지 건수를 입력하면, 해당 메시지 건수만큼만 읽고 종료합니다.
❯ kcat -b localhost:9092 -t peter-test02 -C -c 2
다음으로 offset을 지정할 수 있습니다. -o 옵션과 원하는 오프셋을 입력하면, 해당 오프셋부터 메시지를 가져옵니다. 오프셋 말고도 start(맨 처음), end(맨 마지막) 등의 옵션도 지원합니다.
❯ kcat -b localhost:9092 -t peter-test02 -C -o 3
출력 내용을 통해 peter-test02 토픽의 오프셋 3번부터 마지막까지의 메시지를 가져온 것을 알 수 있습니다.
마지막으로 출력되는 포맷을 변경할 수 있습니다. 옵션은 -f이며, 이후 출력 포맷을 정의하면 됩니다. kcat에서 지원하는 출력 포맷 옵션들이 있는데, 상세한 리스트는 아래와 같습니다.
예제에서 나와있는 내용을 이용하여 메시지를 출력해보겠습니다.
❯ kcat -b localhost:9092 -t peter-test02 -C -f 'Topic %t [%p] at offset %o: key %k: %s\n'
앞에서 메시지 전송하기를 할 때 일부 메시지는 key를 지정하지 않았고, 마지막에 전송한 foo, bar 메시지에 대해서만 key를 지정했습니다. 출력 내용을 보면, foo, bar 메시지의 key 값이 1, 2로 모두 확인됩니다. 다른 메시지들은 추가로 key 값을 지정하지 않았으므로 표시되지 않고 있습니다.
여기에서 다루지 않았지만, -G를 이용하여 컨슈머 그룹 이름을 지정할 수 있고, -p로 파티션 지정, -o와 타임스탬프를 이용하여, 정해진 타임 내에서만 메시지를 가져올 수 있는 기능들도 있습니다.
마무리
지금까지 kcat를 이용한 메타 정보 확인하기, 메시지 전송하기, 메시지 가져오기 등에 대해 설명하였습니다. 여기에서는 다루지 않았지만, kcat은 스키마 레지스트리 지원, avro 포맷 지원 등 다양한 기능들을 제공하고 있습니다. 카프카를 사용 중인데, 이번 글을 통해 kcat을 처음 접해보셨다면 꼭 한번 사용해보시기를 적극 권장합니다. 긴 글 끝까지 읽어주셔서 감사합니다.
