Create a consumer with subscription type Key_Shared; all messages sharing the same orderingKey (or message key) are routed to the same consumer, while different keys can be processed in parallel by different consumers
Choose between AUTO_SPLIT (consistent hashing, keys redistributed on consumer join/leave) and STICKY (manual key range assignment per consumer) hash range modes
For STICKY mode, set KeySharedPolicy.stickyHashRange(startRange, endRange) on the consumer to pin a specific hash range; the broker only delivers messages whose key hash falls in that range to this consumer
Handle subscription changes: when a consumer joins or leaves under AUTO_SPLIT, a short rebalancing period may cause a brief pause in delivery for keys that are being reassigned
Set consumer receiveQueueSize appropriately; a size of 0 disables pre-fetching and ensures the consumer only receives one message at a time, useful for strict ordering requirements at the cost of throughput
Monitor consumerStats via the Pulsar Admin API to observe per-consumer message rates and detect hot keys where one consumer receives disproportionately more traffic
Known gotchas
Key_Shared does not guarantee ordering if multiple consumers in the same subscription have overlapping key ranges; use STICKY mode with non-overlapping ranges or AUTO_SPLIT with allowOutOfOrderDelivery=false for strict ordering
Negative acknowledgments (nack) in Key_Shared mode can cause out-of-order redelivery for the same key; implement idempotent processing or use a dead-letter topic for failed messages rather than nacking indefinitely
Key_Shared subscriptions require the broker to maintain a routing table per key; a topic with very high key cardinality (millions of distinct keys) can create significant broker memory pressure
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp