Skip to content

User guide

Ahmed Elharouny edited this page Jul 10, 2024 · 58 revisions

Setup and permissions

Setup for your tenant

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.

Start the app and login

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.

Provide Consent

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:

  1. 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.
  2. 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.)
  3. View your basic profile. This is required to log in users and get access to basic information like user email.
  4. 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.

Log out

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.

Authenticate via user identity

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:

Explore Service Bus Entities

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:

Filter entities

Users can filter topic and queues by name to narrow down the tree to a subset or a specific entity.

Message counts

In left sidebar you can see active and dead-lettered message counts for all entities in the format: [active], [dead-lettered].

Select entities

Users can set selected entity by clicking a topic, queue or subscription on the left sidebar. Which will reflect on entity information window:

Access Service Bus Messages

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

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.

Filtering

Use the filtering functionality to filter rows of the grid via a particular criteria.

Show/Hide columns

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.

Ordering

Use the ordering functionality to order by any column ascending or descending.

JSON messages support

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.

Ability to display message JSON fields

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.

image

Ability to filter by message JSON fields

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.

image

Apply limit

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.

Show Message Details

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.

Export Messages

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

Send Messages

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

Import Messages

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.

messageId handling during import

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.

Peek Messages

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.

Receive Messages

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 Messages

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.

Authenticate via Azure Active Directory Client Id & Secret

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.

image

Login using a guest account

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:

Option 1 - Via App URL

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

Option 2 - Via Microsoft Log-in flow

  1. If needed, logout of your current account via logout button on the top right corner.

  2. When prompted to log-in, click Use another account:

image

  1. Click Sign-in options:

image

  1. Click Sign in to an organization

image

  1. Enter the domain name of the organization you want to sign in to and click Next:

image

(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)

  1. Finally, select or log-in to your account:

image

User will be redirected back to the app.