Service Bus - Peek Queues, Manage Dead-Letter Messages from Terminal

The Service Bus view lets you browse namespaces, queues, and topics. You can peek messages (read-only) and then optionally lock and manipulate dead-letter messages — requeue them to the active queue, move them to a different target, or complete them outright.

Common tasks this replaces:

• az servicebus commands chained together to peek and parse messages
• Opening Azure Portal’s Service Bus Explorer to check dead-letter queues
• Writing scripts to requeue or clean up DLQ messages
• Manually counting message depths across multiple queues

Pane layout

The view uses miller-columns that grow as you drill in:

Namespaces → Entities → Subscriptions (topics only) → Active/DLQ → Messages → Preview

• Entities are queues and topics for the selected namespace.
• Subscriptions only appears when you’ve selected a topic.
• Active/DLQ is a two-item picker where you choose which queue type to browse.
• Messages is empty by default — peek is a deliberate action, not automatic.
• Preview opens when you press Enter on a message.

Not all panes are visible at once — the view shows a parent, focused, and child pane and shifts as you navigate.

Browsing entities

Entities are queues and topics within a namespace. Press Enter on a namespace to load its entities.

For queues, pressing Enter takes you to the Active/DLQ picker.

For topics, pressing Enter shows the topic’s subscriptions. Select a subscription to reach the Active/DLQ picker.

Sorting and filtering entities

Press s (or a → Sort entities) on the entities pane to open the sort picker:

• Default order
• Name (ascending / descending)
• Active messages (ascending / descending)
• Dead letters (ascending / descending)

The action menu also offers Filter: only with dead letters to hide entities with zero DLQ messages, and Show all entities to clear the filter. The filter is action-menu-only — there is no dedicated shortcut.

Peeking messages

After selecting Active or DLQ, the messages pane is empty. Peek is a deliberate action — no network round-trip happens until you ask for it.

Open the action menu (a) from the messages pane and choose one of:

• Peek active / DLQ messages — fetch the first batch (label says active or DLQ based on which queue is open)
• Peek more active / DLQ messages — append another batch, continuing from where the previous peek left off
• Peek active / DLQ messages (fresh) — discard the current batch and peek from the start
• Clear messages — drop the local snapshot without peeking

Note

Session-enabled queues and subscriptions

An entity that requires sessions refuses the plain receiver a normal peek uses, so lazyaz peeks it by walking its sessions instead: it accepts each available session, peeks inside it, and merges the results in sequence order so the list looks like any other peek. “Peek more” continues from the last sequence number across all sessions. The spinner says “walking sessions” and the status line reports how many sessions the batch spans. The inspect strip (K) shows whether an entity requires sessions.

Two things to know:

• The sessions stay locked for the duration of the walk, usually a few seconds. A live consumer waits that long for them. The walk covers at most 64 sessions per peek.
• The walk only sees sessions that nobody else holds. A session a live consumer has locked is skipped by the broker, so its messages do not appear in the peek even though they are in the queue. The entity’s active count (inspect strip, K) still includes them; to see their contents while the consumer holds the session, use the portal’s Service Bus Explorer, which peeks across locked sessions too.
• Receive-with-lock walks sessions the same way and locks each accepted session whole. Each locked message is settled through the session that holds it, so complete, move and abandon work as on a plain queue. A session lock expires after the entity’s lock duration (one minute by default) if you leave the locked view idle, at which point settling fails and you receive again. “Move all” from the queue-type pane also walks sessions, draining and releasing one session at a time.
• The dead-letter queue is not session-aware: it peeks and receives as usual.

Peeking is read-only. It does not lock or consume messages. You can peek the same DLQ repeatedly without affecting it.

Press Enter on a peeked message to open the preview pane with the full message body. You can select text in the preview with the mouse to copy it.

Key	Action
Enter	View message detail
h / Esc / Backspace	Close message preview
p	Cycle the preview: body → broker properties → custom properties
R	Requeue received DLQ message(s) (opens a confirmation prompt)
y	Yank the current view (body or property table) to clipboard
Space	Mark / unmark message
v / V	Enter visual-line mode to select a range
o	Swap anchor while in visual mode
Esc	Commit visual selection as marks

