Comprendiendo las Herramientas de Línea de Comandos de Kafka: Guía de Referencia CLI

Las herramientas de línea de comandos de Kafka son la forma más rápida de responder preguntas operativas básicas: ¿existe este tema?, ¿qué broker lidera esta partición?, ¿qué hay dentro del tema?, ¿por qué este grupo de consumidores está retrasado?, y ¿puede este cliente autenticarse con el clúster? No las necesita para cada tarea, y la mayoría de los cambios en producción deberían pasar por automatización, pero durante un despliegue roto o una pregunta de datos nocturna, la CLI suele ser el camino más corto hacia los hechos.

Los ejemplos a continuación asumen que los scripts están en su PATH. En muchas instalaciones, se encuentran bajo el directorio bin/ de Kafka, por lo que el mismo comando puede ejecutarse como bin/kafka-topics.sh. Para clústeres seguros, la mayoría de los comandos también necesitan --command-config client.properties, donde ese archivo contiene configuraciones SASL, SSL y otras del cliente.

Herramientas CLI Principales de Kafka

Las distribuciones de Kafka suelen incluir un directorio bin/ que contiene varios scripts y ejecutables. Nos centraremos en los más utilizados para gestionar Kafka de manera efectiva.

1. kafka-topics.sh

Esta es, sin duda, la herramienta de línea de comandos más utilizada. Permite crear, listar, describir, eliminar, modificar y gestionar temas de Kafka. La gestión de temas es fundamental para organizar los flujos de datos dentro de Kafka.

Subcomandos y Argumentos Comunes:

• --create: Crea un nuevo tema.
• --list: Lista todos los temas en el clúster.
• --describe: Proporciona información detallada sobre temas específicos.
• --delete: Elimina uno o más temas.
• --alter: Modifica la configuración de un tema existente.
• --topic <nombre_tema>: Especifica el nombre del tema.
• --partitions <num_partitions>: Establece el número de particiones para un tema (usado con --create).
• --replication-factor <factor>: Establece el factor de replicación para un tema (usado con --create).
• --bootstrap-server <host:puerto>: Especifica el broker de Kafka al que conectarse.

Ejemplos:

• Crear un tema llamado mi_tema con 3 particiones y un factor de replicación de 2:

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

• Listar todos los temas en el clúster:

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

• Describir un tema llamado mi_tema:

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

  Esto mostrará detalles como particiones, líder, réplicas e ISR (Réplicas en Sincronía).

• Eliminar un tema llamado tema_viejo:

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

  Nota: La eliminación de temas debe estar habilitada en las configuraciones del broker de Kafka (delete.topic.enable=true).

2. kafka-console-producer.sh

Esta herramienta permite enviar mensajes a un tema de Kafka desde la entrada estándar. Es invaluable para probar productores, inyectar datos de muestra o publicar mensajes manualmente.

Argumentos Comunes:

• --topic <nombre_tema>: Especifica el tema de destino.
• --bootstrap-server <host:puerto>: Especifica el broker de Kafka al que conectarse.
• --property <clave>=<valor>: Permite establecer propiedades del productor (por ejemplo, key.serializer, value.serializer).
• --producer-property <clave>=<valor>: Similar a --property, pero específicamente para configuraciones del lado del productor.

Ejemplos:

• Enviar mensajes a mi_tema:

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

  Después de ejecutar esto, puede escribir mensajes línea por línea. Presione Ctrl+C para salir.

• Enviar mensajes con claves (formato JSON):

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

  Ahora puede escribir pares clave:valor, y Kafka los enviará con la clave especificada.

3. kafka-console-consumer.sh

Esta herramienta se suscribe a uno o más temas de Kafka e imprime los mensajes que recibe en la salida estándar. Es esencial para probar consumidores, inspeccionar datos en temas y depurar aplicaciones de productor/consumidor.

Argumentos Comunes:

• --topic <nombre_tema>: Especifica el(los) tema(s) de los que consumir.
• --bootstrap-server <host:puerto>: Especifica el broker de Kafka al que conectarse.
• --group-id <id_grupo>: Especifica el ID del grupo de consumidores. Esto es importante para gestionar offsets y permitir que múltiples consumidores compartan la carga de consumo.
• --from-beginning: Lee mensajes desde el principio del registro del tema.
• --offset <offset>: Comienza a consumir desde un offset específico.
• --partition <id_particion>: Consume desde una partición específica.
• --property <clave>=<valor>: Permite establecer propiedades del consumidor (por ejemplo, value.deserializer).

