Kafka

Esta guía te muestra cómo trabajar con Apache Kafka localmente usando Docker Compose y Python. Este lab demuestra cómo producir y consumir eventos en un topic con el cliente confluent-kafka, inspeccionarlos en Kafka UI y operar el broker con las herramientas CLI de Kafka.

Prerrequisitos

Docker instalado y en ejecución.
Dev Containers extension instalada (opcional).

Cómo ejecutar

Configurar el entorno:
- Dev Container (recomendado)
- Manual
Abre VS Code en la carpeta del proyecto y ejecuta este comando en la Paleta de Comandos:
Ventana de terminal
> Dev Containers: Reopen in Container
1. Inicia la infraestructura: Lanza los contenedores del broker de Kafka y de Kafka UI:
  Ventana de terminal
  docker compose up -d
2. Ejecuta el script de configuración para instalar herramientas y dependencias:
  Ventana de terminal
  scripts/setup.sh
Ejecutar el ejemplo:
- Ejecuta el ciclo completo. Publica los eventos, los vuelve a consumir y termina:
  Ventana de terminal
  python main.py
- Divídelo en dos terminales. -c mantiene el consumidor a la escucha hasta CTRL+C, y -p solo publica:
  
  Terminal 1:
  Ventana de terminal
  python main.py -c
  Terminal 2:
  Ventana de terminal
  python main.py -p
1. Produce un evento escribiéndolo en el console producer:
  Ventana de terminal
  scripts/kafka.sh kafka-console-producer.sh --topic user-events
2. Consume los eventos desde el principio del topic:
  Ventana de terminal
  scripts/kafka.sh kafka-console-consumer.sh --topic user-events --from-beginning
- Instala: Tools for Apache Kafka.
- Conecta: El cluster local ya está configurado en .vscode/settings.json a partir de KAFKA_BOOTSTRAP_SERVERS.
- Abre: Abre playgrounds/user_events.kafka.
- Ejecuta: Haz clic en Produce record o Start consumer sobre cada bloque.

Cómo depurar

main.py:
- Abre: Abre main.py.
- Breakpoints: Añade breakpoints en publish_events o en print_event.
- Ejecuta: Pulsa F5 y selecciona Python: Main, que ejecuta el ciclo completo.
Tests:
- Abre: Abre un archivo de test (p. ej., tests/components/test_event_consumer.py).
- Breakpoints: Añade breakpoints en el código de test.
- Ejecuta: Usa la pestaña Testing de VS Code y haz clic en el icono Debug Test junto al test que quieras depurar.

Cómo testear

Todos los tests: Ejecuta el script automatizado:
Ventana de terminal
```
scripts/run_tests.sh
```
Individualmente: Usa la pestaña Testing de VS Code para ejecutar o depurar casos de test específicos.

Validar resultados

Abre: Navega a la UI (puerto definido en KAFKA_UI_PORT de tu .env):
Ventana de terminal
```
http://localhost:8080
```
Verifica: Navega a local → Topics → user-events → Messages.
Monitoriza: Consulta Consumers para ver el lag del grupo user-events-consumer.

Lista los topics:
Ventana de terminal
```
scripts/kafka.sh kafka-topics.sh --list
```

Lee todos los eventos almacenados en el topic:

scripts/kafka.sh kafka-console-consumer.sh --topic user-events --from-beginning

Verifica los offsets y el lag del consumer group:

scripts/kafka.sh kafka-consumer-groups.sh --describe --group user-events-consumer

Instala: Tools for Apache Kafka.
Navega: Abre el panel Kafka en la Activity Bar y despliega el cluster local.
Verifica: Despliega Topics → user-events para inspeccionar particiones y offsets.
Interactivo: Usa playgrounds/user_events.kafka para producir y consumir registros desde el editor.

Limpieza

docker compose down -v

Solución de problemas

Problema	Solución
El productor falla con `Connection refused`.	El broker tarda unos segundos en arrancar. Comprueba que está listo con `docker compose logs kafka`.
Publicas eventos pero ningún consumidor los imprime.	Lista los miembros del grupo con `scripts/kafka.sh kafka-consumer-groups.sh --describe --group user-events-consumer --members`. Sin miembros: no hay nada consumiendo, arranca un consumidor con `python main.py -c`. Más de un miembro: el topic tiene una sola partición, así que solo un miembro la tiene asignada y es ese el que está recibiendo los eventos — para los consumidores sobrantes.
Kafka UI no muestra ningún cluster.	La UI accede al broker por el listener interno `kafka:9093`. Asegúrate de que ambos contenedores están levantados con `docker compose ps`.