Kafka — Core Model

1Glossaire

• Broker — serveur Kafka qui stocke des partitions et sert les producers/consumers.
• Topic — catégorie logique d'événements (ex: stock-moved, order-created).
• Partition — subdivision d'un topic — log ordonné, append-only, stocké sur un broker.
• Offset — position d'un message dans une partition — immuable, croissant.
• Segment — fichier physique constituant une partition — .log + .index + .timeindex. Un seul segment actif, N segments fermés derrière.
• Producer — client qui écrit des messages dans un topic.
• Consumer — client qui lit des messages depuis un topic.
• Consumer group — ensemble de consumers qui se partagent les partitions d'un topic.
• Coordinator — broker responsable de la gestion d'un consumer group (rebalance, offsets).
• Rebalance — redistribution des partitions entre les consumers d'un groupe.
• Retention — durée ou taille au-delà de laquelle Kafka supprime les anciens messages.
• Compaction — politique alternative qui conserve la dernière valeur par clé au lieu de purger par âge.
• Tombstone — message avec value=null utilisé pour signaler une suppression dans un topic compacted.

2Topics, partitions et offsets

Un topic est divisé en partitions indépendantes. Chaque partition est un log append-only : les messages s'accumulent dans l'ordre d'arrivée, chacun reçoit un offset unique et immuable.

flowchart LR
  subgraph T["Topic: stock-moved"]
    subgraph P0["Partition 0"]
      direction LR
      m0["offset 0\nSKU-A"] --> m1["offset 1\nSKU-C"] --> m2["offset 2\nSKU-A"]
    end
    subgraph P1["Partition 1"]
      direction LR
      n0["offset 0\nSKU-B"] --> n1["offset 1\nSKU-D"]
    end
    subgraph P2["Partition 2"]
      direction LR
      o0["offset 0\nSKU-E"]
    end
  end

L'offset est par partition — il n'y a pas d'offset global entre partitions. La lecture ne supprime pas le message, il reste jusqu'à expiration de la rétention. L'ordre est garanti à l'intérieur d'une partition, jamais entre partitions.

3Producer et stratégie de clé

Le producer envoie (topic, key, value). La partition cible est calculée par hash(key) % nombre_de_partitions. Même clé → même partition → ordre garanti pour cette clé. C'est le seul mécanisme d'ordre disponible dans Kafka.

// ✓ Tous les événements du même stock arrivent dans la même partition
producer.send(new ProducerRecord<>("stock-moved", stockId, event));

4Consumer groups et parallélisme

Un consumer group permet à plusieurs instances du même service de se partager les partitions. Chaque partition est assignée à un seul consumer dans le groupe à la fois.

flowchart LR
  subgraph G["Consumer group: stock-service"]
    C1["Pod A"]
    C2["Pod B"]
    C3["Pod C"]
  end
  P0["Partition 0"] --> C1
  P1["Partition 1"] --> C2
  P2["Partition 2"] --> C3

Deux consumers de groupes différents peuvent lire le même topic indépendamment — chaque groupe a ses propres offsets.

Dimensionnement : pods vs partitions

Le rapport entre le nombre de pods (consumers) et le nombre de partitions décide qui consomme quoi. Deux régimes opposés.

Cas 1 — plus de pods que de partitions (3 partitions, 5 pods) :

Un pod oisif n'est pas inutile : il reste membre du groupe, envoie ses heartbeats, participe aux rebalances et sert de hot standby. Si un pod actif tombe, le coordinator lui réassigne une partition au prochain rebalance.

Pod 2 tombe → rebalance → Pod 4 récupère P1 et devient actif.

Cas 2 — plus de partitions que de pods (5 partitions, 3 pods) :

Tous les pods consomment, toutes les partitions sont couvertes, mais le parallélisme reste plafonné à 3 — chaque pod traite ses partitions assignées séquentiellement.

La règle qui borne tout

consumers actifs = min(partitions, pods)

5Rebalance

Le coordinator déclenche un rebalance quand un consumer rejoint ou quitte le groupe, quand session.timeout.ms est dépassé (heartbeat absent), ou quand max.poll.interval.ms est dépassé (consumer bloqué sur le traitement).

Eager vs Cooperative

Deux protocoles coexistent — comprendre lequel est actif change radicalement l'impact opérationnel.

# Recommandé en prod sur clients récents
partition.assignment.strategy=org.apache.kafka.clients.consumer.CooperativeStickyAssignor

6Offset commit — la frontière critique

