Kafka 명령줄 도구 이해하기: CLI 참조 가이드

Kafka의 명령줄 도구는 기본적인 운영 질문에 가장 빠르게 답할 수 있는 방법입니다: 이 토픽이 존재하는가, 어떤 브로커가 이 파티션을 리드하는가, 토픽 안에 무엇이 있는가, 왜 이 컨슈머 그룹이 뒤처져 있는가, 이 클라이언트가 클러스터에 인증할 수 있는가? 모든 작업에 필요하지는 않으며, 대부분의 프로덕션 변경은 여전히 자동화를 통해 이루어져야 하지만, 배포가 중단되거나 늦은 밤 데이터 질문이 있을 때 CLI는 종종 사실에 도달하는 가장 짧은 경로입니다.

아래 예제는 스크립트가 PATH에 있다고 가정합니다. 많은 설치에서 Kafka의 bin/ 디렉토리 아래에 있으므로 동일한 명령어가 bin/kafka-topics.sh로 실행될 수 있습니다. 보안 클러스터의 경우 대부분의 명령어는 --command-config client.properties도 필요하며, 해당 파일에는 SASL, SSL 및 기타 클라이언트 설정이 포함됩니다.

핵심 Kafka CLI 도구

Kafka 배포판에는 일반적으로 다양한 스크립트와 실행 파일이 포함된 bin/ 디렉토리가 포함됩니다. Kafka를 효과적으로 관리하기 위해 가장 자주 사용되는 도구에 초점을 맞출 것입니다.

1. kafka-topics.sh

이것은 가장 자주 사용되는 명령줄 도구입니다. Kafka 토픽을 생성, 나열, 설명, 삭제, 변경 및 관리할 수 있습니다. 토픽 관리는 Kafka 내에서 데이터 스트림을 구성하는 데 기본적입니다.

일반적인 하위 명령어 및 인수:

• --create: 새 토픽을 생성합니다.
• --list: 클러스터의 모든 토픽을 나열합니다.
• --describe: 특정 토픽에 대한 자세한 정보를 제공합니다.
• --delete: 하나 이상의 토픽을 삭제합니다.
• --alter: 기존 토픽의 구성을 수정합니다.
• --topic <토픽_이름>: 토픽 이름을 지정합니다.
• --partitions <파티션_수>: 토픽의 파티션 수를 설정합니다(--create와 함께 사용).
• --replication-factor <팩터>: 토픽의 복제 팩터를 설정합니다(--create와 함께 사용).
• --bootstrap-server <호스트:포트>: 연결할 Kafka 브로커를 지정합니다.

예제:

• my_topic이라는 토픽을 3개의 파티션과 복제 팩터 2로 생성:

  kafka-topics.sh --create --topic my_topic --partitions 3 --replication-factor 2 --bootstrap-server kafka-broker-1:9092,kafka-broker-2:9092
  

• 클러스터의 모든 토픽 나열:

  kafka-topics.sh --list --bootstrap-server kafka-broker-1:9092
  

• my_topic이라는 토픽 설명:

  kafka-topics.sh --describe --topic my_topic --bootstrap-server kafka-broker-1:9092
  

  파티션, 리더, 복제본 및 ISR(동기화된 복제본)과 같은 세부 정보가 표시됩니다.

• old_topic이라는 토픽 삭제:

  kafka-topics.sh --delete --topic old_topic --bootstrap-server kafka-broker-1:9092
  

  참고: 토픽 삭제는 Kafka 브로커 구성에서 활성화되어야 합니다(delete.topic.enable=true).

2. kafka-console-producer.sh

이 도구를 사용하면 표준 입력에서 Kafka 토픽으로 메시지를 보낼 수 있습니다. 프로듀서 테스트, 샘플 데이터 주입 또는 수동 메시지 게시에 매우 유용합니다.

일반적인 인수:

• --topic <토픽_이름>: 대상 토픽을 지정합니다.
• --bootstrap-server <호스트:포트>: 연결할 Kafka 브로커를 지정합니다.
• --property <키>=<값>: 프로듀서 속성을 설정할 수 있습니다(예: key.serializer, value.serializer).
• --producer-property <키>=<값>: --property와 유사하지만 프로듀서 측 구성에 특화되어 있습니다.

예제:

• my_topic에 메시지 보내기:

  kafka-console-producer.sh --topic my_topic --bootstrap-server kafka-broker-1:9092
  

  실행 후 줄 단위로 메시지를 입력할 수 있습니다. Ctrl+C를 눌러 종료합니다.

