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

As ferramentas de linha de comando do Kafka são a maneira mais rápida de responder a perguntas operacionais básicas: este tópico existe, qual broker lidera esta partição, o que há dentro do tópico, por que este grupo de consumidores está atrasado, e este cliente pode autenticar com o cluster? Você não precisa delas para todas as tarefas, e a maioria das alterações de produção ainda deve passar por automação, mas durante uma implantação quebrada ou uma pergunta de dados tarde da noite, a CLI é frequentemente o caminho mais curto para os fatos.

Os exemplos abaixo assumem que os scripts estão no seu PATH. Em muitas instalações, eles ficam no diretório bin/ do Kafka, então o mesmo comando pode ser executado como bin/kafka-topics.sh. Para clusters seguros, a maioria dos comandos também precisa de --command-config client.properties, onde esse arquivo contém configurações SASL, SSL e outras do cliente.

Ferramentas CLI Principais do Kafka

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

1. kafka-topics.sh

Esta é, sem dúvida, a ferramenta de linha de comando mais usada. Ela permite criar, listar, descrever, excluir, alterar e gerenciar tópicos do Kafka. O gerenciamento de tópicos é fundamental para organizar fluxos 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 <nome_do_tópico>: Especifica o nome do tópico.
• --partitions <número_de_particoes>: Define o número de partições para um tópico (usado com --create).
• --replication-factor <fator>: Define o fator de replicação para um tópico (usado com --create).
• --bootstrap-server <host:porta>: Especifica o broker Kafka ao qual se conectar.

Exemplos:

• Criar um tópico chamado meu_topico com 3 partições e fator de replicação 2:

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

• Listar todos os tópicos no cluster:

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

• Descrever um tópico chamado meu_topico:

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

  Isso mostrará detalhes como partições, líder, réplicas e ISRs (Réplicas em Sincronia).

• Excluir um tópico chamado topico_antigo:

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

  Nota: A exclusão de tópicos precisa estar 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 <nome_do_tópico>: Especifica o tópico de destino.
• --bootstrap-server <host:porta>: Especifica o broker Kafka ao qual se conectar.
• --property <chave>=<valor>: Permite definir propriedades do produtor (por exemplo, key.serializer, value.serializer).
• --producer-property <chave>=<valor>: Semelhante a --property, mas especificamente para configurações do lado do produtor.

Exemplos:

• Enviar mensagens para meu_topico:

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

  Após executar isso, você pode digitar mensagens linha por linha. Pressione Ctrl+C para sair.

• Enviar mensagens com chaves (formato JSON):

  kafka-console-producer.sh --topic meu_topico --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 recebidas na saída padrão. É essencial para testar consumidores, inspecionar dados em tópicos e depurar aplicações produtoras/consumidoras.

Argumentos Comuns:

• --topic <nome_do_tópico>: Especifica o(s) tópico(s) dos quais consumir.
• --bootstrap-server <host:porta>: Especifica o broker Kafka ao qual se conectar.
• --group-id <id_do_grupo>: 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 do início do log do tópico.
• --offset <offset>: Começa a consumir a partir de um offset específico.
• --partition <id_da_particao>: Consome de uma partição específica.
• --property <chave>=<valor>: Permite definir propriedades do consumidor (por exemplo, value.deserializer).

Exemplos:

• Consumir todas as mensagens de meu_topico:

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

• Consumir mensagens do início de meu_topico para o grupo de consumidores meu_grupo:

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

• Consumir mensagens com offsets e chaves impressos:

  kafka-console-consumer.sh --topic meu_topico --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 atraso do consumidor, reassinar 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 atraso.
• --bootstrap-server <host:porta>: Especifica o broker Kafka ao qual se conectar.
• --group <id_do_grupo>: Especifica o ID do grupo de consumidores.
• --reset-offsets: Redefine offsets para um grupo de consumidores.
• --topic <nome_do_tópico>: Especifica o tópico para redefinição de offset.
• --to-earliest: Redefine offsets para a mensagem mais antiga disponível.
• --to-latest: Redefine 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:

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

• Descrever um grupo de consumidores meu_grupo e mostrar seu atraso:

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

  A saída mostrará o tópico, partição, offset atual, offset final do log e o atraso.

• Redefinir offsets para meu_grupo em meu_topico para a mensagem mais antiga disponível:

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

  Use este comando com cautela, pois ele afeta 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 do tópico.

Argumentos Comuns:

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

Exemplos:

• Listar diretórios de log em um broker:

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

• Mostrar diretórios de log para um tópico específico:

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

6. kafka-preferred-replica-election.sh

Este script inicia eleições de réplica preferida para tópicos. Uma réplica preferida é 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 preferida se tornar a líder, esta ferramenta pode ser usada para mover a liderança de volta para a réplica preferida.

Argumentos Comuns:

