Guía Completa de Kafka Stream Processing
Construye pipelines de eventos en tiempo real con Kafka: producers, consumers, Kafka Streams, Connect, schema registry y patrones.
Introducción
Mover datos por Kafka es fácil; procesarlos correctamente a escala es donde los equipos se queman. Las APIs de producer/consumer te dan el caño — pero en el momento en que necesitas agregar, joinear, windower o enriquecer eventos, necesitas stream processing, y ahí es donde la mayoría de los pipelines se descarrilan: estado que no planificaste, supuestos de orden que se rompen, schemas que cambian en silencio.
Esta guía cubre el stack completo de procesamiento: producers y consumers en tres lenguajes, el DSL de Kafka Streams con state stores y windowing, Kafka Connect para mover datos hacia adentro y afuera, Schema Registry para los contratos, y los patrones que aparecen en todo pipeline real. El código es ejecutable — elige el lenguaje que tu servicio ya usa.
Para el lado del broker — particiones, replicación, monitoreo — la guía de operación de Kafka en producción complementa a esta. Para la versión agnóstica de plataforma de estos patrones, ver Stream Processing: Pipelines de Datos Event-Driven.
Elegir tu Modelo de Procesamiento
Antes de escribir código, elige la herramienta correcta. Kafka te da tres formas incorporadas de procesar eventos, y elegir mal significa reconstruir después o correr infraestructura que no necesitas.
| Herramienta | Modelo | Ideal para | Costo |
|---|---|---|---|
| Consumers simples | Pull-based, manejas todo | Transforms simples, escritura a DB | Mínimo — sin infra extra |
| Kafka Streams | Librería dentro de tu app, estado local | Agregaciones, joins, windowing, lógica stateful | Medio — embebido, sin cluster |
| Kafka Connect | Workers + configs de conectores | Mover datos entre Kafka y sistemas externos | Medio — necesita cluster Connect |
| Flink / Spark | Clusters de procesamiento dedicados | Lógica event-time compleja, estado enorme, multi-source | Máximo — cluster separado |
La regla que más dolor ahorra: empieza con un consumer simple si solo transformas y escribes; pasa a Kafka Streams en el momento en que necesites estado (counts, joins, windows); usa Flink solo cuando la semántica de event-time o el tamaño de estado de Kafka Streams genuinamente no alcanzan. La mayoría de los pipelines nunca pasa de la opción dos.
Conceptos Core
- Topic: un stream de eventos con nombre (como una categoría).
- Partition: un topic se divide en particiones para paralelismo; cada partición es un log ordenado y append-only.
- Offset: la posición de un mensaje dentro de una partición.
- Consumer Group: un conjunto de consumers que comparten las particiones de un topic.
- Broker: un servidor Kafka que almacena y sirve mensajes.
- Producer: una aplicación que publica eventos en topics.
- Consumer: una aplicación que se suscribe a topics y procesa eventos.
Una topología de stream processing lee de topics source, transforma eventos (posiblemente con estado) y escribe a topics sink — todo lo del medio es tu código.
Producer
El contrato del producer en cualquier lenguaje: configura acks=all para durabilidad y enable.idempotence=true para que los retries no produzcan duplicados. Ambos son seguro barato contra las dos fallas que realmente vas a ver — crashes de broker a mitad de escritura y timeouts de cliente.
Python (aiokafka)
from aiokafka import AIOKafkaProducer
import json
import asyncio
async def produce_events():
producer = AIOKafkaProducer(
bootstrap_servers="localhost:9092",
value_serializer=lambda v: json.dumps(v).encode("utf-8"),
key_serializer=lambda k: k.encode("utf-8") if k else None,
acks="all",
enable_idempotence=True,
)
await producer.start()
try:
for i in range(100):
await producer.send_and_wait(
"orders",
key=f"order-{i}",
value={"order_id": i, "amount": 99.99 * i, "status": "created"},
)
finally:
await producer.stop()
asyncio.run(produce_events())
La key importa más de lo que parece: order-{i} se convierte en la partition key, así que todos los eventos de la misma orden caen en la misma partición y mantienen orden. Quita la key y Kafka hace round-robin — pierdes el ordenamiento por entidad y cualquier join downstream que dependa de ella se rompe.
Java (Kafka Producer)
import org.apache.kafka.clients.producer.*;
import java.util.Properties;
public class OrderProducer {
public static void main(String[] args) {
Properties props = new Properties();
props.put("bootstrap.servers", "localhost:9092");
props.put("key.serializer", "org.apache.kafka.common.serialization.StringSerializer");
props.put("value.serializer", "org.apache.kafka.common.serialization.StringSerializer");
props.put("acks", "all");
props.put("enable.idempotence", "true");
try (Producer<String, String> producer = new KafkaProducer<>(props)) {
for (int i = 0; i < 100; i++) {
ProducerRecord<String, String> record = new ProducerRecord<>(
"orders",
"order-" + i,
"{\"order_id\":" + i + ",\"amount\":" + (99.99 * i) + "}"
);
producer.send(record, (metadata, e) -> {
if (e != null) {
e.printStackTrace();
} else {
System.out.printf("Sent to partition %d offset %d%n",
metadata.partition(), metadata.offset());
}
});
}
}
}
}
La versión con callback es asíncrona: los mensajes se acumulan en batches y se flushean en background. send().get() serializaría cada escritura y destruiría el throughput — usa el callback, maneja los errores ahí, y dejá que el buffer trabaje.
Consumer
Los consumers leen de particiones en el contexto de un consumer group. La única regla que importa: commitea los offsets después de procesar, nunca antes — de lo contrario un crash pierde mensajes silenciosamente.
Python (aiokafka)
from aiokafka import AIOKafkaConsumer
import json
import asyncio
async def consume_events():
consumer = AIOKafkaConsumer(
"orders",
bootstrap_servers="localhost:9092",
group_id="order-processor",
value_deserializer=lambda v: json.loads(v.decode("utf-8")),
key_deserializer=lambda k: k.decode("utf-8") if k else None,
auto_offset_reset="earliest",
enable_auto_commit=False,
)
await consumer.start()
try:
async for msg in consumer:
print(f"Topic={msg.topic}, Partition={msg.partition}, Offset={msg.offset}")
print(f"Key={msg.key}, Value={msg.value}")
await consumer.commit()
finally:
await consumer.stop()
asyncio.run(consume_events())
auto_offset_reset="earliest" reproduce el historial para un grupo nuevo — normalmente lo que querés para un procesador. "latest" salta todo lo publicado antes de que arranque el consumer, lo que descarta silenciosamente el backlog en el primer deploy.
JavaScript (KafkaJS)
const { Kafka } = require("kafkajs");
const kafka = new Kafka({
clientId: "order-consumer",
brokers: ["localhost:9092"],
});
const consumer = kafka.consumer({ groupId: "order-processor" });
async function consumeEvents() {
await consumer.connect();
await consumer.subscribe({ topic: "orders", fromBeginning: true });
await consumer.run({
eachMessage: async ({ topic, partition, message }) => {
const event = JSON.parse(message.value.toString());
console.log(`Processing order ${event.order_id}, amount: ${event.amount}`);
// Procesar la orden...
},
});
}
consumeEvents();
KafkaJS commitea automáticamente después de que eachMessage resuelve por defecto — la misma garantía at-least-once que el commit manual, porque un error lanzado deja el offset sin commitear y el mensaje se re-entrega.
Kafka Streams (Java)
Kafka Streams es la herramienta correcta cuando el procesamiento necesita estado — agregaciones, joins, windows — sin levantar un cluster de procesamiento separado. Es una librería dentro de tu app Java: topología, estado local, exactly-once y tolerancia a fallas incluidos.
Una topología es un grafo dirigido de procesadores de stream: los nodos source leen topics, los nodos procesador transforman, los nodos sink escriben de vuelta. El estado vive en stores RocksDB locales, respaldados por changelog topics para que otra instancia pueda reconstruirlo si la primera muere.
Filter y branch
import org.apache.kafka.streams.*;
import org.apache.kafka.streams.kstream.*;
import java.util.Properties;
public class OrderStreamProcessor {
public static void main(String[] args) {
Properties props = new Properties();
props.put("application.id", "order-processor");
props.put("bootstrap.servers", "localhost:9092");
props.put("default.key.serde", "org.apache.kafka.common.serialization.Serdes$StringSerde");
props.put("default.value.serde", "org.apache.kafka.common.serialization.Serdes$StringSerde");
StreamsBuilder builder = new StreamsBuilder();
KStream<String, String> orders = builder.stream("orders");
// Branch por monto
KStream<String, String>[] branches = orders.branch(
(key, value) -> value.contains("\"amount\":0"),
(key, value) -> true
);
KStream<String, String> zeroOrders = branches[0];
KStream<String, String> validOrders = branches[1];
// Filtrar órdenes de alto valor
KStream<String, String> highValue = validOrders.filter(
(key, value) -> {
// Parsear y verificar amount > 1000
return value.contains("\"amount\":1");
}
);
highValue.to("high-value-orders");
validOrders.to("processed-orders");
KafkaStreams streams = new KafkaStreams(builder.build(), props);
streams.start();
}
}
application.id también es el nombre del consumer group — toda instancia con el mismo ID comparte particiones y estado automáticamente. Así escala Streams: agregas instancias, las particiones se reasignan, el trabajo se distribuye.
Agregación (count por key)
KTable<String, Long> orderCounts = orders
.groupBy((key, value) -> key, Grouped.with(
Serdes.String(),
Serdes.String()
))
.count();
orderCounts.toStream().to("order-counts");
KStream vs KTable: un stream es una secuencia de eventos; una tabla es el valor actual por key — estado materializado. La agregación convierte un stream en una tabla, y el changelog de la tabla fluye a un topic interno *-changelog para recuperación ante fallas. GlobalKTable replica la tabla completa en cada instancia — úsala para datos de lookup chicos, nunca para estado de alto volumen.
Agregación con ventanas (ventanas tumbling de 5 minutos)
KTable<Windowed<String>, Long> windowedCounts = orders
.groupByKey()
.windowedBy(TimeWindows.ofSizeWithNoGrace(Duration.ofMinutes(5)))
.count();
windowedCounts.toStream((key, value) -> key.key() + "@" + key.window().start())
.to("windowed-order-counts");
El windowing es donde la semántica se pone sutil. Tres tipos de ventana: tumbling (fijas, sin solapamiento — reportes), hopping (solapadas, ej. ventana de 5 min cada minuto — tendencias), session (guiadas por gap — ráfagas de actividad de usuario). El grace period controla cuánto tiempo una ventana acepta eventos tardíos: ofSizeWithNoGrace descarta lo que llegue después de cerrada la ventana — el default ofSizeAndGrace(Duration.ofMinutes(5), Duration.ofMinutes(1)) mantiene un minuto de buffer para rezagados.
Join de streams
KStream<String, String> orders = builder.stream("orders");
KStream<String, String> payments = builder.stream("payments");
KStream<String, String> enriched = orders.join(
payments,
(orderValue, paymentValue) -> orderValue + "|" + paymentValue,
JoinWindows.of(Duration.ofMinutes(5)),
Joined.with(Serdes.String(), Serdes.String(), Serdes.String())
);
enriched.to("enriched-orders");
Los joins stream-stream son por ventana: el join solo empareja eventos dentro de la ventana temporal — un pago 10 minutos después de la orden no matchea. Para datos de referencia que no expiran (lookups de cliente), joinea contra una KTable o GlobalKTable en su lugar — nunca falla.
DSL vs Processor API
El DSL (stream, filter, groupBy, windowedBy) cubre el 90% de los casos. Bajá a la Processor API (process(), punctuators, acceso manual a state stores) solo cuando necesites: punctuación custom por intervalos de wall-clock o stream-time, lecturas directas del state store en medio de la topología, o forwarding no estándar. Mezcla ambos: construye la topología DSL y adjunta un nodo .process() donde necesites la salida de escape.
Exactly-once con Kafka Streams
props.put("processing.guarantee", "exactly_once_v2");
Con exactly_once_v2, Kafka Streams envuelve read-process-write-commit en una transacción por tarea: eventos duplicados, escrituras de estado y registros de salida aterrizan todos o ninguno. El costo es un golpe de latencia de unos cientos de ms por intervalo de commit — reduce commit.interval.ms (default 30s) para commits más rápidos a mayor overhead.
Dead Letter Topics y Manejo de Errores
Todo pipeline eventualmente encuentra un mensaje envenenado: JSON malformado, un campo faltante, un payload más grande que el límite del broker. Sin un camino de dead-letter, ese mensaje bloquea su partición para siempre — el consumer lo reintenta hasta que las alertas de lag suenan y alguien saltea el offset manualmente.
El patrón es simple: captura por mensaje, rutea las fallas a un DLT con suficiente contexto para debuggear después, y continúa.
async for msg in consumer:
try:
process_order(msg.value)
await consumer.commit()
except Exception as e:
# Rutear el mensaje envenenado a un dead-letter topic con contexto
await producer.send_and_wait(
"orders-dlt",
key=msg.key,
value={
"original_value": msg.value,
"error": str(e),
"partition": msg.partition,
"offset": msg.offset,
},
)
await consumer.commit() # Saltea el mensaje envenenado, sigue procesando
Monitorea el DLT como un topic real — un DLT que crece significa que los producers upstream están enviando datos malos, no que los consumers están rotos. Alertá sobre la tasa del DLT, muéstrelo semanalmente, y reprócesalo después de los fixes (consumilo de vuelta al pipeline con un grupo dedicado).
Escalado y Testing de Aplicaciones Stream
Kafka Streams escala agregando instancias del mismo application.id: las particiones se rebalancean entre ellas automáticamente, y cada instancia recibe su parte del estado. Dos knobs importan para resiliencia: num.standby.replicas=1 mantiene una copia pasiva de cada state store en otra instancia (failover sin reconstrucción en frío), y num.stream.threads controla el paralelismo dentro de una instancia — ajústalo a los cores.
Para testing, TopologyTestDriver corre tu topología completa en memoria — sin cluster:
TopologyTestDriver driver = new TopologyTestDriver(builder.build(), props);
TestInputTopic<String, String> input =
driver.createInputTopic("orders", Serdes.String().serializer(), Serdes.String().serializer());
TestOutputTopic<String, Long> output =
driver.createOutputTopic("order-counts", Serdes.String().deserializer(), Serdes.Long().deserializer());
input.pipeInput("order-1", "{\"amount\": 99.99}");
assertThat(output.readValue()).isEqualTo(1L);
Testea la lógica stateful así — windowing, joins y agregaciones funcionan todas en el driver. Lo que no puede cubrir es el comportamiento distribuido (rebalancing, failover de standby), que necesita un cluster real; el docker-compose del repo companion te da uno.
Operativamente, vigila la frecuencia de rebalance: cada reinicio de instancia dispara una reasignación de particiones, y las tareas stateful tardan más en volver que las stateless porque primero reproducen sus changelog topics. Un catch-up largo después de un rebalance suele significar state stores demasiado grandes — si una tarea tiene gigabytes, considera más particiones o una retención más corta en el changelog.
Schema Registry
Los schemas son contratos entre producers y consumers. Sin un registry, un campo renombrado embarca un breaking change que solo notas cuando los servicios downstream crashean. Con uno, el serializer del producer fuerza compatibilidad al escribir.
Registrar un schema Avro
from confluent_kafka import SerializingProducer
from confluent_kafka.schema_registry import SchemaRegistryClient
from confluent_kafka.schema_registry.avro import AvroSerializer
schema_registry_conf = {"url": "http://localhost:8081"}
schema_registry_client = SchemaRegistryClient(schema_registry_conf)
schema_str = """
{
"type": "record",
"name": "Order",
"fields": [
{"name": "order_id", "type": "int"},
{"name": "amount", "type": "double"},
{"name": "status", "type": "string"}
]
}
"""
avro_serializer = AvroSerializer(schema_registry_client, schema_str)
producer_conf = {
"bootstrap.servers": "localhost:9092",
"key.serializer": "org.apache.kafka.common.serialization.StringSerializer",
"value.serializer": avro_serializer,
}
producer = SerializingProducer(producer_conf)
producer.produce(
topic="orders-avro",
key="order-1",
value={"order_id": 1, "amount": 99.99, "status": "created"},
)
producer.flush()
Los modos de compatibilidad definen qué cambios son legales: backward (el schema nuevo lee datos viejos — solo agregar campos con defaults), forward (el schema viejo lee datos nuevos — solo borrar campos con defaults), full (ambos). El default práctico es backward: los consumers actualizados a su propio ritmo nunca se rompen por un cambio del producer. JSON funciona sin registry, Avro/Protobuf/JSON-Schema no — en el momento en que los payloads se complican, registra.
Kafka Connect
Connect mueve datos entre Kafka y sistemas externos — escribes configs JSON, no código. Corre como un cluster de workers distribuidos: cada conector genera tareas que leen de un source (JDBC, S3, MongoDB) o escriben a un sink (Elasticsearch, warehouses), manejando offsets, retries y conversión de schema mediante converters y transforms (SMTs) enchufables.
JDBC Source Connector
{
"name": "postgres-source",
"config": {
"connector.class": "io.confluent.connect.jdbc.JdbcSourceConnector",
"connection.url": "jdbc:postgresql://localhost:5432/mydb",
"connection.user": "postgres",
"connection.password": "secret",
"table.whitelist": "orders",
"mode": "incrementing",
"incrementing.column.name": "id",
"topic.prefix": "postgres-",
"key.converter": "org.apache.kafka.connect.json.JsonConverter",
"value.converter": "org.apache.kafka.connect.json.JsonConverter"
}
}
mode=incrementing pollea sobre una columna auto-incremental — simple, pero pierde actualizaciones a filas existentes. Para change data capture (updates, deletes), usa Debezium en su lugar: lee el WAL y emite eventos a nivel de fila con el estado completo antes/después.
Elasticsearch Sink Connector
{
"name": "es-sink",
"config": {
"connector.class": "io.confluent.connect.elasticsearch.ElasticsearchSinkConnector",
"tasks.max": "1",
"topics": "processed-orders",
"connection.url": "http://localhost:9200",
"type.name": "_doc",
"key.converter": "org.apache.kafka.connect.json.JsonConverter",
"value.converter": "org.apache.kafka.connect.json.JsonConverter",
"schema.ignore": "true"
}
}
tasks.max controla el paralelismo — súbelo para matchear el conteo de particiones en sinks de alto volumen. schema.ignore=true acepta JSON sin schema; déjalo en false cuando pases a Avro para que Connect valide contra el registry.
Patrones de Stream Processing
| Patrón | Descripción | Caso de uso |
|---|---|---|
| Filter | Descarta eventos que no cumplen un predicado | Remover órdenes inválidas |
| Map | Transforma cada evento | Enriquecer con datos de cliente |
| Aggregate | Agrupa y reduce | Contar órdenes por cliente |
| Window | Agrega en el tiempo | Promedio rolling de 5 minutos |
| Join | Combina dos streams | Órdenes + pagos |
| Split | Rutea a múltiples topics | Órdenes de alto/bajo valor |
| Repartition | Re-keyea un stream | Agrupar por customer_id en vez de order_id |
Repartition merece atención: es el invisible. Cualquier groupBy sobre una key distinta dispara un repartition topic interno — cada cambio de key significa un salto de red completo para todo el stream. Minimiza los cambios de key, y dimensiona los repartition topics como topics reales (retención, monitoreo).
Buenas Prácticas
- Usa
acks=allen producers — asegura que los datos se escriben en múltiples réplicas - Habilitá producers idempotentes — previene duplicados en retries
- Configurá
enable.auto.commit=false— commitea offsets después de procesar, no antes - Manejá errores de deserialización — usa un dead-letter topic para poison pills
- Usa Schema Registry — fuerza compatibilidad de schema, previene romper consumers
- Particioná por key para ordenamiento — los eventos con la misma key van a la misma partición
- Dimensioná las particiones correctamente — apuntá a 10-50 MB/s de throughput por partición
- Monitorea el consumer lag — lag creciente significa que los consumers no van al día
- Usa exactly-once para pipelines críticos — configura
processing.guarantee=exactly_once_v2 - Configurá la retención sabiamente — por tiempo (7 días) o por tamaño (1GB) por topic
- Usa consumer groups para paralelismo — cada consumer del grupo recibe un subconjunto de particiones
Errores Comunes
- No manejar poison pills — un mensaje malo bloquea la partición completa
- Usar
auto.offset.reset=latest— los consumers nuevos pierden datos históricos - No configurar
max.poll.interval.ms— los consumers lentos son expulsados del grupo - Sobre-particionar — demasiadas particiones aumentan overhead y latencia
- No monitorear lag — los problemas emergen solo cuando los usuarios se quejan
- Usar Kafka como base de datos — Kafka es un log, no un store queryable
- No usar Schema Registry — los cambios de schema rompen consumers en silencio
- Producir sin key — los eventos se distribuyen aleatoriamente, perdiendo garantías de orden
Ver También
- Stream Processing: Pipelines de Datos Event-Driven
- Guía Completa de Apache Kafka en Producción
- Guía de Arquitectura Event-Driven
- Apache Kafka Streams Documentation (oficial)
- Kafka Connect Documentation (oficial)
- Confluent Schema Registry Fundamentals (oficial)
Todas las configs de clientes y la topología de Streams de esta página están como código ejecutable en el repositorio companion — un cluster KRaft, la app de Streams y scripts de producer/consumer listos para docker compose up.
Preguntas frecuentes
¿Cuántas particiones debería tener un topic?
Empieza con 6-12 particiones para la mayoría de los topics. Agrega particiones si el consumer lag crece o el throughput excede 50 MB/s por partición. No podés reducir particiones después — solo agregar. Planificá para el throughput pico, no el promedio.
¿Cuándo usar Kafka Streams vs un consumer simple?
Consumer simple si solo transformas y escribes o alimentás otro sistema. Kafka Streams en el momento en que necesites estado: agregaciones, joins, windows o procesamiento exactly-once. Si entra en un loop de consumer sin un Map de estado que mantienes tú, todavía no necesitas Streams.
¿Cuál es la diferencia entre KStream y KTable?
Un KStream es una secuencia ilimitada de eventos — cada registro es un hecho nuevo. Una KTable es el valor actual por key — los registros posteriores actualizan los anteriores. Las agregaciones producen KTables; joinear un stream contra datos de lookup usa KTable o GlobalKTable del lado del lookup.
¿Cómo maneja el windowing los eventos tardíos?
Las ventanas tienen un grace period: cuánto tiempo permanecen abiertas para eventos que llegan tarde. TimeWindows.ofSizeWithNoGrace descarta lo que pase del límite; ofSizeAndGrace mantiene un buffer. Los eventos tardíos más allá del grace se descartan en silencio — alértalos si tu SLA no puede permitirse la pérdida.
¿Cómo logro procesamiento exactly-once?
Para Kafka Streams, configura processing.guarantee=exactly_once_v2. Para loops consumer-producer, usa la API transaccional: initTransactions(), beginTransaction(), send + commit offset, commitTransaction(). Cuesta latencia — unos cientos de ms por commit — así que resérvalo para pipelines donde los duplicados duelen.
¿Cuál es la diferencia entre Kafka Connect y escribir mi propio consumer?
Connect maneja offsets, retries, conversión de schema y paralelismo para sources/sinks estándar — escribes JSON, no código. Escribe un consumer cuando tu source/sink no está cubierto por un conector existente o necesitas lógica de negocio en el loop. No escribas consumers custom para "leer tabla JDBC a topic" — eso es exactamente para lo que es Connect.
Recursos Relacionados
Guía Completa de Sistemas Event-Driven
Diseña backends event-driven: event sourcing, CQRS, sagas, outbox pattern, idempotency, eventual consistency y patrones de producción.
GuideGuía Completa de Comunicación entre Microservicios
Compara patrones de comunicación síncrona vs asíncrona para microservicios. Cubre REST, gRPC, colas de mensajes, event-driven, service mesh y cuándo usar cada uno.
PatternPatrón Pipes and Filters: Pipelines de Datos Componibles
Encadena filtros independientes con pipes para construir pipelines de transformación de datos reutilizables y componibles.
RecipeConsumer Groups de Kafka con Python para Streaming Escalable
Crea consumer groups de Kafka en Python con asignación de particiones, gestión de offsets, manejo de rebalanceos y semántica exactly-once usando confluent-kafka.
RecipeConsumir Tópicos de Kafka con Spring Boot Stream Listeners
Construye consumers de Kafka confiables en Spring Boot con @KafkaListener: concurrencia, acks manuales, reintentos con dead-letter topics y batch listeners.
GuideGuía Completa para Configurar un Cluster de Elasticsearch
Despliega y escala clusters de Elasticsearch en producción. Cubre roles de nodos, sharding, index templates, mapping, ILM, snapshots, seguridad y tuning.