Compreendendo as Ferramentas de Linha de Comando do Kafka: Guia de Referência da CLI

Apache Kafka é uma poderosa plataforma distribuída de streaming de eventos que permite pipelines de dados em tempo real com alta throughput, tolerância a falhas e escalabilidade. Embora o Kafka possa ser gerenciado e interagido programaticamente através de suas APIs, suas ferramentas de interface de linha de comando (CLI) oferecem uma maneira direta e eficiente de realizar tarefas administrativas essenciais, gerenciar tópicos, interagir com consumidores e monitorar a saúde do cluster. Este guia fornece uma referência abrangente das ferramentas CLI do Kafka mais comumente usadas, detalhando seu propósito, argumentos essenciais e casos de uso práticos.

Compreender essas ferramentas é crucial para administradores, desenvolvedores Kafka e qualquer pessoa envolvida no gerenciamento ou solução de problemas de clusters Kafka. Elas permitem inspeção, manipulação e diagnóstico rápidos sem a necessidade de escrever scripts ou aplicativos personalizados para cada operação simples.

Ferramentas Essenciais da CLI do Kafka

As distribuições do Kafka geralmente incluem um diretório bin/ contendo vários scripts e executáveis. Focaremos nos mais frequentemente usados para gerenciar o Kafka de forma eficaz.

1. kafka-topics.sh

Esta é, sem dúvida, a ferramenta de linha de comando mais frequentemente usada. Ela permite criar, listar, descrever, excluir, alterar e gerenciar tópicos do Kafka. O gerenciamento de tópicos é fundamental para organizar streams de dados dentro do Kafka.

Subcomandos e Argumentos Comuns:

• --create: Cria um novo tópico.
• --list: Lista todos os tópicos no cluster.
• --describe: Fornece informações detalhadas sobre tópicos específicos.
• --delete: Exclui um ou mais tópicos.
• --alter: Modifica a configuração de um tópico existente.
• --topic <topic_name>: Especifica o nome do tópico.
• --partitions <num_partitions>: Define o número de partições para um tópico (usado com --create).
• --replication-factor <factor>: Define o fator de replicação para um tópico (usado com --create).
• --bootstrap-server <host:port>: Especifica o broker Kafka ao qual se conectar.

Exemplos:

• Criar um tópico chamado my_topic com 3 partições e um fator de replicação de 2:
  bash kafka-topics.sh --create --topic my_topic --partitions 3 --replication-factor 2 --bootstrap-server kafka-broker-1:9092,kafka-broker-2:9092

• Listar todos os tópicos no cluster:
  bash kafka-topics.sh --list --bootstrap-server kafka-broker-1:9092

• Descrever um tópico chamado my_topic:
  bash kafka-topics.sh --describe --topic my_topic --bootstrap-server kafka-broker-1:9092
  Isso mostrará detalhes como partições, líder, réplicas e ISRs (In-Sync Replicas).

• Excluir um tópico chamado old_topic:
  bash kafka-topics.sh --delete --topic old_topic --bootstrap-server kafka-broker-1:9092
  Nota: A exclusão de tópicos precisa ser habilitada nas configurações do broker Kafka (delete.topic.enable=true).

2. kafka-console-producer.sh

Esta ferramenta permite enviar mensagens para um tópico Kafka a partir da entrada padrão. É inestimável para testar produtores, injetar dados de amostra ou publicar mensagens manualmente.

Argumentos Comuns:

• --topic <topic_name>: Especifica o tópico de destino.
• --bootstrap-server <host:port>: Especifica o broker Kafka ao qual se conectar.
• --property <key>=<value>: Permite definir propriedades do produtor (por exemplo, key.serializer, value.serializer).
• --producer-property <key>=<value>: Semelhante a --property, mas especificamente para configurações do lado do produtor.

Exemplos:

• Enviar mensagens para my_topic:
  bash kafka-console-producer.sh --topic my_topic --bootstrap-server kafka-broker-1:9092
  Depois de executar isso, você pode digitar mensagens linha por linha. Pressione Ctrl+C para sair.

• Enviar mensagens com chaves (formato JSON):
  bash kafka-console-producer.sh --topic my_topic --bootstrap-server kafka-broker-1:9092 --property parse.key=true --property key.separator=':'
  Agora você pode digitar pares chave:valor, e o Kafka os enviará com a chave especificada.

3. kafka-console-consumer.sh

Esta ferramenta se inscreve em um ou mais tópicos Kafka e imprime as mensagens que recebe na saída padrão. É essencial para testar consumidores, inspecionar dados em tópicos e depurar aplicativos produtor/consumidor.

Argumentos Comuns:

• --topic <topic_name>: Especifica o(s) tópico(s) do(s) qual(is) consumir.
• --bootstrap-server <host:port>: Especifica o broker Kafka ao qual se conectar.
• --group-id <group_id>: Especifica o ID do grupo de consumidores. Isso é importante para gerenciar offsets e permitir que vários consumidores compartilhem a carga de consumo.
• --from-beginning: Lê mensagens desde o início do log do tópico.
• --offset <offset>: Começa a consumir a partir de um offset específico.
• --partition <partition_id>: Consome de uma partição específica.
• --property <key>=<value>: Permite definir propriedades do consumidor (por exemplo, value.deserializer).

Exemplos:

• Consumir todas as mensagens de my_topic:
  bash kafka-console-consumer.sh --topic my_topic --bootstrap-server kafka-broker-1:9092

• Consumir mensagens desde o início de my_topic para o grupo de consumidores my_group:
  bash kafka-console-consumer.sh --topic my_topic --group-id my_group --from-beginning --bootstrap-server kafka-broker-1:9092

