Receive and Cache AWS SQS Messages

Learn how Tarmac receives AWS SQS messages, applies visibility timeouts, samples with Live Tail, and stores messages in its local cache.

Fetch messages

The Operations panel gives you two controls:

Count sets how many messages to receive. It defaults to 100 and accepts 1 to 10,000.
Visibility (min) sets how long received messages stay hidden from other consumers. It defaults to 15 and accepts 1 to 720.

SQS returns at most 10 messages per ReceiveMessage call, so a large fetch takes many requests. Tarmac keeps going until it reaches your count, the queue looks empty, held messages block further receives, it hits a 256 MB download limit, or you cancel. You can cancel a running fetch at any time, and messages already received stay in the cache.

On a FIFO queue, messages in the same group stay invisible to everyone while Tarmac holds them. A fetch can therefore stop after the first batch even when the group still has more messages. Tarmac tells you when that happens instead of calling the queue empty. Those held messages also block your real consumers until the visibility window ends.

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, and depth counters are approximate. Treat a fetch as a large representative sample of right now, not a consistent export.

Choose 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. Delete and send-with-delete both need that handle.

That creates a genuine trade-off:

For browsing and inspection, keep the default 15 minutes and work from the cache.
For destructive sessions, choose a window that covers selection and review. Publishing renews visibility for the remaining batch, within SQS's 12-hour receive limit.

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 fails at publish time. Fetch with a generous visibility timeout, then publish promptly. If a publish reports failures, fetch again and re-stage.

Live Tail

Live Tail polls the queue every 3 seconds and receives at most one message per tick with a 1-second visibility timeout. It is built to observe traffic, not consume it. Messages reappear after that second, and nothing is deleted. On a FIFO queue it samples one message per tail session, then waits. Receiving the same group head over and over would increment its receive count until a redrive policy moved it to a DLQ.

Use it to answer "is anything flowing right now?" and to watch new messages arrive while you work. Keep its limits in mind:

On a Standard queue it samples. One message every 3 seconds is a trickle on a busy queue, not the full stream.
On a FIFO queue it samples one message per tail session, then waits.
During each 1-second window it competes with your consumers for the message it touched, and each observation increments that message's receive count.
A message it has already sampled this session is not cached again, so the list only refreshes when the tail sees something new. The message is still received, and that receive still counts.
It stops on its own if a fetch fails, or to protect the queue (below).

A green Live indicator appears in the top bar while a tail is running.

When a tail stops itself

A queue whose messages are not moving hands Live Tail the same head over and over, and every one of those receives counts toward the redrive policy. So Tarmac reads the queue's redrive policy when the tail starts and stops before it can cost you a message:

The queue has no redrive policy. Nothing to trip. The tail runs until you stop it. Watching a DLQ that does not redrive anywhere is unaffected.
The queue redrives at maxReceiveCount. The tail stops as soon as it samples a message that has used every receive the policy allows, so the next one would move it. The toast says the count it saw and what the queue redrives at.
The redrive policy could not be read. The tail stops after the same message comes back three times, because there is no way to tell how much room is left.

Starting the tail again begins a fresh session. If it stops immediately, the queue's head is already near its redrive limit: fetch it and deal with it rather than watching it.

The local cache

Everything Tarmac receives, fetched or tailed, is stored on your machine. Receiving the same message again updates the copy you already have instead of adding a second one.

What the cache gives you:

Search and filters run against the cache. No SQS calls, no visibility side effects, and they work offline.
Messages survive restarts, so yesterday's fetch is still searchable today.
Each message keeps its body, attributes, receive metadata, and any retrieved S3 payload.

The footer shows the cached message count and the time since this session's last successful manual fetch. While Tarmac holds messages invisible, the right side also shows the held message and queue counts.

The cache is a snapshot, not the queue

A cached message may have been consumed, deleted, moved to a DLQ, or expired by the retention period since you received it. The cache tells you what the message was when you received it. When freshness matters, fetch again. The cache updates in place.

Clear Cache is available when the selected queue has a local copy. It removes that copy and nothing else. It never deletes anything from SQS. Before clearing, Tarmac makes every message it still holds visible again by setting the visibility timeout to 0.

Tarmac releases held messages the same way when you quit, close the window, restart after an update, delete all local data, change AWS credentials, or switch regions. It stops Live Tail and in-flight fetches first, waits for receives that already came back, then releases. The dialog reports release progress. If a release request fails, that message stays held until a later release or until its visibility deadline passes. Switching queues does not release messages, but it does stop Live Tail on the queue you leave.

If leaving would keep messages invisible, Tarmac asks first and shows the held message and queue counts. Staged actions stay saved locally, but publishing them means fetching those messages again. You can hide the reminder only for a small hold from one queue with nothing staged.