• 키와 함께 메시지 보내기(JSON 형식):

  kafka-console-producer.sh --topic my_topic --bootstrap-server kafka-broker-1:9092 --property parse.key=true --property key.separator=':'
  

  이제 키:값 쌍을 입력할 수 있으며, Kafka는 지정된 키와 함께 메시지를 보냅니다.

3. kafka-console-consumer.sh

이 도구는 하나 이상의 Kafka 토픽을 구독하고 수신한 메시지를 표준 출력으로 출력합니다. 컨슈머 테스트, 토픽 데이터 검사, 프로듀서/컨슈머 애플리케이션 디버깅에 필수적입니다.

일반적인 인수:

• --topic <토픽_이름>: 소비할 토픽을 지정합니다.
• --bootstrap-server <호스트:포트>: 연결할 Kafka 브로커를 지정합니다.
• --group-id <그룹_ID>: 컨슈머 그룹 ID를 지정합니다. 오프셋 관리 및 여러 컨슈머가 소비 부하를 공유할 수 있도록 하는 데 중요합니다.
• --from-beginning: 토픽 로그의 처음부터 메시지를 읽습니다.
• --offset <오프셋>: 특정 오프셋부터 소비를 시작합니다.
• --partition <파티션_ID>: 특정 파티션에서 소비합니다.
• --property <키>=<값>: 컨슈머 속성을 설정할 수 있습니다(예: value.deserializer).

예제:

• my_topic의 모든 메시지 소비:

  kafka-console-consumer.sh --topic my_topic --bootstrap-server kafka-broker-1:9092
  

• my_group 컨슈머 그룹에 대해 my_topic의 처음부터 메시지 소비:

  kafka-console-consumer.sh --topic my_topic --group-id my_group --from-beginning --bootstrap-server kafka-broker-1:9092
  

• 오프셋과 키를 출력하며 메시지 소비:

  kafka-console-consumer.sh --topic my_topic --bootstrap-server kafka-broker-1:9092 --property print.key=true --property key.separator="\t" --property print.offset=true --property print.headers=true
  

4. kafka-consumer-groups.sh

이 도구는 컨슈머 그룹을 관리하고 검사하는 데 사용됩니다. 컨슈머 지연 이해, 파티션 재할당, 소비 문제 해결에 필수적입니다.

일반적인 하위 명령어 및 인수:

• --list: 클러스터의 모든 컨슈머 그룹을 나열합니다.
• --describe: 특정 컨슈머 그룹에 대한 세부 정보(지연 포함)를 제공합니다.
• --bootstrap-server <호스트:포트>: 연결할 Kafka 브로커를 지정합니다.
• --group <그룹_ID>: 컨슈머 그룹 ID를 지정합니다.
• --reset-offsets: 컨슈머 그룹의 오프셋을 재설정합니다.
• --topic <토픽_이름>: 오프셋 재설정을 위한 토픽을 지정합니다.
• --to-earliest: 오프셋을 사용 가능한 가장 이른 메시지로 재설정합니다.
• --to-latest: 오프셋을 사용 가능한 가장 최신 메시지로 재설정합니다.
• --execute: 오프셋 재설정 작업을 실행합니다.

예제:

• 모든 컨슈머 그룹 나열:

  kafka-consumer-groups.sh --list --bootstrap-server kafka-broker-1:9092
  

• my_group 컨슈머 그룹 설명 및 지연 표시:

  kafka-consumer-groups.sh --describe --group my_group --bootstrap-server kafka-broker-1:9092
  

  출력에는 토픽, 파티션, 현재 오프셋, 로그 끝 오프셋 및 지연이 표시됩니다.

• my_topic의 my_group에 대한 오프셋을 가장 이른 메시지로 재설정:

  kafka-consumer-groups.sh --group my_group --topic my_topic --reset-offsets --to-earliest --execute --bootstrap-server kafka-broker-1:9092
  

  이 명령어는 컨슈머가 읽기 시작할 위치에 영향을 미치므로 주의해서 사용하십시오.

5. kafka-log-dirs.sh

이 도구는 Kafka 브로커의 로그 디렉토리를 검사하는 데 도움이 됩니다. 디스크 사용량을 이해하고 토픽 데이터를 찾는 데 유용할 수 있습니다.

일반적인 인수:

• --bootstrap-server <호스트:포트>: 연결할 Kafka 브로커를 지정합니다.
• --topic <토픽_이름>: 특정 토픽에 대한 디렉토리만 표시하도록 출력을 필터링합니다.

예제:

• 브로커의 로그 디렉토리 나열:

  kafka-log-dirs.sh --bootstrap-server kafka-broker-1:9092
  

• 특정 토픽의 로그 디렉토리 표시:

  kafka-log-dirs.sh --bootstrap-server kafka-broker-1:9092 --topic my_topic
  

