Event partition key design starts with the smallest business set that must be observed in order. Choosing a key from an available column, a desire for even hashing, or a diagram labeled customer can either destroy required order or serialize far too much traffic. The key determines placement and therefore the maximum ordering scope, parallelism, hot-key exposure, failure coupling, and replay behavior. It is a domain decision implemented by the event platform.
Kafka orders records within a partition, Kinesis maps partition keys to shards, and Pub/Sub ordering applies to messages with the same ordering key under documented regional and subscription conditions. None supplies a single global business order by default. A correct design states an invariant such as all state transitions for one order must be applied in sequence, then uses order ID consistently from producer through broker and consumer.
Build the six-stage partition-key decision path
Write every candidate ordering invariant and challenge it. Does an account balance require ordering per account, or can independent instruments proceed concurrently? Does inventory require one SKU per location rather than one global SKU? Does a customer profile need order across all regions? Identify the state machine, conflicting commands, and consequence of reordering. If consumers use only commutative updates or version checks, strict transport order may be unnecessary.
Select the narrowest stable key that contains all events participating in the invariant. Order ID is usually better than customer ID for an order lifecycle; account ID may be required for one account ledger; tenant ID is rarely appropriate for every tenant event. Document producers that must derive the key and reject missing or malformed values before publication. A null key can route unpredictably and silently remove the intended guarantee.
| Candidate | Ordering scope | Parallelism | Skew risk | When it fits |
|---|---|---|---|---|
| Aggregate or entity ID | One state machine | High when many aggregates are active | Hot individual aggregate | Most domain event streams |
| Tenant ID | All tenant events | Limited by tenant count | Very high for large tenants | Only when cross-entity tenant order is real |
| Region plus entity | Entity within region | High and geographically bounded | Regional demand imbalance | State is intentionally region-scoped |
| Random key | No useful entity order | Very high | Usually low | Independent events with no keyed state |
| Event type | All events of one type | Limited by type count | Popular types become hot | Rarely; mostly specialized serialized processing |
| Composite bucket plus entity | Order within chosen bucket boundary | Higher for splittable workloads | Complex merge semantics | Only when domain can tolerate partitioned aggregate state |
Measure cardinality, frequency, and byte distribution
High distinct-key count helps distribution only if traffic is reasonably spread. Measure events and bytes per key over relevant windows, not just number of keys. Calculate top-key share, percentile key rates, burst duration, payload-size distribution, active keys, and correlation with tenant or product launches. A million dormant keys do not offset one celebrity account producing half the stream.
Use production traces or representative replay to simulate the platform's partitioner and planned partition count. Hashing distributes keys, not records evenly when key frequencies differ. Test both normal and incident bursts, because retry storms can concentrate on the same failed keys. Set acceptance thresholds from partition capacity and consumer processing time, with headroom for maintenance and replay.
Keep key semantics stable across the event lifetime
The same logical aggregate must derive the same key from every producer and event version. Avoid mutable attributes such as customer tier, current region, or owner because a change moves later events elsewhere. Define canonical encoding, case, Unicode normalization, prefixes, and treatment of legacy identifiers. Shared producer libraries can reduce variation, but contract tests must still verify the emitted broker key.
Do not expose sensitive raw identifiers unnecessarily in broker metadata. Hashing a domain ID can preserve stable placement, but rotation and collision handling need policy, and consumers may still need the original identifier in protected payload data. Encryption with randomized output destroys stable mapping. Choose a deterministic nonsecret routing representation under security review.
| Test | Method | Pass condition | Defect revealed |
|---|---|---|---|
| Determinism | Generate key repeatedly across languages and versions | Identical canonical bytes | SDK or normalization drift |
| Invariant coverage | Map all conflicting events to keys | Every conflict shares one key | Ordering scope too narrow |
| Skew simulation | Replay realistic key and byte frequencies | Per-partition load remains within headroom | Hot keys or correlated hashes |
| Failure replay | Redeliver and restart consumers by key | State remains valid and duplicates are controlled | Order mistaken for exactly-once effects |
| Missing-key rejection | Publish null, empty and malformed candidates | Producer or gateway rejects safely | Unkeyed events bypass guarantee |
| Scale transition | Increase partitions or shards in a test stream | Documented order and ownership behavior holds | Resharding assumptions are false |
Handle hot keys without pretending they can be hashed away
A single required-order key cannot gain parallel write or processing capacity merely by adding partitions; it still maps as one unit. First reduce unnecessary event volume, batch compatible updates, compact state, optimize the consumer, or isolate the hot aggregate. If the domain operation is commutative or separable, redesign the state into independently keyed subaggregates and define a merge. Salting a key blindly increases throughput by abandoning order.
Rate-limit or backpressure producers with clear fairness policy. Large tenants may deserve dedicated streams or partitions where the platform supports assignment, but operational isolation adds cost and migration work. Monitor key-level heat when available, partition bytes and records, producer throttling, consumer lag, and processing time. Alert on concentration changes before a shard or partition saturates.
Align consumer concurrency with keyed state
Broker placement alone does not preserve effect order if a consumer dispatches records from one partition to an unordered thread pool. Process one key serially, use key-aware executors, or apply sequence and version checks at the state store. Commit progress only after durable effects according to the client contract. On retry, later records for the key may need to wait; otherwise a failed transition can be overtaken.
Ordering does not eliminate duplicates. Consumers still need idempotent event handling and stale-version rejection. Include an aggregate sequence where gaps and reordering must be detected, but define who assigns it atomically with the state transition. Broker offsets are transport positions and should not become domain sequence across topics, repartitioning, or restored environments.
Plan partition growth and key migration before saturation
Adding Kafka partitions changes key-to-partition mapping for common partitioners and can place later records separately from earlier records. Existing order within each partition remains, but a consumer processing old and new placements concurrently may not observe one aggregate sequence. Kinesis resharding and Pub/Sub ordering have their own documented behavior. Test the exact service, client, and transition instead of applying one platform's intuition to another.
Migration options include drain and cutover, new topic with a new partition count, producer epoch plus consumer sequencing, or controlled dual publication with reconciliation. Each must define the boundary at which one owner stops and another starts. Avoid changing key function, partition count, schema, and consumer release simultaneously. Preserve event identity so duplicates across migration can be recognized.
Design replay and recovery around the same invariant
Replay can overload the hottest keys and interleave historical events with live ones. Decide whether to pause live traffic, replay into an isolated stream and rebuild state, or merge using aggregate sequence and version rules. Preserve original key and identity for the same event. A dead-letter tool that republishes without the original key can destroy the very ordering required for recovery.
Test consumer restart, partition reassignment, poison messages, delayed records, duplicates, and missing sequence. Reconcile state from authoritative records after large campaigns. The operating dashboard should show lag and failures by partition and, where safe, key class; aggregate averages hide one blocked ordered key behind healthy parallel work.
Key takeaways
- Start from the exact state transitions that must be observed in order.
- Choose the narrowest stable key covering those conflicts and reject missing keys.
- Measure frequency and bytes per key, top-key concentration, bursts, and consumer cost.
- Do not salt a hot key unless the domain invariant can be split and merged safely.
- Preserve keyed order through consumer execution and add idempotency plus sequence checks.
- Rehearse repartitioning and replay with the exact broker, client, and live-traffic behavior.
Event partition key design FAQ
Can one partition provide global order?
It can serialize one stream under its platform guarantees, but it caps throughput and availability options and may still face duplicate processing. Use it only when a true global invariant justifies the cost, which is uncommon.
Is tenant ID a good default key?
Usually not. It serializes unrelated tenant entities and creates hot partitions for large tenants. Use it only when events across those entities genuinely require one order; otherwise choose the aggregate boundary.
Can adding partitions fix a single hot key?
No. One key remains one routing unit. Reduce or batch traffic, optimize processing, isolate the workload, or split the domain state only when its ordering invariant permits it.
Conclusion
A partition key is an encoded business tradeoff: it buys order for one scope by limiting parallelism for that scope. The right design names the invariant, uses a stable narrow key, measures real skew, preserves order in consumers, detects gaps and duplicates, and plans migration and replay. With that evidence, throughput tuning supports correctness instead of accidentally redefining it.