• --topic <nome_do_tópico>: Especifica o tópico para o qual eleger réplicas preferidas.
• --broker-list <id_do_broker1,id_do_broker2,...>: Especifica uma lista separada por vírgulas de IDs de brokers.
• --bootstrap-server <host:porta>: Especifica o broker Kafka ao qual se conectar.

Exemplos:

• Eleger réplicas preferidas para meu_topico:

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

• Eleger réplicas preferidas para vários tópicos:

  kafka-preferred-replica-election.sh --topic topico1,topico2 --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 é uma lista separada por vírgulas de host:porta para seus brokers.
• Ambiente: Esses comandos são normalmente encontrados no diretório bin/ da sua instalação do 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: Certifique-se de 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 através de 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 SSL/TLS ou autenticação 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.

Uma Maneira Segura de Usar a CLI em Produção

Use a CLI primeiro como uma ferramenta de inspeção e depois como uma ferramenta de mutação. --list, --describe e leituras curtas do console são de baixo risco. --delete, --alter, aumentos de partição e redefinições de offset alteram o comportamento do cluster e devem passar pelo mesmo caminho de revisão que as alterações de aplicação sempre que possível.

Uma sessão prática de produção geralmente começa com um arquivo de configuração do cliente:

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

Então cada comando o inclui:

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

Para consumidores de console, evite entrar acidentalmente em um grupo de aplicação real. Use um ID de grupo temporário ao inspecionar dados e use --max-messages para que o comando saia:

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

Esse pequeno hábito impede que um comando de depuração roube partições de um serviço ativo. Também deixa uma trilha de auditoria mais limpa porque o nome do grupo torna a intenção óbvia.

A CLI é melhor quando é entediante: um comando para inspecionar, um comando para confirmar e um registro claro de qualquer comando que mude o estado.

Receitas de Solução de Problemas do Dia a Dia

Se um produtor diz que está escrevendo com sucesso, mas a equipe do consumidor não vê nada, comece com o tópico:

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

Confirme o nome do tópico, contagem de partições, disponibilidade do líder e réplicas em sincronia. Um erro de digitação no nome de um tópico pode parecer exatamente um pipeline quebrado quando a criação automática de tópicos está habilitada em um cluster de desenvolvimento. Em produção, um tópico com partições offline ou ISR diminuindo aponta para um problema de broker ou replicação antes de apontar para o código da aplicação.

Em seguida, leia uma pequena amostra com um grupo temporário:

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

Se os registros aparecerem lá, o Kafka tem os dados e o problema é provavelmente o grupo de consumidores real, seus offsets, suas assinaturas ou sua lógica de processamento. Se nenhum registro aparecer, verifique o tópico do produtor, serializadores, autenticação e se o produtor está escrevendo em um cluster diferente.

Para perguntas sobre atraso, vá direto ao grupo:

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

Não pare no atraso total. Compare as partições. Uma única partição com grande atraso significa um problema diferente do que todas as partições com atraso moderado. Atraso em partição única geralmente significa distorção de chave ou uma atribuição de consumidor ruim. Atraso uniforme geralmente significa que toda a aplicação é mais lenta que a taxa de entrada.

Para perguntas "o que mudou?", inspecione a configuração do tópico:

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

É aqui que você detecta alterações de retenção, surpresas na política de limpeza, substituições de compactação e configurações de tamanho de mensagem que diferem das suposições do serviço.

A saída da CLI não substitui o monitoramento, mas é excelente para reduzir a incerteza. Em um incidente real, algumas saídas de comando coladas no ticket podem poupar a todos de debater se o tópico existe, se os registros estão presentes e se o grupo está realmente se movendo.

Comandos que Merecem Cuidado

Alguns comandos da CLI do Kafka parecem inofensivos porque são curtos. Eles não são inofensivos.

kafka-topics.sh --alter --partitions apenas aumenta a contagem de partições; não a diminui depois se você se arrepender da mudança. Mais partições podem ajudar no paralelismo do consumidor, mas também podem alterar a distribuição de chaves para novos registros e quebrar suposições em sistemas que esperavam que todos os eventos para um intervalo de chaves caíssem em um conjunto menor de partições.

kafka-consumer-groups.sh --reset-offsets --execute muda onde um grupo lerá em seguida. Use --dry-run primeiro, pare os consumidores afetados e registre os offsets antigos. Redefinir para o início pode reproduzir dados em sistemas que não são idempotentes. Redefinir para o mais recente pode pular dados que a empresa ainda espera processar.

kafka-topics.sh --delete depende da configuração e política do cluster, mas quando a exclusão é permitida, deve ser tratada como a exclusão de uma tabela de banco de dados. Verifique o cluster, verifique o tópico e verifique se outro ambiente usa a mesma convenção de nomenclatura. Um tópico de produção chamado orders-test ainda é produção se serviços reais dependem dele.

Para operações repetíveis, coloque o comando em um runbook ou script com variáveis explícitas para cluster, tópico, grupo e configuração de comando. A CLI é ótima para investigação, mas a mutação de produção deve ser entediante, revisada e fácil de auditar.