How to inspect and manage Azure Service Bus sessions
Updated July 21, 2026
Azure Service Bus sessions group related messages by the application-defined SessionId and give one
receiver an exclusive lock on that session. They are the Service Bus mechanism for ordered processing within
each group, not a global ordering guarantee across an entire queue or subscription.
With QueueExplorer, open a session-enabled queue or topic subscription to list its sessions, filter or sort by Session ID, inspect messages in each session, and view the session's application-owned state.
How Azure Service Bus sessions work
- The sender assigns the same
SessionIdto messages that belong to one ordered stream. - A session receiver accepts one available session or a specific Session ID and acquires its exclusive session lock.
- While that lock is valid, no other receiver can process messages from the same session.
- Different sessions can be processed concurrently by different receivers.
- Messages inside the session are settled individually, while lock ownership applies to the session as a whole.
- Optional session state stores an application checkpoint or a pointer to external state.
Sessions are available in Standard and Premium, not Basic. They must be enabled when the queue or subscription is created; Azure Service Bus does not let you turn sessions on or off later. Once enabled, senders must set a Session ID and consumers must accept sessions. Ordinary non-session send/receive code is no longer sufficient, although Peek can still browse the entity.
See Microsoft's current message sessions documentation for the protocol model.
1. List sessions in a queue or subscription
- Connect QueueExplorer and select the session-enabled queue or topic subscription.
- Wait while QueueExplorer discovers the available sessions.
- Leave Preload messages enabled when the entity is small enough and you want message counts, last-message times, and faster movement between sessions.
- Turn preloading off, or cancel after session discovery, when the entity contains too many messages. QueueExplorer will load a session's messages when you select it.
- Sort or filter the session list to find the required Session ID.
Preloading is a diagnostic convenience, not a requirement. On a large production entity it can consume client memory and take long enough for the displayed counts to become stale. Start without preloading when session or message cardinality is unknown.
Free trial for Windows, macOS, and Linux
2. Inspect messages within a session
Select a session to display its messages. Add Sequence Number, Message ID, Subject, Enqueued Time, Expires At, Delivery Count, and application properties as columns. Select a message to view its body as JSON, XML, text, WCF, or hex.
You can select multiple sessions for comparison and use QueueExplorer's filtering to isolate a customer, order, workflow, or correlation key. QueueExplorer Professional can extract values from JSON, XML, or text bodies into sortable columns.
Messages with the same Session ID are ordered relative to one another, but a displayed browse list is still a diagnostic snapshot. Active consumers may hold a session lock or settle messages while you inspect it. Pause the relevant receiver when an operator action depends on an exact sequence.
3. View, back up, edit, or clear session state
QueueExplorer shows the selected session's state in a dedicated panel with text, hex, XML, and JSON viewers. Use the representation that matches the application's serialization format.
Before editing session state:
- Stop or pause the consumer that can accept this session.
- Save the raw state bytes, Session ID, entity, namespace, and time.
- Confirm the serializer, schema version, checkpoint semantics, and valid transitions with the application owner.
- Make the smallest necessary change and preserve the original for rollback.
- Restart one consumer instance and verify the next message and downstream state before resuming normal concurrency.
Session state remains stored until a client explicitly clears it, even after all messages in the session are consumed. It counts toward the entity's storage quota. Microsoft documents a maximum state size equal to one message: 256 KB in Standard and 100 MB in Premium. Applications should clear finished state by setting it to null.
4. Manage messages in a session
After selecting one or more messages, QueueExplorer can save, copy, move, delete, defer, schedule, or dead-letter them. The same safeguards used for non-session messages still apply, with an additional ordering constraint.
- Save first. Keep a full-message backup and export the separate session state.
- Preserve Session ID deliberately. A session-enabled destination rejects messages without one.
- Expect a new position. Copying, moving, editing, or replaying sends a new message at the end of the destination session with a new Sequence Number and Enqueued Time.
- Do not silently change groups. Choosing a different Session ID changes which messages are ordered and processed together.
- Check duplicate detection. Preserving Message ID can suppress a replay inside the detection window.
- Reconcile application state. Moving a message without adjusting its checkpoint can make state and queue contents disagree.
When an operation creates new messages, QueueExplorer can keep each source message's Session ID or use a Session ID you specify. Use a different ID only when the business workflow is intentionally being reassigned.
Session locks, Delivery Count, and TTL
Session lock behavior
Accepting a session locks all its messages to one receiver. The client must renew the session lock when processing
takes longer than the lock duration. If the lock expires or the AMQP link detaches, Azure Service Bus can raise
SessionLockLost; the session becomes available for another receiver.
Microsoft documents that when an accepted session lock expires, Delivery Count increases. Closing a session without completing its messages does not by itself increment their Delivery Count. Do not repeatedly open a session and allow its lock to expire during an investigation.
TTL behavior is session-wide
For a session-enabled queue or subscription, Microsoft documents that if any message in a session passes its TTL, the service expires all messages related to that session, dropping or dead-lettering them according to the entity setting. Expiration occurs when there is an active listener. Monitor the oldest message and dead-letter settings, not just the most recent activity.
Common Azure Service Bus session problems
| Symptom | Likely cause | What to check |
|---|---|---|
| Messages are present but a normal receiver gets none | The entity requires sessions | Use a session receiver and verify Session ID |
| One session is not progressing | A receiver holds its lock, a message is failing, or application state is inconsistent | Lock owner, Delivery Count, DLQ, consumer logs, and session state |
SessionLockLost | Lock timeout, idle timeout, link detach, service update, or entity change | Processing time, renewal, connectivity, idle behavior, and retries |
| Storage remains used after messages are gone | Session state was not cleared | Inspect state and clear it only after confirming workflow completion |
| Replay appears out of order | The replayed copy was appended at the session's tail | New Sequence Number and application ordering logic |
| A session batch expires together | One message passed TTL on a session-enabled entity | Oldest message, TTL, listener activity, and dead-letter-on-expiration |
Production session checklist
- Confirm that the entity is session-enabled and identify the affected Session IDs.
- Pause receivers before editing state or changing ordered message contents.
- Back up messages and raw session state separately.
- Keep processing within the lock or renew it intentionally.
- Clear completed session state to release storage.
- Make replayed processing idempotent and expect new Sequence Numbers.
- Test repairs on an equivalent non-production entity before applying them to production.
Frequently asked questions
Do Azure Service Bus sessions guarantee FIFO ordering?
They guarantee exclusive, ordered delivery within a Session ID while the receiver follows the session model. They do not impose one global order across different sessions, and replaying a message appends a new copy at the end.
Can I enable sessions on an existing queue or subscription?
No. Session support is fixed when the entity is created. Create a replacement entity and migrate producers, consumers, messages, and configuration if the design must change.
Does Azure Service Bus delete session state when the last message is consumed?
No. State remains and uses entity storage until a client explicitly clears it by setting the state to null.
Can I move a message to another session?
QueueExplorer can send a new copy with another Session ID and remove the source. That changes its ordered group and broker metadata, so reconcile the old and new session state and verify the destination before deleting the original.
For message-level procedures, see how to move selected Azure Service Bus messages and back them up first.
QueueExplorer: a better way to inspect and manage Azure Service Bus
See what is happening in Azure Service Bus and resolve message problems without writing one-off tools. Browse queues and topic subscriptions, inspect message contents, and manage your Azure Service Bus environment from one desktop application. Try it free on Windows, macOS, or Linux.