TOP 10 Comandos de Apache Kafka CLI que Todo Desarrollador Debe Saber

Por Qué la CLI de Apache Kafka es Indispensable para Data Engineers y Arquitectos

En el ecosistema de datos moderno, las interfaces gráficas (UIs) como Kafka UI, AKHQ o Confluent Control Center son herramientas visuales fantásticas para monitorizar métricas globales. Sin embargo, cuando ocurre una caída en producción a las tres de la madrugada, cuando un microservicio envenenado colapsa tu clúster por un fallo de deserialización, o cuando necesitas ejecutar validaciones en pipelines de CI/CD automatizados, la interfaz gráfica se queda corta o es inaccesible.

Como arquitectos de datos e ingenieros de plataforma, la Command Line Interface (CLI) oficial de Kafka es la navaja suiza que nunca falla. Opera directamente sobre la red con mínima sobrecarga, permite interactuar contra entornos con autenticación estricta (mTLS, SASL_SSL) y puede integrarse en scripts Bash para resolver problemas en segundos.

Si estás aprendiendo a desplegar Apache Kafka en Docker con KRaft o profundizando en nuestro curso completo de Apache Kafka para Data Engineers, dominar estos 10 comandos es el factor diferencial para operar clústeres distribuidos con solvencia profesional.

TOP 10 Comandos Esenciales de Apache Kafka CLI Explicados con Ejemplos

Todos los scripts que revisaremos se encuentran en el directorio bin/ de la distribución oficial de Apache Kafka. En clústeres modernos basados en KRaft, el parámetro de conexión universal es --bootstrap-server <host:puerto>.

1. Crear Tópicos con Particionamiento Óptimo: kafka-topics.sh --create

La creación de tópicos define la unidad fundamental de escalabilidad horizontal en Kafka. Cada partición puede ser consumida por un único hilo dentro de un mismo grupo de consumidores, por lo que dimensionar el número de particiones es una decisión arquitectónica clave.

# Creación de un topic de transacciones con 3 particiones y factor de replicación 1 (local)
kafka-topics.sh --create \
  --bootstrap-server localhost:9092 \
  --topic transacciones-bancarias \
  --partitions 3 \
  --replication-factor 1 \
  --config retention.ms=604800000

El flag --config te permite inyectar sobrecargas de configuración específicas al momento de crearlo, como fijar el tiempo de retención de mensajes a 7 días (604.800.000 ms) sin alterar los valores por defecto del broker.

2. Inspección Topológica y Salud de Réplicas: kafka-topics.sh --describe

Antes de culpar a tu código consumidor o productor, este comando te permite ver las entrañas del tópico: qué broker es el líder de cada partición, en qué brokers residen las réplicas y cuáles de ellas están en el grupo ISR (In-Sync Replicas).

# Inspeccionar el estado interno y líderes de partición
kafka-topics.sh --describe \
  --bootstrap-server localhost:9092 \
  --topic transacciones-bancarias

Salida típica en consola:

Topic: transacciones-bancarias  TopicId: QK3N9e8-T3m4... PartitionCount: 3 ReplicationFactor: 1
  Topic: transacciones-bancarias Partition: 0 Leader: 1 Replicas: 1 Isr: 1
  Topic: transacciones-bancarias Partition: 1 Leader: 1 Replicas: 1 Isr: 1
  Topic: transacciones-bancarias Partition: 2 Leader: 1 Replicas: 1 Isr: 1

Si notas que el campo Isr tiene menos IDs que el campo Replicas, significa que un broker secundario se ha desincronizado por latencia de red, saturación de disco o caída de hardware.

3. Escalado Dinámico de Throughput: kafka-topics.sh --alter

Si tu aplicación experimenta un pico de tráfico inesperado y necesitas que más instancias de tus consumidores en paralelo absorban la carga, puedes aumentar el número de particiones en caliente sin interrumpir el clúster:

# Incrementar de 3 a 6 particiones en caliente
kafka-topics.sh --alter \
  --bootstrap-server localhost:9092 \
  --topic transacciones-bancarias \
  --partitions 6

4. Publicación Forense y Claves Particionadas: kafka-console-producer.sh