Le commit d'offset déclare à Kafka "j'ai traité jusqu'ici". C'est la position de reprise en cas de crash ou rebalance. La règle absolue : commiter après que le traitement est persisté, jamais avant.

sequenceDiagram
  participant C as Consumer
  participant K as Kafka
  participant DB as Base de données

  C->>K: poll() → messages 0..99
  C->>DB: INSERT / UPDATE
  DB-->>C: OK
  C->>K: commitSync() → offset 100
  Note over C,K: crash ici → reprise à 100, pas de perte

try {
    process(records);        // ✓ traitement métier
    ecrireEnBase(records);   // ✓ persistance
    consumer.commitSync();   // ✓ commit après succès garanti
} catch (Exception e) {
    // ⚠️ pas de commit → les messages seront retraités
}

7Delivery semantics

8Retention et log compaction

La rétention décide quand un message ancien disparaît. Deux politiques mutuellement combinables via cleanup.policy. Pour comprendre quand chacune déclenche, il faut d'abord comprendre les segments — l'unité physique sur laquelle elles opèrent.

Anatomie d'un segment

Une partition n'est pas un seul fichier — c'est une suite ordonnée de segments, chacun composé de plusieurs fichiers sur disque :

/var/kafka-logs/stock-moved-0/
├── 00000000000000000000.log        ← messages (base offset 0)
├── 00000000000000000000.index      ← offset → position fichier
├── 00000000000000000000.timeindex  ← timestamp → offset
├── 00000000000000012453.log        ← segment suivant (base offset 12453)
├── 00000000000000012453.index
├── 00000000000000012453.timeindex
└── 00000000000000024891.log        ← segment actif (writes en cours)

Le nom de fichier est le base offset : l'offset du premier message du segment, padé à 20 chiffres. Quand un consumer demande l'offset 15000, Kafka trouve le segment 12453.log (plus grand base offset ≤ 15000), utilise .index pour sauter directement à la bonne position dans le fichier, lit le message.

Cycle de vie d'un segment

À tout instant, une partition a un seul segment actif (le dernier, celui où les nouveaux messages sont appendés) et N segments fermés derrière.

écritures → [segment actif] | [segment fermé] [segment fermé] [segment fermé]
                  ↑                                                ↑
              writes ici                                    plus ancien

Conditions de rotation (le segment actif se ferme, un nouveau démarre) :

• segment.bytes atteint (défaut : 1 Go)
• segment.ms écoulé depuis l'ouverture (défaut : 7 jours)
• Le premier des deux gagne.

Un segment fermé est immuable. Plus aucune écriture, jamais. C'est ce qui rend Kafka efficace : pas de mise à jour en place, pas de réécriture, juste append puis archivage.

Politique delete (défaut) — purge par âge ou taille

cleanup.policy=delete
retention.ms=604800000      # 7 jours (défaut)
retention.bytes=-1          # illimité (défaut)
segment.ms=604800000        # rotation segment toutes les 7j
segment.bytes=1073741824    # 1 Go par segment

La règle de purge ne s'applique qu'aux segments fermés, et au segment entier. Conséquences concrètes :

1. La rétention effective est toujours ≥ celle configurée. Si retention.ms=1h mais que segment.ms=24h, un message émis à T+0 dans un segment qui se ferme à T+24h ne sera purgeable qu'à partir de T+25h (rétention basée sur le timestamp du dernier message du segment). Tu peux observer 25h de rétention réelle pour 1h configurée — c'est normal, pas un bug.

2. La rétention se compte depuis le timestamp du dernier message du segment, pas depuis sa fermeture. Un segment qui couvre T+0 → T+24h devient éligible à la purge à T+24h + retention.ms.

3. Le segment actif n'est jamais purgé, même si tous ses messages ont dépassé retention.ms. Forcer la rotation (segment.ms court) accélère la purge sur les topics peu actifs.

# Topic peu actif (heartbeat, métriques rares) — forcer la rotation
segment.ms=3600000        # 1h au lieu de 7j
retention.ms=86400000     # garde 24h

Sans ce réglage, un topic à 10 messages/jour garderait potentiellement des semaines de données — le segment actif ne tournerait jamais sur segment.bytes.

retention.ms et retention.bytes s'appliquent en parallèle (OR) — le premier seuil atteint déclenche le nettoyage.

Dimensionner les segments

La taille d'un segment résulte du premier seuil atteint entre segment.bytes et segment.ms. Le défaut (1 Go / 7 jours) convient aux topics actifs ; sur les autres, il faut arbitrer. Les deux extrêmes coûtent cher.