Ejemplos:

• Consumir todos los mensajes de mi_tema:

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

• Consumir mensajes desde el principio de mi_tema para el grupo de consumidores mi_grupo:

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

• Consumir mensajes con offsets y claves impresos:

  kafka-console-consumer.sh --topic mi_tema --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 herramienta se utiliza para gestionar e inspeccionar grupos de consumidores. Es vital para entender el retraso del consumidor, reasignar particiones y solucionar problemas de consumo.

Subcomandos y Argumentos Comunes:

• --list: Lista todos los grupos de consumidores en el clúster.
• --describe: Proporciona detalles sobre grupos de consumidores específicos, incluido el retraso.
• --bootstrap-server <host:puerto>: Especifica el broker de Kafka al que conectarse.
• --group <id_grupo>: Especifica el ID del grupo de consumidores.
• --reset-offsets: Restablece los offsets para un grupo de consumidores.
• --topic <nombre_tema>: Especifica el tema para el restablecimiento de offsets.
• --to-earliest: Restablece los offsets al mensaje disponible más antiguo.
• --to-latest: Restablece los offsets al mensaje disponible más reciente.
• --execute: Ejecuta la operación de restablecimiento de offsets.

Ejemplos:

• Listar todos los grupos de consumidores:

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

• Describir un grupo de consumidores mi_grupo y mostrar su retraso:

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

  La salida mostrará el tema, la partición, el offset actual, el offset final del registro y el retraso.

• Restablecer offsets para mi_grupo en mi_tema al mensaje disponible más antiguo:

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

  Use este comando con precaución, ya que afecta desde dónde comenzarán a leer los consumidores.

5. kafka-log-dirs.sh

Esta herramienta ayuda a inspeccionar los directorios de registro en los brokers de Kafka. Puede ser útil para entender el uso del disco y localizar datos de temas.

Argumentos Comunes:

• --bootstrap-server <host:puerto>: Especifica el broker de Kafka al que conectarse.
• --topic <nombre_tema>: Filtra la salida para mostrar directorios de un tema específico.

Ejemplos:

• Listar directorios de registro en un broker:

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

• Mostrar directorios de registro para un tema específico:

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

6. kafka-preferred-replica-election.sh

Este script inicia elecciones de réplicas preferidas para temas. Una réplica preferida es el broker que se elige como líder para una partición según su factor de replicación. Si un broker falla y una réplica no preferida se convierte en líder, esta herramienta se puede usar para devolver el liderazgo a la réplica preferida.

Argumentos Comunes:

• --topic <nombre_tema>: Especifica el tema para el cual elegir réplicas preferidas.
• --broker-list <id_broker1,id_broker2,...>: Especifica una lista separada por comas de IDs de brokers.
• --bootstrap-server <host:puerto>: Especifica el broker de Kafka al que conectarse.

Ejemplos:

• Elegir réplicas preferidas para mi_tema:

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

• Elegir réplicas preferidas para múltiples temas:

  kafka-preferred-replica-election.sh --topic tema1,tema2 --bootstrap-server kafka-broker-1:9092
  

Consideraciones Importantes y Mejores Prácticas

• --bootstrap-server es Clave: Siempre asegúrese de especificar el argumento --bootstrap-server correcto para conectarse a su clúster de Kafka. Esto suele ser una lista separada por comas de host:puerto de sus brokers.
• Entorno: Estos comandos se encuentran típicamente en el directorio bin/ de su instalación de Kafka. Necesitará navegar a este directorio o asegurarse de que el directorio bin de Kafka esté en el PATH de su sistema.
• Permisos: Asegúrese de que el usuario que ejecuta estos comandos tenga el acceso de red necesario para llegar a los brokers de Kafka.
• Configuración: Muchas herramientas CLI pueden aceptar configuraciones de cliente de Kafka a través de argumentos --property o --producer-property/--consumer-property. Esto es útil para anular serializadores/deserializadores predeterminados o establecer otras configuraciones específicas del cliente.
• Seguridad: Para clústeres de Kafka seguros (por ejemplo, con SSL/TLS o autenticación SASL), necesitará pasar argumentos adicionales relacionados con la seguridad (como --command-config apuntando a un archivo de propiedades del cliente) a estas herramientas.
• Eliminación de Temas: Recuerde que la eliminación de temas es una operación sensible y debe estar explícitamente habilitada en el archivo server.properties del broker de Kafka usando delete.topic.enable=true.

