User guide
To setup Service Bus Cloud Explorer to be used for your tenant; create a Service Bus Cloud Explorer resource in Azure Portal or from Azure Marketplace. For more details on setup process; please visit: Setup in your tenant page.
To start Service Bus Cloud Explorer; users need to navigate to servicebus.cloudbricks.io and login with their organization accounts.
During the first time any user logs in to the app, a consent screen will show up (if your organization administrator didn't consent on behalf of all users). Users have to consent on the following:
- Access Azure Service Management As you. This is required as the app users Azure Service Management APIs to load all namespaces, topics, queues and other information like active message counts and dead letter queue counts.
- Have full access to Azure Service Bus service This is required to be able to perform service bus operation on behalf of logged in user like peeking a message off a queue or sending a message to a topic. (Please note that App access is limited to the access of the user despite what appears in the title.)
- View your basic profile. This is required to log in users and get access to basic information like user email.
- Maintain access to data you have give it access to. This is required to be able to use refresh tokens to avoid having to log in users every time they use the app.
The name of the logged-in user will appear in the application top bar. To log out; click on user name and click log out button from the popup menue.
The default method to authenticate to Service Bus entities is via user's Azure AD identity.
A basic read access over Service Bus namespaces is enough to populate all entities in left sidebar. In addition to that; the following permissions might be needed:
- To send messages via user identity; users need
Azure Service Bus Data Senderpermission. - To peek or receive messages via user identity; users need
Azure Service Bus Data Receiverpermission.
The following screenshot is showing the permissions applied on a Resource Group level:
On the left sidebar, a tree of all namespaces in which the logged-in user have access to will show up. Users can expand nodes of the tree, which will load selected entities i.e. topics, queues and subscriptions on demand. Multiple namespaces can be expanded at the same time:
Users can filter topic and queues by name to narrow down the tree to a subset or a specific entity.
In left sidebar you can see active and dead-lettered message counts for all entities in the format: [active], [dead-lettered].
Users can set selected entity by clicking a topic, queue or subscription on the left sidebar. Which will reflect on entity information window:
In the middle of the screen, the tab navigation is showing all the actions that can be performed on Service Bus messages: Browse, Send, Peek, Receive and Replay.
Browse messages enables users to browse all messages in queues and subscriptions without locking them (i.e. message retry count will not be increased upon reading messages). For more information check message-browsing.
Use the filtering functionality to filter rows of the grid via a particular criteria.
Browse messages grid by-default displays few of the most important columns. However, you can use the show/hide column features to control what should be displayed.
Use the ordering functionality to order by any column ascending or descending.
If you're dealing with a large number of messages you can use the limit dropdown to define an approximate number of messages to retrieve to save time and resources.
- Loading messages will
pauseif number of loaded messages equals or more than defined limit. - Loading messages will
resumeif number of loaded messages are less than limit.
In the paging section you can see exactly how many messages loaded in memory.
Click on any row on the grid to select the message and reveal its full details in the right sidebar.
Press ctrl and click a selected row to unselect.
Click Export all button to export all messages currently loaded in memory in JSON format.
Export functionality exports a JSON array of objects where each object represents a message where message schema is defined here.
The following example is for an exported JSON document:
[
{
"messageId": "631cc5679d4741fe8f2e57b0fea03b81",
"body": {
"foo": "bar"
},
"timeToLive": 1209600000,
"deliveryCount": 10,
"applicationProperties": {
"DeadLetterReason": "MaxDeliveryCountExceeded",
"DeadLetterErrorDescription": "Message could not be consumed after 10 delivery attempts."
},
"contentType": "application/json",
"state": "active",
"enqueuedTimeUtc": "2022-04-15T04:39:52.127Z",
"lockedUntilUtc": "2022-04-26T06:17:23.204Z",
"deadLetterReason": "MaxDeliveryCountExceeded",
"deadLetterErrorDescription": "Message could not be consumed after 10 delivery attempts.",
"expiresAtUtc": "2022-04-29T04:39:52.127Z"
}
]For documentation on each of those fields, please check relevant properties in Message Interface
To send messages switch to Send tab. Sending messages requires sender permission on the target entity.
For documentation on each of those fields, please check relevant properties in Message Interface
To send multiple messages you can switch to Import mode where you can upload a JSON file with an array of messages following schema defined here.
By default even if JSON file includes messages with messageId property; the app removes those properties to avoid the chance of having messages with duplicate messageId properties. To change that behaviour turn off Generate Message Ids option.
Peeking is a Non-destructive Read operation of messages. To peek a single or multiple messages; switch to peek tab, select number of messages to peek and click peek button.
Note this uses the Peek-Lock message operation. After
reading the message the lock is released via an abandon operation which will increase deliveryCount and potentially could move the message to dead-letter queue if max retry count reached. This could be useful in some testing scenarios, however, if you want to read messages without locking please use Browse Messages instead.
Peeked messages will show up in Event Log view. Click on status or message URLs to see all the details of loaded messages and the entire operation.
Receiving is a Destructive Read operation of messages and will permanently delete the message(s) from Service Bus. To receive/delete a single or multiple messages; switch to receive tab, select number of messages to receive and click receive button.
Received/deleted messages will show up in Event Log view. Click on status or message URLs to see all the details of those messages and the entire operation.
Replay functionality can be used to resubmit messages ended up in dead-letter queues and submitting them to either queues or topics and optionally delete messages from dead-letter queues after being resubmitted.
Note Replaying messages in a subscription's dead-letter queue will resubmit messages to subscription's topic. If topic has multiple subscriptions this may -based on filters- end up submitting messages into other subscriptions.
All replay operations will be show up in Event Log table.