6. kafka-preferred-replica-election.sh

이 스크립트는 토픽에 대한 선호 복제본 선출을 시작합니다. 선호 복제본은 복제 팩터를 기반으로 파티션의 리더로 선택된 브로커입니다. 브로커에 장애가 발생하여 선호되지 않는 복제본이 리더가 된 경우, 이 도구를 사용하여 리더십을 선호 복제본으로 되돌릴 수 있습니다.

일반적인 인수:

• --topic <토픽_이름>: 선호 복제본을 선출할 토픽을 지정합니다.
• --broker-list <브로커_ID1,브로커_ID2,...>: 쉼표로 구분된 브로커 ID 목록을 지정합니다.
• --bootstrap-server <호스트:포트>: 연결할 Kafka 브로커를 지정합니다.

예제:

• my_topic에 대한 선호 복제본 선출:

  kafka-preferred-replica-election.sh --topic my_topic --bootstrap-server kafka-broker-1:9092
  

• 여러 토픽에 대한 선호 복제본 선출:

  kafka-preferred-replica-election.sh --topic topic1,topic2 --bootstrap-server kafka-broker-1:9092
  

중요한 고려 사항 및 모범 사례

• --bootstrap-server는 핵심입니다: Kafka 클러스터에 연결하려면 항상 올바른 --bootstrap-server 인수를 지정해야 합니다. 일반적으로 브로커의 호스트:포트를 쉼표로 구분한 목록입니다.
• 환경: 이러한 명령어는 일반적으로 Kafka 설치의 bin/ 디렉토리에 있습니다. 이 디렉토리로 이동하거나 Kafka의 bin 디렉토리가 시스템의 PATH에 있는지 확인해야 합니다.
• 권한: 이러한 명령어를 실행하는 사용자가 Kafka 브로커에 도달하는 데 필요한 네트워크 액세스 권한이 있는지 확인하십시오.
• 구성: 많은 CLI 도구는 --property 또는 --producer-property/--consumer-property 인수를 통해 Kafka 클라이언트 구성을 수락할 수 있습니다. 이는 기본 직렬화/역직렬화를 재정의하거나 다른 특정 클라이언트 구성을 설정하는 데 유용합니다.
• 보안: 보안 Kafka 클러스터(예: SSL/TLS 또는 SASL 인증 사용)의 경우 이러한 도구에 추가 보안 관련 인수(예: 클라이언트 속성 파일을 가리키는 --command-config)를 전달해야 합니다.
• 토픽 삭제: 토픽 삭제는 민감한 작업이며 Kafka 브로커의 server.properties 파일에서 delete.topic.enable=true를 사용하여 명시적으로 활성화해야 합니다.

프로덕션에서 CLI를 안전하게 사용하는 방법

CLI를 먼저 검사 도구로 사용하고 그 다음에 변경 도구로 사용하십시오. --list, --describe 및 짧은 콘솔 읽기는 위험이 낮습니다. --delete, --alter, 파티션 증가 및 오프셋 재설정은 클러스터 동작을 변경하므로 가능하면 애플리케이션 변경과 동일한 검토 경로를 거쳐야 합니다.

실용적인 프로덕션 세션은 일반적으로 클라이언트 구성 파일로 시작합니다:

cat client.properties
# security.protocol=SASL_SSL
# sasl.mechanism=SCRAM-SHA-512
# sasl.jaas.config=...

그런 다음 모든 명령어에 이를 포함합니다:

kafka-topics.sh --bootstrap-server kafka-1:9093 --command-config client.properties --describe --topic orders

콘솔 컨슈머의 경우 실제 애플리케이션 그룹에 실수로 참여하지 않도록 하십시오. 데이터를 검사할 때는 임시 그룹 ID를 사용하고, 명령어가 종료되도록 --max-messages를 사용하십시오:

kafka-console-consumer.sh \
  --bootstrap-server kafka-1:9093 \
  --command-config client.properties \
  --topic orders \
  --group debug-orders-$(date +%s) \
  --from-beginning \
  --max-messages 5 \
  --property print.key=true \
  --property print.offset=true

이 작은 습관은 디버그 명령어가 라이브 서비스에서 파티션을 도용하는 것을 방지합니다. 또한 그룹 이름이 의도를 명확하게 하기 때문에 더 깔끔한 감사 추적을 남깁니다.

CLI는 지루할 때 가장 좋습니다: 하나의 명령어로 검사하고, 하나의 명령어로 확인하며, 상태를 변경하는 모든 명령어에 대한 명확한 기록을 남깁니다.

일상적인 문제 해결 레시피