Una Forma Segura de Usar la CLI en Producción

Use la CLI primero como herramienta de inspección y luego como herramienta de mutación. --list, --describe y lecturas cortas de consola son de bajo riesgo. --delete, --alter, aumentos de particiones y restablecimientos de offsets cambian el comportamiento del clúster y deberían pasar por el mismo proceso de revisión que los cambios de aplicación siempre que sea posible.

Una sesión de producción práctica generalmente comienza con un archivo de configuración del cliente:

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

Luego, cada comando lo incluye:

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

Para consumidores de consola, evite unirse accidentalmente a un grupo de aplicación real. Use un ID de grupo temporal cuando esté inspeccionando datos, y use --max-messages para que el comando termine:

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

Ese pequeño hábito evita que un comando de depuración robe particiones de un servicio en vivo. También deja un rastro de auditoría más limpio porque el nombre del grupo hace obvia la intención.

La CLI es mejor cuando es aburrida: un comando para inspeccionar, un comando para confirmar y un registro claro de cualquier comando que cambie el estado.

Recetas Cotidianas para Solución de Problemas

Si un productor dice que está escribiendo con éxito pero el equipo consumidor no ve nada, comience con el tema:

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

Confirme el nombre del tema, el número de particiones, la disponibilidad del líder y las réplicas en sincronía. Un error tipográfico en un nombre de tema puede parecer exactamente una tubería rota cuando la creación automática de temas está habilitada en un clúster de desarrollo. En producción, un tema con particiones fuera de línea o ISR reducido apunta a un problema de broker o replicación antes que a un problema de código de aplicación.

A continuación, lea una pequeña muestra con un grupo temporal:

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

Si aparecen registros allí, Kafka tiene los datos y el problema probablemente sea el grupo de consumidores real, sus offsets, sus suscripciones o su lógica de procesamiento. Si no aparecen registros, verifique el tema del productor, los serializadores, la autenticación y si el productor está escribiendo en un clúster diferente.

Para preguntas sobre retrasos, vaya directamente al grupo:

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

No se detenga en el retraso total. Compare las particiones. Una sola partición con gran retraso significa un problema diferente que todas las particiones con retraso moderado. El retraso de una sola partición a menudo significa sesgo de clave o una mala asignación de consumidor. El retraso uniforme generalmente significa que toda la aplicación es más lenta que la tasa de entrada.

Para preguntas de "¿qué cambió?", inspeccione la configuración del tema:

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

Aquí es donde detecta cambios de retención, sorpresas en la política de limpieza, anulaciones de compresión y configuraciones de tamaño de mensaje que difieren de las suposiciones del servicio.

La salida de la CLI no es un reemplazo para la monitorización, pero es excelente para reducir la incertidumbre. En un incidente real, algunas salidas de comandos pegadas en el ticket pueden ahorrarle a todos el debate sobre si el tema existe, si los registros están presentes y si el grupo realmente se está moviendo.

Comandos que Vale la Pena Tratar con Cuidado

Algunos comandos de la CLI de Kafka parecen inofensivos porque son cortos. No son inofensivos.

kafka-topics.sh --alter --partitions solo aumenta el número de particiones; no lo reduce más tarde si se arrepiente del cambio. Más particiones pueden ayudar al paralelismo del consumidor, pero también pueden cambiar la distribución de claves para nuevos registros y romper suposiciones en sistemas que esperaban que todos los eventos para un rango de claves cayeran en un conjunto más pequeño de particiones.

kafka-consumer-groups.sh --reset-offsets --execute cambia dónde leerá un grupo a continuación. Use --dry-run primero, detenga los consumidores afectados y registre los offsets antiguos. Restablecer al más antiguo puede reproducir datos en sistemas que no son idempotentes. Restablecer al más reciente puede saltar datos que el negocio aún espera procesar.

kafka-topics.sh --delete depende de la configuración y política del clúster, pero cuando se permite la eliminación, debe tratarse como eliminar una tabla de base de datos. Verifique el clúster, verifique el tema y verifique si otro entorno usa la misma convención de nombres. Un tema de producción llamado orders-test sigue siendo producción si servicios reales dependen de él.

Para operaciones repetibles, coloque el comando en un runbook o script con variables explícitas para clúster, tema, grupo y configuración de comando. La CLI es excelente para la investigación, pero la mutación en producción debe ser aburrida, revisada y fácil de auditar.