Segments trop gros (segment.ms très long, ou segment.bytes jamais atteint sur un topic peu actif) :

Segments trop petits (segment.ms=1s ou segment.bytes minuscule) :

Cadrage pratique — caler segment.ms sur l'ordre de grandeur de la rétention :

Politique compact — dernière valeur par clé

cleanup.policy=compact
min.cleanable.dirty.ratio=0.5
delete.retention.ms=86400000   # rétention des tombstones (24h)
min.compaction.lag.ms=0

Au lieu de purger par âge, Kafka conserve uniquement la dernière valeur pour chaque clé. Le log cleaner ne touche pas au segment actif. Il scanne uniquement les segments fermés, en deux phases :

Phase 1 — Build : log cleaner parcourt les segments fermés
                  construit en mémoire une map { clé → dernier offset connu }

Phase 2 — Sweep : réécrit les segments en supprimant les entrées
                  dont l'offset est < dernier offset de leur clé
                  → de plus petits segments fusionnés

Un message avec value=null (tombstone) marque la clé comme supprimée. Il reste lui-même delete.retention.ms puis disparaît.

Avant compaction :
  k=A,v=1  k=B,v=10  k=A,v=2  k=C,v=100  k=B,v=null  k=A,v=3

Après compaction :
  k=C,v=100  k=B,v=null  k=A,v=3

Conséquence majeure : l'offset n'est plus continu dans un topic compacted. Un consumer qui boucle de 0 à N verra des "trous" — normal, ne pas en faire un bug.

Paramètres qui retardent la compaction :

• min.cleanable.dirty.ratio (défaut 0.5) — le cleaner ne démarre que quand bytes_compactable / bytes_total dépasse le seuil. Sur un topic peu actif, ça peut tarder des heures.
• min.compaction.lag.ms — empêche la compaction d'un message tant qu'il n'a pas atteint cet âge. Utile pour garantir aux consumers une fenêtre de lecture de toutes les versions.
• delete.retention.ms (défaut 24h) — combien de temps une tombstone reste après compaction avant d'être elle-même éliminée. Trop court = un consumer en retard peut rater la suppression.

delete,compact — combiné

cleanup.policy=delete,compact

Compaction + plafond de rétention temps/taille. Utile pour limiter la croissance d'un topic compacted dont l'espace des clés grossit indéfiniment.

Quand choisir quoi

Inspecter les segments sur disque

# Lister les segments d'une partition
ls -lh /var/kafka-logs/stock-moved-0/

# Dump lisible du contenu d'un segment
kafka-dump-log.sh --files 00000000000000012453.log --print-data-log

# Vérifier intégrité de l'index
kafka-dump-log.sh --files 00000000000000012453.log --index-sanity-check

Utile pour diagnostiquer un consumer qui voit des "trous" (compaction normale) vs un vrai bug de production, ou pour vérifier qu'une rétention configurée a bien pris effet.

9Idempotence côté consumer

Puisque at-least-once est la norme, le consumer doit être idempotent : exécuté plusieurs fois sur le même message, il produit le même résultat.

// ❌ Pas idempotent — exécuté 2 fois = stock faux
stock.setQuantity(stock.getQuantity() + 10);

// ✓ Idempotent — exécuté N fois = même résultat
stock.setQuantity(100);

// ✓ Idempotent via clé de déduplication
if (!dejaTraite(event.getId())) {
    traiter(event);
    marquerTraite(event.getId()); // ✓ constraint UNIQUE en DB
}

Sources

• Apache Kafka — Introduction — design du log distribué, topics, partitions, offsets
• Apache Kafka — Log Compaction — mécanique du log cleaner, tombstones, configuration
• Apache Kafka — Topic-level configs — segment.ms, segment.bytes, retention.ms, min.cleanable.dirty.ratio, min.compaction.lag.ms
• Confluent — Kafka Consumer Design — consumer groups, rebalance protocol, offset management
• Confluent — Guide to Consumer Offsets — sémantique exacte des offsets commités, at-least-once, leader epoch
• KIP-429 — Kafka Consumer Incremental Rebalance Protocol — design du CooperativeStickyAssignor
• kafka-infra-cluster — ISR, réplication, durabilité, KRaft
• kafka-producer-consumer-tuning — batching, idempotence producer, sticky partitioner, poll loop, commit manuel
• kafka-connect-1-fondamentaux — Connect source/sink qui consomme ces partitions ; topics internes compacted
• pattern-outbox-publication-fiable-de-messages-depuis-une-transaction-db — at-least-once et idempotence consumer appliqués au pattern outbox