El productor por consola estándar envía cadenas simples de texto. Sin embargo, en eventos empresariales de streaming, casi siempre necesitamos publicar pares clave-valor (Key:Value) para que Kafka garantice que todos los eventos de un mismo cliente o usuario viajen a la misma partición:

# Iniciar productor con soporte explícito de claves separadas por dos puntos
kafka-console-producer.sh \
  --bootstrap-server localhost:9092 \
  --topic transacciones-bancarias \
  --property "parse.key=true" \
  --property "key.separator=:"

# Al pulsar Enter, escribe tus eventos con el formato clave:valor
> user-101:{"monto": 150.00, "moneda": "EUR", "operacion": "transferencia"}
> user-204:{"monto": 25.50, "moneda": "USD", "operacion": "pago_tarjeta"}
> user-101:{"monto": 420.00, "moneda": "EUR", "operacion": "abono_nomina"}

Al especificar user-101 como clave, Kafka calcula su hash determinista, garantizando que ambas transferencias se ubiquen en la misma partición y sean consumidas en estricto orden cronológico.

5. Consumo en Tiempo Real con Metadatos: kafka-console-consumer.sh

Consumir solo el cuerpo del mensaje muchas veces no te dice de qué partición proviene ni en qué milisegundo exacto se generó. Añadiendo propiedades de impresión de metadatos, conviertes la CLI en un analizador forense en tiempo real:

# Consumir desde el inicio imprimiendo timestamp, partición, offset y key
kafka-console-consumer.sh \
  --bootstrap-server localhost:9092 \
  --topic transacciones-bancarias \
  --from-beginning \
  --property "print.timestamp=true" \
  --property "print.key=true" \
  --property "print.partition=true" \
  --property "print.offset=true" \
  --property "key.separator= | "

Esta salida te revelará de inmediato si tus mensajes se están repartiendo equitativamente entre las particiones o si una partición específica está absorbiendo todo el tráfico (el clásico antipatrón de *hotspotting* por claves nulas o sesgadas).

6. Monitorización de Consumer Lag: kafka-consumer-groups.sh --describe

El Consumer Lag es la métrica reina en Apache Kafka: indica la diferencia entre el último mensaje persistido en el log (LOG-END-OFFSET) y el último mensaje que tu consumidor ha procesado y confirmado (CURRENT-OFFSET). Si el lag crece sin control, tu pipeline de datos tiene un cuello de botella crítico.

# Inspeccionar el lag de un grupo de consumidores específico
kafka-consumer-groups.sh --describe \
  --bootstrap-server localhost:9092 \
  --group fraud-detection-service

Salida de auditoría de offsets:

GROUP                   TOPIC                  PARTITION  CURRENT-OFFSET  LOG-END-OFFSET  LAG      CONSUMER-ID      HOST            CLIENT-ID
fraud-detection-service transacciones-bancarias 0          14520           14525           5        fraud-app-1...   /172.20.0.4     fraud-app-1
fraud-detection-service transacciones-bancarias 1          9840            18500           8660     fraud-app-2...   /172.20.0.5     fraud-app-2
fraud-detection-service transacciones-bancarias 2          12030           12030           0        fraud-app-3...   /172.20.0.6     fraud-app-3

En este ejemplo, la partición 1 presenta un Lag de 8.660 mensajes acumulados. Gracias a la CLI detectas al instante qué pod o worker se ha colgado o consume más lento que el resto.

7. El Salvavidas de Producción: kafka-consumer-groups.sh --reset-offsets

¿Un bug en el microservicio parseó mal los últimos 10.000 eventos? ¿Un mensaje corrupto (*poison pill*) provocó una excepción no controlada que detuvo el pipeline? Con este comando puedes manipular el puntero del grupo de consumidores hacia atrás en el tiempo o saltarte eventos conflictivos.

# PASO 1: Simulación de reseteo al inicio (--dry-run obligatorio)
kafka-consumer-groups.sh \
  --bootstrap-server localhost:9092 \
  --group fraud-detection-service \
  --topic transacciones-bancarias \
  --reset-offsets \
  --to-earliest \
  --dry-run

Una vez revisado que el cálculo de offsets es el deseado, reemplazas --dry-run por --execute:

