Skip to main content
PreparationZone Logo
PrepZone

Poll Loop, max.poll.interval, and Heartbeats

Why long-running VaultCommerce handlers must not block poll() — heartbeats, session timeout, and max.poll.interval.ms.

Pass checkpoint below

Why this matters

  • VaultCommerce's image-resize consumer exceeded max.poll.interval — kicked from group every 10 minutes.
  • Heartbeats prove liveness; poll frequency must stay within session.timeout.ms / 3.
  • Long processing belongs off the poll thread — pause/resume or decouple with queue.
  • Classic on-call issue: 'consumer keeps rebalancing'.
Topic partitions
P0
P1
P2
Group: inventory-service
Consumer Areads P0
Consumer Breads P1
Consumer Creads P2
Each partition is consumed by exactly one consumer in the group. Add consumers up to partition count.

poll() contract

consumer.poll(Duration) returns records AND sends heartbeats. Default max.poll.records=500 — processing 500 heavy records before next poll risks timeout. VaultCommerce sets max.poll.records=50 for inventory and processes in a worker pool with pause/resume.

Key points

  • poll() — fetch records and maintain group membership
  • max.poll.interval.ms — upper bound on time between poll() calls
  • session.timeout.ms — heartbeat failure threshold
  • heartbeat.interval.ms — typically session.timeout / 3
  • pause()/resume() — stop fetching while processing backlog locally

The rest of this guide is part of Pro

Free covers every fresher guide in full. Pro unlocks Senior, Staff and Architect guides across every track.

Still to come · 2 sections

  • Timeouts explained
  • VaultCommerce rollout checklist

Test yourself

Answer these before moving on — recall is what makes it stick.