Message properties

The preview pane has three views, mirroring the tabs in the portal’s Service Bus Explorer. Press p to cycle through them; the pane title names the one you are on.

View	Contents
Body	The message payload, with = to pretty-print JSON or XML
Broker properties	Every property the broker sets: IDs, sequence numbers, enqueued / scheduled / expiry times, TTL, delivery count, state, content type, subject, correlation and session IDs, partition key, reply-to and to, lock token, and the dead-letter source, reason and description
Custom properties	The sender’s application properties as a key / value table, keys sorted

The property views are ordinary text: scroll them, search with /, enter the vim capture with v to select and yank a single value, or press y to yank the whole table. The chosen view sticks while you step between messages, so you can walk a dead-letter queue with the custom properties up the whole time. The inspect strip (K) still shows the one-line summary; the property views are where the full text lives.

The copy palette (Y) offers the two tables and each custom property on its own, for pasting a single value straight into a search or a ticket.

Dead-letter queue operations

Caution

DLQ modifications happen in two modes: peek (read-only, default) and receive-with-lock (actions that remove or move messages). The lock-based flow uses Azure Service Bus’s native peek-lock semantics so operations are transactional. Closing the messages pane or navigating away abandons any held locks automatically.

Every destructive DLQ operation — requeue (marked or all), complete, and move — opens a confirmation prompt showing the affected entity and message count before anything executes. y / Enter confirms, n / Esc cancels. Move operations confirm after you’ve picked the target entity, so the prompt can name the destination.

Receive with lock

To actually change queue state, open the action menu and choose Receive DLQ messages (with lock) — or Receive active messages (with lock) on the active queue. This receives up to 50 messages in a single 30-second call — often fewer, depending on the broker — and holds locks on them. The pane title changes to DLQ Locked (N) / Locked (N) to indicate the mode. If nothing locks (count is 0), only Abandon all is useful.

Once locked, the action menu offers:

• Requeue N message(s) — DLQ only: send each locked message to the active queue, then complete it from the DLQ
• Move N message(s) to… — send each locked message to a different target queue or subscription (picker opens), then complete it from the source
• Complete N message(s) (remove from DLQ/queue) — complete without re-sending; on the active queue this is how you delete specific messages
• Abandon all (release locks) — release all locks, messages stay put

N is the number of marked messages, or 1 (the cursor) if nothing is marked. Use Space or visual-line mode to mark messages before opening the action menu.

Receiving from the active queue competes with real consumers: locked messages are invisible to them until you abandon or the lock expires, and every receive+abandon cycle increments the delivery count — enough cycles can push a message over its max delivery count into the DLQ.

Bulk operations from the queue type pane

For larger jobs, skip the per-message lock flow and use the action menu on the queue type pane (Active/DLQ picker). Both entries only appear when the selected queue type has at least one message.

• Requeue all DLQ messages (N) — drains the entire DLQ to the active queue. Receives in batches of 50, sends each, completes each, repeats until empty.
• Move all active messages to… (N) / Move all DLQ messages to… (N) — same but sends to a different target you pick. The label includes whether it’s the active or DLQ queue based on which one you have open.

These are safer than looping locally because they lock each batch before processing, and recover if interrupted (unprocessed messages retain their original delivery count).

Both bulk operations are bounded by a 120-second window. Very large queues may complete partially — the result notification reports how many succeeded before the deadline.

Move targets

Picking Move … to… opens a target picker. The first phase lists entities in the current namespace plus a synthetic Other namespace... entry; selecting that opens a second phase to pick a different namespace, then entities within it.

Cross-namespace moves require AAD with Send rights on the target — there’s no connection-string fallback for the target side, so an explicit “Send claim required” error means the credential doesn’t have the right role.

Operation progress

Long-running bulk operations show progress through a spinner and resolve with a notification when they finish. The app-level Activity overlay (F) tracks in-flight cache fetches across all tabs, but Service Bus requeue/move operations are not currently wired into it — watch the notifier and pane status instead.

