Why this matters
- VaultCommerce keys by orderId so payment, ship, and cancel events for one order stay ordered.
- Null keys round-robin across partitions — fine for metrics, wrong for order lifecycle.
- Custom partitioners are rare; get the key right first.
- Hot keys create partition imbalance — monitor per-partition byte rate.
Default partitioner behavior
Kafka 3.x uses sticky partitioning for null keys (batch to one partition until batch fills) and murmur2 hash for non-null keys. VaultCommerce never sets a custom partitioner — orderId string keys distribute well across 12 partitions for their SKU mix.
Key points
- Partition key — business identifier hashed to partition index
- Sticky partitioner — batches null-key records to reduce partition spread
- Hot partition — skewed key distribution overloads one broker
- Ordering scope — guaranteed only among records sharing a key
- Partition count — fixed at topic creation; affects hash distribution
Explicit partition override
You can set partition index directly on ProducerRecord — VaultCommerce uses this only in tests. Production always relies on keys. Overriding bypasses ordering guarantees when keys would have collided intentionally.
VaultCommerce rollout checklist
Before promoting changes that touch the VaultCommerce order and payment event backbone, run the staging KRaft cluster (Kafka 3.7+, Schema Registry 7.x) through a 10k events/min soak test. Compare producer request latency p99 and consumer lag per group against the pre-deploy baseline. Same key → same partition → per-key ordering. Document the change in the internal topic registry, attach Grafana screenshots to the change ticket, and keep an engineer on lag dashboards for 30 minutes after production rollout — roll back the service release before altering broker-level settings if lag or under-replicated partitions spike.
// VaultCommerce — key by orderId for lifecycle ordering
OrderPlaced event = new OrderPlaced(orderId, customerId, lines, total);
ProducerRecord<String, OrderPlaced> record =
new ProducerRecord<>("vaultcommerce.orders.placed.v1", orderId, event);
// partition = murmur2(orderId) % 12 — same orderId always same partition
// Anti-pattern: key by customerId — one VIP customer's orders pile on one partition
// ProducerRecord<>(topic, customerId, event); // causes hot partition during launches
Quick recall
Everything you need if you only revisit this box.
- Same key → same partition → per-key ordering.
- Use orderId, not customerId, for checkout events.
- Monitor per-partition throughput for hot keys.
Test yourself
Answer these before moving on — recall is what makes it stick.