프로듀서가 성공적으로 쓰고 있다고 말하지만 컨슈머 팀이 아무것도 보지 못하는 경우 토픽부터 시작하십시오:

kafka-topics.sh --bootstrap-server kafka-1:9092 --describe --topic orders

토픽 이름, 파티션 수, 리더 가용성 및 동기화된 복제본을 확인하십시오. 토픽 이름의 오타는 개발 클러스터에서 자동 토픽 생성이 활성화된 경우 중단된 파이프라인과 정확히 동일하게 보일 수 있습니다. 프로덕션에서는 오프라인 파티션이나 축소되는 ISR이 있는 토픽은 애플리케이션 코드보다 먼저 브로커 또는 복제 문제를 가리킵니다.

다음으로 임시 그룹으로 작은 샘플을 읽으십시오:

kafka-console-consumer.sh \
  --bootstrap-server kafka-1:9092 \
  --topic orders \
  --group debug-orders-$(date +%s) \
  --max-messages 10 \
  --property print.key=true \
  --property print.timestamp=true \
  --property print.offset=true

레코드가 나타나면 Kafka에 데이터가 있으며 문제는 실제 컨슈머 그룹, 해당 오프셋, 구독 또는 처리 로직일 가능성이 높습니다. 레코드가 나타나지 않으면 프로듀서 토픽, 직렬화기, 인증 및 프로듀서가 다른 클러스터에 쓰고 있는지 확인하십시오.

지연 질문의 경우 그룹으로 바로 이동하십시오:

kafka-consumer-groups.sh --bootstrap-server kafka-1:9092 --describe --group orders-writer

총 지연에서 멈추지 마십시오. 파티션을 비교하십시오. 큰 지연이 있는 단일 파티션은 모든 파티션이 적당한 지연을 가진 경우와 다른 문제를 의미합니다. 단일 파티션 지연은 종종 키 편향 또는 하나의 잘못된 컨슈머 할당을 의미합니다. 균일한 지연은 일반적으로 전체 애플리케이션이 입력 속도보다 느리다는 것을 의미합니다.

"무엇이 변경되었는가?" 질문의 경우 토픽 구성을 검사하십시오:

kafka-configs.sh \
  --bootstrap-server kafka-1:9092 \
  --entity-type topics \
  --entity-name orders \
  --describe

여기서 보존 변경, 정리 정책 문제, 압축 재정의 및 서비스의 가정과 다른 메시지 크기 설정을 발견할 수 있습니다.

CLI 출력은 모니터링을 대체하지 않지만 불확실성을 줄이는 데 탁월합니다. 실제 사고에서 티켓에 붙여넣은 몇 가지 명령어 출력은 토픽이 존재하는지, 레코드가 있는지, 그룹이 실제로 이동 중인지에 대한 논쟁을 모두에게 없앨 수 있습니다.

주의해서 다루어야 할 명령어

일부 Kafka CLI 명령어는 짧기 때문에 무해해 보입니다. 무해하지 않습니다.

kafka-topics.sh --alter --partitions는 파티션 수만 증가시킵니다. 변경을 후회해도 나중에 줄일 수 없습니다. 더 많은 파티션은 컨슈머 병렬 처리를 도울 수 있지만 새 레코드의 키 분포를 변경하고 키 범위의 모든 이벤트가 더 작은 파티션 세트에 도달할 것으로 예상한 시스템의 가정을 깨뜨릴 수 있습니다.

kafka-consumer-groups.sh --reset-offsets --execute는 그룹이 다음에 읽을 위치를 변경합니다. 먼저 --dry-run을 사용하고, 영향을 받는 컨슈머를 중지하고, 이전 오프셋을 기록하십시오. 가장 이른 것으로 재설정하면 멱등성이 없는 시스템에 데이터를 재생할 수 있습니다. 가장 최신으로 재설정하면 비즈니스에서 여전히 처리할 것으로 예상하는 데이터를 건너뛸 수 있습니다.

kafka-topics.sh --delete는 클러스터 구성 및 정책에 따라 다르지만 삭제가 허용되는 경우 데이터베이스 테이블을 삭제하는 것처럼 취급해야 합니다. 클러스터를 확인하고, 토픽을 확인하고, 다른 환경이 동일한 명명 규칙을 사용하는지 확인하십시오. orders-test라는 프로덕션 토픽은 실제 서비스가 의존하는 경우 여전히 프로덕션입니다.

반복 가능한 작업의 경우 클러스터, 토픽, 그룹 및 명령어 구성에 대한 명시적 변수를 사용하여 명령어를 런북 또는 스크립트에 넣으십시오. CLI는 조사에 훌륭하지만 프로덕션 변경은 지루하고, 검토되고, 감사하기 쉬워야 합니다.