Receiving Messages
Fetch mechanics, live tail, visibility timeouts, and how the local cache works.
The Fetch Operation
The Operations panel gives you two controls:
- Count (default 100, up to 100,000) — how many messages to receive.
- Visibility (s) (default 10, range 10–43,200) — how long received messages stay hidden from other consumers.
SQS returns at most 10 messages per ReceiveMessage call, so Tarmac drains toward your count with up to 4 concurrent receive calls, stopping when the count is reached or after 3 consecutive empty responses. Every message is requested with all attributes and system attributes, so receive counts, sent timestamps, and FIFO metadata are always captured. A running fetch can be cancelled at any time — messages already received stay in the cache.
Fetch is a sample, not a snapshot
SQS is a distributed system: a fetch grabs whatever the service returns, in no guaranteed order, and the queue keeps moving while you drain it. Empty responses don't prove the queue is empty (that's why Tarmac retries 3 times before stopping), and depth counters are approximate. Treat a fetch as "a large representative sample right now," not a consistent export.
Choosing a Visibility Timeout
The visibility timeout is the most consequential setting in Tarmac. While a message is invisible:
- your real consumers cannot receive it, and
- Tarmac holds a valid receipt handle for it, which is what destructive actions (delete, redrive) require.
That creates a genuine trade-off:
- Browsing / inspection — keep the default 10 seconds. Messages return to the queue almost immediately and your consumers barely notice.
- Delete or redrive sessions — set the visibility to comfortably cover the time you'll spend selecting, staging, and publishing (e.g. 300–900 seconds). If the window expires before you publish, the message becomes visible again, may be received by a consumer, and your staged delete can no longer act on it.
Receipt handles expire with the visibility window
Destructive actions only work on messages received in the current session, using the receipt handle from that receive. Once the visibility window lapses — or another consumer receives the message — the handle goes stale and the action is skipped or fails at publish time. Fetch with a generous visibility timeout, then publish promptly. If a publish reports skips, re-fetch and re-stage.
Live Tail
Live Tail polls the queue every 3 seconds, receiving at most one message per tick with a 1-second visibility timeout. It's designed to observe traffic, not consume it: messages reappear on the queue within a second, and nothing is deleted.
Use it to answer "is anything flowing right now?" and to watch new messages arrive while you work. Keep its limits in mind:
- It samples — one message per 3 seconds — so on a busy queue it shows a trickle, not the full stream.
- During each 1-second window it competes with your consumers for the messages it touched, and each observation increments the message's receive count.
- It stops automatically if a fetch error occurs.
A green Live indicator appears in the top bar while a tail is running.
The Local Cache
Everything Tarmac receives — fetched or tailed — is written to a local SQLite cache, keyed by queue and message ID. Re-receiving the same message updates the existing row (refreshing its receipt handle) rather than duplicating it, which quietly absorbs SQS's at-least-once redelivery.
The cache is what makes Tarmac pleasant to use:
- Search and filters run entirely locally — zero SQS calls, no visibility side effects, works offline.
- Messages persist across restarts, so yesterday's fetch is still searchable today.
- Each message stores its body, attributes, receive metadata, and any resolved S3 payload.
The footer shows the cached message count and the last cache time for the selected queue.
The cache is a snapshot, not the queue
A cached message may have since been consumed, deleted, moved to a DLQ, or expired by the retention period. The cache tells you what the message was when you received it. When freshness matters, fetch again — the cache updates in place.
Clear Cache removes the local copy for the selected queue only. It never deletes anything from SQS.