# PASO 2: Ejecución del reseteo de offsets
kafka-consumer-groups.sh \
  --bootstrap-server localhost:9092 \
  --group fraud-detection-service \
  --topic transacciones-bancarias \
  --reset-offsets \
  --to-earliest \
  --execute

También dispones de variantes indispensables como --to-datetime 2026-10-25T12:00:00.000 o --shift-by -500 para retroceder un número exacto de mensajes.

8. Modificación Dinámica de Configuración: kafka-configs.sh

Imagínate que un proceso de pruebas llenó el disco del clúster al 95%. Reiniciar los brokers no es una opción viable en horario laboral. Mediante kafka-configs.sh puedes forzar la purga inmediata de segmentos alterando la retención del tópico en caliente:

# Reducir temporalmente la retención a 1 hora (3.600.000 ms) para liberar almacenamiento
kafka-configs.sh \
  --bootstrap-server localhost:9092 \
  --entity-type topics \
  --entity-name transacciones-bancarias \
  --alter \
  --add-config retention.ms=3600000

# Consultar las configuraciones sobreescritas del topic
kafka-configs.sh \
  --bootstrap-server localhost:9092 \
  --entity-type topics \
  --entity-name transacciones-bancarias \
  --describe

9. Inspección Forense a Bajo Nivel del Log: kafka-dump-log.sh

Cuando una librería de cliente lanza errores crípticos del tipo CorruptRecordException o cuando sospechas que los magic bytes de tus mensajes están alterados, necesitas mirar directamente el archivo binario .log almacenado en el disco del broker:

# Decodificar el contenido binario del segmento de log e inspeccionar offsets y payloads
kafka-dump-log.sh \
  --files /tmp/kraft-combined-logs/transacciones-bancarias-0/00000000000000000000.log \
  --print-data-log \
  --deep-iteration

Este comando lee el encabezado de compresión (snappy, zstd, gzip), el timestamp del broker versus el del productor, y muestra si el payload fue escrito con el Schema Registry ID correcto.

10. Compatibilidad de Clúster y API Versions: kafka-broker-api-versions.sh