• Consumir mensagens com offsets e chaves impressos:
  bash 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

Esta ferramenta é usada para gerenciar e inspecionar grupos de consumidores. É vital para entender o lag do consumidor, reatribuir partições e solucionar problemas de consumo.

Subcomandos e Argumentos Comuns:

• --list: Lista todos os grupos de consumidores no cluster.
• --describe: Fornece detalhes sobre grupos de consumidores específicos, incluindo lag.
• --bootstrap-server <host:port>: Especifica o broker Kafka ao qual se conectar.
• --group <group_id>: Especifica o ID do grupo de consumidores.
• --reset-offsets: Redefine os offsets para um grupo de consumidores.
• --topic <topic_name>: Especifica o tópico para redefinição de offset.
• --to-earliest: Redefine os offsets para a mensagem mais antiga disponível.
• --to-latest: Redefine os offsets para a mensagem mais recente disponível.
• --execute: Executa a operação de redefinição de offset.

Exemplos:

• Listar todos os grupos de consumidores:
  bash kafka-consumer-groups.sh --list --bootstrap-server kafka-broker-1:9092

• Descrever um grupo de consumidores my_group e mostrar seu lag:
  bash kafka-consumer-groups.sh --describe --group my_group --bootstrap-server kafka-broker-1:9092
  A saída mostrará o tópico, a partição, o offset atual, o log end offset e o lag.

• Redefinir offsets para my_group em my_topic para a mensagem mais antiga disponível:
  bash kafka-consumer-groups.sh --group my_group --topic my_topic --reset-offsets --to-earliest --execute --bootstrap-server kafka-broker-1:9092
  Use este comando com cautela, pois ele afeta de onde os consumidores começarão a ler.

5. kafka-log-dirs.sh

Esta ferramenta ajuda a inspecionar os diretórios de log nos brokers Kafka. Pode ser útil para entender o uso do disco e localizar dados de tópicos.

Argumentos Comuns:

• --bootstrap-server <host:port>: Especifica o broker Kafka ao qual se conectar.
• --topic <topic_name>: Filtra a saída para mostrar diretórios para um tópico específico.

Exemplos:

• Listar diretórios de log em um broker:
  bash kafka-log-dirs.sh --bootstrap-server kafka-broker-1:9092

• Mostrar diretórios de log para um tópico específico:
  bash kafka-log-dirs.sh --bootstrap-server kafka-broker-1:9092 --topic my_topic

6. kafka-preferred-replica-election.sh

Este script inicia eleições de réplicas preferenciais para tópicos. Uma réplica preferencial é o broker que é escolhido como líder para uma partição com base em seu fator de replicação. Se um broker falhar e uma réplica não preferencial se tornar o líder, esta ferramenta pode ser usada para mover a liderança de volta para a réplica preferencial.

Argumentos Comuns:

• --topic <topic_name>: Especifica o tópico para o qual eleger réplicas preferenciais.
• --broker-list <broker_id1,broker_id2,...>: Especifica uma lista de IDs de brokers separados por vírgulas.
• --bootstrap-server <host:port>: Especifica o broker Kafka ao qual se conectar.

Exemplos:

• Eleger réplicas preferenciais para my_topic:
  bash kafka-preferred-replica-election.sh --topic my_topic --bootstrap-server kafka-broker-1:9092

• Eleger réplicas preferenciais para vários tópicos:
  bash kafka-preferred-replica-election.sh --topic topic1,topic2 --bootstrap-server kafka-broker-1:9092

Considerações Importantes e Melhores Práticas

• --bootstrap-server é Fundamental: Sempre certifique-se de especificar o argumento --bootstrap-server correto para se conectar ao seu cluster Kafka. Geralmente, esta é uma lista de host:port separados por vírgulas para seus brokers.
• Ambiente: Esses comandos são tipicamente encontrados no diretório bin/ da sua instalação Kafka. Você precisará navegar até este diretório ou garantir que o diretório bin do Kafka esteja no PATH do seu sistema.
• Permissões: Garanta que o usuário que executa esses comandos tenha o acesso de rede necessário para alcançar os brokers Kafka.
• Configuração: Muitas ferramentas CLI podem aceitar configurações de cliente Kafka via argumentos --property ou --producer-property/--consumer-property. Isso é útil para substituir serializadores/desserializadores padrão ou definir outras configurações específicas do cliente.
• Segurança: Para clusters Kafka seguros (por exemplo, com autenticação SSL/TLS ou SASL), você precisará passar argumentos adicionais relacionados à segurança (como --command-config apontando para um arquivo de propriedades do cliente) para essas ferramentas.
• Exclusão de Tópicos: Lembre-se de que a exclusão de tópicos é uma operação sensível e deve ser explicitamente habilitada no arquivo server.properties do broker Kafka usando delete.topic.enable=true.

Conclusão

As ferramentas de linha de comando do Kafka fornecem uma interface robusta e acessível para gerenciar e interagir com seu cluster Kafka. Dominar ferramentas como kafka-topics.sh, kafka-console-producer.sh, kafka-console-consumer.sh e kafka-consumer-groups.sh é essencial para operações eficientes do Kafka, solução de problemas e desenvolvimento. Ao compreender seus argumentos e casos de uso, você pode simplificar significativamente seu fluxo de trabalho e obter insights mais profundos sobre sua infraestrutura de streaming de eventos.

Consultar regularmente esses comandos não apenas o ajudará a realizar tarefas administrativas diárias, mas também o capacitará a diagnosticar e resolver problemas de forma mais eficaz. À medida que você se familiariza com o Kafka, pode explorar outros scripts utilitários disponíveis no diretório bin/ para operações mais avançadas.