-
Notifications
You must be signed in to change notification settings - Fork 0
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; you need to navigate to servicebus.cloudbricks.io and login with your organization (work or school) account. Please note that personal accounts are not supported i.e. *@outlook.com or *@hotmail.com.
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 menu.
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 Sender
permission. - To peek or receive messages via user identity; users need
Azure Service Bus Data Receiver
permission.
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.
For messages that contains JSON payloads; users are able to operate on message fields individually which provides lots of benefits when dealing with large number of messages.
By default, only default service bus message properties are displayed in the grid. To display message JSON fields, click on Columns
and select required columns from the available list of JSON fields. All JSON fields will be prefixed with Body.
to indicate they belong to message body.
To search/filter but an individual message JSON field, click on Filters
. You should see all JSON fields (in all object levels) listed in Columns
and available to be used to filter grid rows. All JSON fields will be prefixed with Body.
to indicate they belong to message body.
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
pause
if number of loaded messages equals or more than defined limit. - Loading messages will
resume
if 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.
In some cases users might want to authenticate via providing an Azure AD Client Id & Secret. This comes very handy when access is being granted to an Azure Active Directory service principal or app registration, where users who own the service principal/app registration would be able to test Service Bus integrations without being granted any other permissions or share secrets.
To change to Azure Active Directory Client Id & Secret authentication; select Client Secret
from Authentication
radio button group.
Properties
- Tenant Id: The Id of the Azure Active Directory tenant where the service principal belongs to. By default logged in user sign in tenant id will be populated but users can change to any tenant id.
- Client Id: The client id of the service principal that have permissions on Service Bus.
- Client Secret: The client secret of the service principal that have permissions on Service Bus.
In certain situations, users may need to log in to Azure tenants via guest accounts. To support this, users can change the sign-in flow to log into the tenant where they are guest users, instead of the default home tenant. Follow the instructions below if you need to control the tenant to sign in to:
Simply change the URL that you use to get to the app from https://servicebus.cloudbricks.io/
to https://servicebus.cloudbricks.io/?tenantId=<guest directory tenant id>
. Where <guest directory tenant id>
is the id of the directory you are a guest user in.
Example: https://servicebus.cloudbricks.io/?tenantId=9331b95f-a1dd-4a21-b122-502fda5dff74
-
If needed, logout of your current account via logout button on the top right corner.
-
When prompted to log-in, click
Use another account
:
- Click
Sign-in options
:
- Click
Sign in to an organization
- Enter the domain name of the organization you want to sign in to and click
Next
:
(Tip: In Azure Portal you can get a list of all directories you have access to and the domain of each directory using settings
icon in the top left corner Portal settings
-> Directories + subscriptions
)
- Finally, select or log-in to your account:
User will be redirected back to the app.