En clústeres empresariales con múltiples clientes legados (Go, Python, Java, C#), es frecuente encontrar errores de negociación de protocolos. Este comando interroga a todos los brokers y devuelve exactamente qué versiones de cada API (Produce, Fetch, ListOffsets, Metadata) soporta el clúster:

# Validar la matriz de versiones de API soportadas por el broker
kafka-broker-api-versions.sh \
  --bootstrap-server localhost:9092

Si un cliente antiguo no puede conectarse tras una actualización de Kafka, la salida de este comando te dirá al instante si la versión mínima de la API requerida por el broker ha dejado de ser compatible.

Vídeo Tutorial: Demostración Práctica de los Comandos de Kafka en Terminal

Acompaña la lectura con esta sesión práctica grabada directamente sobre un clúster en terminal Linux, donde exploramos la ejecución en vivo de cada uno de estos comandos y las técnicas de diagnóstico en tiempo real:

Caso Real de Producción: Automatización con Bash para Inyectar 1.000 Mensajes en 47 Tópicos

En uno de nuestros proyectos de modernización de arquitectura analítica para un cliente financiero, debíamos validar el comportamiento de un nuevo motor de ingestión de eventos. El requerimiento técnico era estricto: necesitábamos una batería de pruebas de 1.000 mensajes sintéticos inyectados de forma controlada en 47 tópicos distintos para verificar la idempotencia de los consumidores y comprobar que no se perdiese ni un solo registro.

La primera propuesta del equipo de desarrollo fue escribir un microservicio en Java o Python que utilizara el cliente oficial de Kafka. Sin embargo, configurar el proyecto, definir los modelos serializados, compilar la imagen Docker y orquestar el despliegue habría llevado casi dos jornadas de trabajo.

Kafka CLI nos salvó el día. En menos de 20 minutos programamos un script modular en Bash que utilizó kafka-topics.sh para aprovisionar los 47 tópicos y un bucle canalizado hacia kafka-console-producer.sh. El script completo, listo para reutilizar en cualquier entorno de testing, es el siguiente:

#!/usr/bin/env bash
# ==============================================================================
# Automatización de Inyección de Eventos Sintéticos en Apache Kafka
# Autor: Eduardo Martínez Agrelo (Google Cloud con Eduardo)
# ==============================================================================

set -euo pipefail

BOOTSTRAP_SERVER="localhost:9092"
TOTAL_TOPICS=47
MESSAGES_PER_TOPIC=1000

echo "🚀 [1/3] Iniciando creación de ${TOTAL_TOPICS} tópicos de prueba..."

for i in $(seq -w 1 ${TOTAL_TOPICS}); do
  TOPIC_NAME="test-pipeline-modulo-${i}"
  
  # Creación idempotente (evita fallos si el topic ya existe)
  kafka-topics.sh --create \
    --bootstrap-server "${BOOTSTRAP_SERVER}" \
    --topic "${TOPIC_NAME}" \
    --partitions 3 \
    --replication-factor 1 \
    --if-not-exists
done

echo "✅ Tópicos creados exitosamente."
echo "🚀 [2/3] Generando e inyectando ${MESSAGES_PER_TOPIC} eventos por tópico..."

START_TIME=$(date +%s)

for i in $(seq -w 1 ${TOTAL_TOPICS}); do
  TOPIC_NAME="test-pipeline-modulo-${i}"
  echo "--> Inyectando tráfico en [${TOPIC_NAME}]..."

  # Generar secuencia de 1.000 JSONs y canalizarlos directamente al console producer
  for m in $(seq 1 ${MESSAGES_PER_TOPIC}); do
    TIMESTAMP=$(date +%s%3N)
    echo "test-key-${m}:{\"event_id\":\"${m}\",\"topic\":\"${TOPIC_NAME}\",\"ts\":${TIMESTAMP},\"status\":\"OK\"}"
  done | kafka-console-producer.sh \
    --bootstrap-server "${BOOTSTRAP_SERVER}" \
    --topic "${TOPIC_NAME}" \
    --property "parse.key=true" \
    --property "key.separator=:" \
    --compression-codec "lz4" > /dev/null 2>&1
done

END_TIME=$(date +%s)
ELAPSED=$((END_TIME - START_TIME))

echo "🎉 [3/3] ¡Prueba completada con éxito! $((TOTAL_TOPICS * MESSAGES_PER_TOPIC)) eventos publicados en ${ELAPSED} segundos."

Gracias a la canalización en memoria vía tubería (pipe |) hacia kafka-console-producer.sh con compresión LZ4, logramos inyectar 47.000 eventos en menos de 2 minutos. Esto permitió validar la tasa de ingesta, verificar que los consumidores no sufrieran rebalanceos y comprobar el correcto descarte de duplicados sin escribir una sola línea de código en un framework pesado.

Matriz Comparativa: Clasificación de Comandos por Escenario Operativo

Para tener una referencia rápida de consulta en tu día a día como ingeniero de datos o administrador de sistemas, esta matriz resume el propósito, el comando principal y su criticidad en producción:

Antipatrones Comunes y Alerta de Producción en el Manejo de la CLI

El poder de la línea de comandos conlleva una gran responsabilidad. En nuestras auditorías arquitectónicas encontramos con frecuencia los siguientes errores costosos:

• Consumir Topics Masivos con --from-beginning sin Limitador: Ejecutar un kafka-console-consumer.sh --from-beginning en un topic de producción con 50 millones de registros inundará la memoria de tu terminal, saturará la tarjeta de red del broker con ancho de banda innecesario y puede provocar desconexiones temporales en otros clientes críticos. Si necesitas probar, utiliza siempre --max-messages 50.
• Olvidar el flag --dry-run al Resetear Offsets: Ejecutar directamente --execute para resetear un consumer group a --to-earliest en un topic con retención de 30 días forzará al microservicio a reprocesar semanas de información, provocando facturación desmedida de infraestructura, registros duplicados en bases de datos relacionales y alertas de saturación.
• Consumidores Activos Durante el Reseteo: Si intentas alterar los offsets de un grupo mientras sus instancias continúan levantadas, el clúster rechazará la operación o se generará una condición de carrera donde el commit automático del consumidor sobreescribirá inmediatamente tu cambio manual.

Preguntas Frecuentes sobre los Comandos de Apache Kafka (FAQ)