Cheat sheet: Kafka e stream processing

Questa pagina appartiene al binario ml-tabellare e raccoglie in forma operativa tutto il modulo: non un riassunto da leggere, ma una lista di review da usare prima di ogni rilascio Kafka.

L’idea in una frase

Questa pagina è la lista di review che rende ogni rilascio Kafka verificabile su topic, client, schemi e metriche.

La procedura in cinque passi

1. Verifica owner, chiave, schema compatibile e retention di ogni topic.
2. Allinea i producer su acks=all, idempotenza e batch calibrato.
3. Allinea i consumer su commit manuale e reset esplicito degli offset.
4. Controlla lag, partizioni sotto-replicate e spazio disco prima del rilascio.
5. Blocca il rilascio su ogni voce mancante: la lista è un criterio, non un promemoria.

Come usare questa pagina

Prima di aprire una pull request su una pipeline Kafka, il team deve rispondere in fretta a domande pratiche: chi possiede il topic, qual è la chiave, quale schema è compatibile, quanto dura la retention, quali consumer sono critici e come si misura il lag. Questa pagina raccoglie quei controlli in forma operativa, da usare come lista di revisione più che come lettura lineare. Ogni voce deve produrre una decisione verificabile: se non lo fa, resta un promemoria elegante e inutile.

La review prima del rilascio tocca, nell’ordine, design dei topic, producer, consumer, schemi, connector, stream processing e operations. Per ogni blocco chiediti quale regola serve sotto pressione, quale eccezione è facile dimenticare e quale controllo useresti domani su un progetto reale. Il resto della pagina segue questa traccia.

Essential CLI Commands

# Creare un topic
kafka-topics --create --topic user-events --partitions 16 --replication-factor 3

# Lista consumer groups e lag
kafka-consumer-groups --bootstrap-server localhost:9092 --list
kafka-consumer-groups --describe --group my-group

# Leggere messaggi
kafka-console-consumer --topic user-events --from-beginning --max-messages 10

Sono i comandi per le tre domande più frequenti durante un incidente: come è fatto il topic, quanto sono indietro i consumer e cosa contengono davvero i messaggi.

Recommended Producer Configurations

acks=all                     # maximum durability
enable.idempotence=true      # deduplicate retries
compression.type=zstd        # maximum compression
linger.ms=5                  # batching
batch.size=65536             # 64KB batch

La combinazione di acks=all e idempotenza protegge dai duplicati nei retry senza sacrificare la durabilità. Il batching con linger.ms e batch.size è il margine su cui si gioca il throughput, e va calibrato sul carico reale.

Recommended Consumer Configurations

group.id=analytics-team
auto.offset.reset=earliest   # leggi tutto se nuovo gruppo
enable.auto.commit=false     # commit manuale
max.poll.records=500         # batch gestibile

Il commit manuale è la scelta da preferire in produzione, perché il commit automatico può confermare offset di messaggi non ancora processati davvero, con perdita silenziosa di dati in caso di crash.

Metrics to Monitor

Metric	Meaning	Alert if
Under-replicated partitions	Broker not in sync	>0 for >1 minute
Consumer lag increasing	Consumer not keeping up	Lag grows linearly
Disk free <30%	Risk of filling up	Plan expansion

Un lag che cresce in modo lineare segnala che il consumer non recupererà da solo: prima o poi servono più capacità o un fix nel processamento.

Serialization Patterns

JSON va bene per sviluppo rapido e debugging, ma non garantisce uno schema. Avro con Schema Registry è la scelta da produzione quando servono contratti forti ed evoluzione sicura. Protobuf dà la performance migliore e si usa tipicamente per la comunicazione gRPC tra servizi interni. La regola è semplice: se il dato attraversa team o sopravvive nel tempo, vuoi uno schema registrato.

Anti-pattern da evitare

Un topic con una sola partizione e retention infinita è un collo di bottiglia che non scala e cresce senza limite. Lasciare il commit automatico attivo in produzione espone a perdita silenziosa di messaggi. Una chiave null su un topic compattato impedisce la compattazione e va contro lo scopo del topic stesso. E assumere un ordine globale tra partizioni diverse porta a bug sottili, perché Kafka garantisce l’ordine solo dentro la singola partizione.

Come impostare la scelta

La domanda di fondo, prima di toccare la configurazione, non è “quale parametro imposto” ma “quale decisione operativa devo rendere più sicura”. Rendi esplicita l’unità di lavoro (topic, evento, schema, producer, consumer o stream processor), il segnale osservato (latenza, throughput, lag, compatibilità schema, perdita dati), la baseline di lettura e la decisione attesa, che sia un contratto evento, una pipeline o una policy. Il rischio costante è scambiare un numero disponibile per una prova sufficiente.

Un caso di review

Durante una review, la cheat sheet fa emergere che nessuno ha definito retention e owner di un topic usato da tre consumer. Il rilascio viene corretto prima della produzione: meno urgenze in incident room e più decisioni prese quando il sistema è ancora facile da modificare. È il tipo di problema che una lista di controllo intercetta e che un occhio distratto lascia passare.

Verdetto: JSON per prototipi, Avro con registro per contratti tra team, Protobuf dove la performance interna domina, e commit manuale con acks=all appena i dati contano.

L’esempio che fa da riferimento

Kafka nasce in LinkedIn e viene pubblicato open source nel 2011 per unificare eventi ad alto volume sotto un unico log. Nel 2014 gli stessi ingegneri fondano Confluent e trasformano quell’esperienza operativa in configurazioni e controlli standard: replica multipla, idempotenza, commit espliciti e monitoraggio del lag. Le voci di questa pagina discendono da quel percorso: ogni comando e soglia risponde a un guasto già visto in produzione. Usata come lista di review prima del rilascio, la pagina previene gli incidenti che la fretta lascia passare.

Domande per verificare la lezione

1. Chi possiede il topic e quanta retention dichiara prima del rilascio?
2. Quale chiave ordina gli eventi e quale schema risulta compatibile?
3. Quale consumer è critico e quanto lag tollera prima dell’escalation?
4. Quale voce della pagina blocca il rilascio se manca?