Selecting messages

Mark individual messages with Space, or use visual-line mode (v) to select a range. Marked messages can be operated on in bulk through the action menu.

Visual-line mode behaves like vim:

1. Press v to anchor at the current message.
2. Move the cursor to extend the selection; press o to extend from the other end.
3. Press v again or Esc to commit the range to marks.

Visual selection respects an active filter — the range covers exactly the rows you see, so messages hidden by the filter are never marked.

Inspect panel

Press K to toggle the inspect strip, which shows a fixed set of fields for the current selection: namespace (name / subscription / resource group / FQDN), entity (name / kind / active / DLQ counts), or topic subscription (name / parent topic / active / DLQ counts).

For messages the strip is the place for debugging and fault inspection: ID, enqueued time, delivery count, content type, correlation ID, subject, session, the sender’s custom application properties, and — in the DLQ view — the dead-letter reason and error description the broker recorded, plus the body preview.

Jump list

Service Bus tabs participate in the cross-tab jump list. Pressing Ctrl+O jumps back to your previous navigable position (including a different tab); Ctrl+I goes forward. See Navigation for details.

Actions

Press a to open the action menu. Available actions depend on which pane is focused.

Entities pane

Action	Description
Sort entities	Sort by name, active count, or dead-letter count
Show all entities / Filter: only with dead letters	Toggle the DLQ entity filter

Queue type pane

Both entries only appear when the selected queue type has count > 0.

Action	Description
Requeue all DLQ messages (N)	Requeue every dead-letter message back to the active queue
Move all active / DLQ messages to… (N)	Move all messages of the open type to a different queue or subscription

Messages pane — peek mode

Action	Description
Peek active / DLQ messages	Fetch a batch of messages (read-only); label depends on the open queue
Peek more active / DLQ messages	Append another batch
Peek active / DLQ messages (fresh)	Discard current batch and re-peek
Clear messages	Drop the local snapshot
Receive active / DLQ messages (with lock)	Lock messages for transactional operations; label depends on the open queue
Open blob in explorer	Cross-tab jump — shown (here and in the preview pane) when the cursor message is a Microsoft.Storage.Blob* Event Grid envelope; opens a Blob tab pre-positioned on that blob
Toggle mark	Mark or unmark the current message
Toggle visual line selection	Enter or exit visual-line mode

Messages pane — locked mode

Action	Description
Requeue N message(s)	Send marked messages to the active queue and complete from DLQ
Move N message(s) to…	Send marked messages to a different target and complete from DLQ
Complete N message(s) (remove from DLQ)	Complete marked messages without re-sending
Abandon all (release locks)	Release all held locks without modifying messages
Toggle mark	Mark or unmark the current message
Toggle visual line selection	Enter or exit visual-line mode

Any pane

Action	Description
Refresh	Reload the current scope (hidden from message preview)
Toggle details panel	Show or hide the inspect strip (hidden from message preview)
Change subscription	Open the subscription picker
Open theme picker	Open the theme picker (standalone only)
Toggle help	Open or close the help overlay (standalone only)

The Message preview pane offers only the Open blob in explorer entry (when the cursor message is an Event Grid blob event) plus subscription / theme / help — refresh and inspect are intentionally hidden because they have no effect on a single-message view.

Keybindings

Key	Action
Tab / Shift+Tab	Cycle pane focus
Enter / l	Open / drill in
h / Left	Go back
/	Filter focused pane
Ctrl+D / Ctrl+U	Half-page scroll
a	Action menu
s	Open sort picker (entities pane)
Space	Toggle mark (messages pane)
v / V	Visual-line selection
o	Swap visual anchor
Esc	Exit visual mode (commits selection) / close preview / cancel filter or overlay
K	Toggle inspect panel
p	Cycle message preview: body / broker properties / custom properties
S	Switch subscription
r	Refresh — re-fetches entity counts from the queue-type pane; re-peeks from the messages pane (unless DLQ is locked)
F	Activity overlay (app-level — currently shows cache fetches only)
Ctrl+O / Ctrl+I	Jump back / forward in history