Introduction
This blog is introducing past changes of Service Bus SDK for python and several common exception scenarios as well as troubleshooting suggestions.
As more and more developers choose Python when developing Azure Service Bus application, it is necessary to have a clear awareness about the different versions change and current version.
The attractiveness and painfulness of coding is to deal with the exceptions and gain a sense of achievement.
Here we would like to have an introduction about the different versions of Python for Service Bus with common exceptions and sample scenarios to help us understand troubleshooting steps more.
SDK Version Changes
There are three main branches for different versions. With the development of features of Service bus, we rich the python library accordingly. The latest version (as of Jan 2023) of the Azure Service Bus library is version 7. x.x . Please see tables below:
|
|
[Pre-release] |
[Release] |
End Release |
Latest Release |
Maintained Status |
|
0.2x
|
0.20.0rc1 (Aug 25, 2015) |
0.20.0 (Jun 16, 2015) |
0.21.1 (Apr 28, 2017) |
0.21.1 (Apr 28, 2017) |
no longer maintained. |
|
0.50.x |
None |
0.50.0 (Jan 18, 2019) |
0.50.3 (May 21,2020) |
0.50.3 (May 21, 2020) |
no longer maintained. |
|
7.x.x |
7.0.0b1 (Apr 7, 2020)
|
7.0.0 (Nov 24, 2020)
|
None |
7.8.2 (Jan 13, 2023) |
Under maintaining. |
As for the first period of this version 0.2x, this package is initial release of this, it is release as a part of azure python SDK. See the azure package release note for 1.0.0 for details and previous history on Service Bus. This version supports below features:
- Queues: create, list and delete queues; create, list, and delete subscriptions; send, receive, unlock and delete messages
- Topics: create, list, and delete topics; create, list, and delete rules
- Event Hubs: create and delete event hubs; send events.
Several months later the release of 0.2x, we enrich some features and add more advanced interfaces to strength its robustness. As of version 0.50.0 a new AMQP-based API is available for sending and receiving messages. This update involves breaking changes. Please read Migration from 0.21.1 to 0.50.0 .
Breaking changes
- Introducing new AMQP-based API.
- Original HTTP-based API still available under new namespace: azure.servicebus.control_client
- For full API changes, please see updated reference documentation.
Features
- The new API supports message send and receive via AMQP with improved performance and stability.
- New asynchronous APIs (using asyncio) for send, receive and message handling.
- Support for message and session auto lock renewal via background thread or async operation.
- Now supports scheduled message cancellation.
As there came to the next release version (7.x.x), it implemented features and mechanisms for asynchronous highly reliable communication, such as structured first-in-first-out messaging, publish/subscribe capabilities, and the ability to easily scale as your needs grow.
Compared to the previous version (0.50.x), We have a variety of new features in the version 7.x.x of the Service Bus library.
- Ability to create a batch of messages with the smarter ServiceBusSender.create_message_batch() and ServiceBusMessageBatch.add_message() APIs. This will help you manage the messages to be sent in the most optimal way.
- Ability to configure the retry policy used by the operations on the client.
- Ability to connect to the service through http proxy.
- Authentication with AAD credentials using azure-identity.
Please refer to link:
azure-sdk-for-python/migration_guide.md at main · Azure/azure-sdk-for-python · GitHub
In a word, our Service Bus product group continues empower each developer and user to have a better experience and stable usage to interact with service bus.
As everything grows and agile mind goes, our service bus developer raised the latest version python library with implementing the features steps by steps with thinking of all suggestions and feedbacks.
Considering the various users who might use the different versions in different periods, we highly recommend using version 7.x.x for new applications.
As for migrating azure-servicebus to v7 from v0.50, please see guidance:
azure-sdk-for-python/migration_guide.md at main · Azure/azure-sdk-for-python · GitHub
Third Part——Common Exceptions
After having a basic awareness about the Service Bus Python library’s history, I guess you might be eager to try. However, as you could image that there is no perfect world, so same as usage of this library. You might get a kind of exception sometimes.
There is a Chinese slang that “好记性不如烂笔头”, have something written down for past problems and some troubleshooting would benefits us for learning something well in practice.
Please let me have a summary of the common client error exceptions when using this library.
- ServiceBusConnectionError
- ServiceBusAuthorizationError
- MessageSizeExceededError
- MessageAlreadySettled
- MessageLockLostError
- MessagingEntityNotFoundError
- MessagingEntityDisabledError
- ServiceBusQuotaExceededError
ServiceBusConnectionError
Definition:
An error occurred in the connection to the service.
Scenario:
If I try to send/receive message from a certain queue while connecting to service bus via connection string, and the network is aborted suddenly at my client side.
Error in client side:
I could see the traceback error messages that it has retry to send this message and it raise the last retry’s exception error message.
azure.servicebus.exceptions.ServiceBusConnectionError: Unable to open authentication session on connection xxx.
(Default retry count is 3 times, you could check the default value in initialization method.)
If you also open the queue in Azure Poral meanwhile, you could also have received such an error below:
RCA & Suggestions:
This may have been caused by a transient network issue or service problem.
It is recommended to check your client network status and customize retry mechanism when facing an instable network.
ServiceBusAuthorizationError
Definition:
An error occurred when authorizing the connection to the service.
Scenario:
If I am a QA for test sending message to queue, but I am assigned a connection string only with listen permission. Then we I try to send message, and I receive the error exception.
Error in client side:
azure.servicebus.exceptions.ServiceBusAuthorizationError: Unauthorized access. 'Send' claim(s) are required to perform this operation. Resource: 'sb://testforcommonexceptions.servicebus.windows.net/testforexceptions'. TrackingId:9f5326494f78471d99222599e97f4b37_G2, SystemTracker:gateway7, Timestamp:2023-01-15T09:30:25 Error condition: ErrorCodes.UnauthorizedAccess.
RCA & Suggestions:
This may have been caused by the credentials not having the right permission to perform the operation.
It is recommended to check the permission of the credentials.
MessageSizeExceededError
Definition:
This indicates that the message content is larger than the service bus frame size.
Scenario:
I try to read all data in a .txt file (800 KB) and send the data to queue under a basic service bus (256 KB).
Error in client side:
azure.servicebus.exceptions.MessageSizeExceededError: The received message (delivery-id:1126, size:327545 bytes) exceeds the limit (262144 bytes) currently allowed on the link. TrackingId:d693052b-8712-4795-bb0b-492dc16b9c3c_B15, SystemTracker:NoSystemTracker, Timestamp:2023-01-15T10:31:13 Error condition: ErrorCodes.LinkMessageSizeExceeded.
RCA & Suggestions:
This could happen when too many service bus messages are sent in a batch or the content passed into the body of a Message is too large.
It is recommended to reduce the count of messages being sent in a batch or the size of content being passed into a single ServiceBusMessage.
MessageAlreadySettled
Definition:
This indicates failure to settle the message, when you receive message with operations like : complete(), abandon(), deadletter(), defer().
Scenario:
During the receiving process, I add more operations when settling a message, which is duplicated and invalid for settling one message data.
Error in client side:
azure.servicebus.exceptions.MessageAlreadySettled: Unable to complete message; The message has either been deleted or already settled.
RCA & Suggestions:
This could happen when trying to settle an already-settled message.
Please check how you achieve the logic for settling a message.
Refer more details to link:
MessageLockLostError
Definition:
The lock on the message has expired and it has been released back to the queue.
Scenario:
I try to pause for 15s when settling the message, but its Message lock duration is 10 s.
Code part:
Error in client side:
azure.servicebus.exceptions.ServiceBusError: The lock on the message lock has expired.
RCA & Suggestions:
You should be aware of the lock duration of a message and keep renewing the lock before expiration in case of long processing time.
AutoLockRenewer could help with keeping the lock of the message automatically renewed.
MessagingEntityNotFoundError
Definition:
The target service bus entity was not been found when sending message.
Scenario:
My team member deleted our test queue and I have not got this information in time. When I tried to send messages to this deleted queue, I received this kind of exception.
Error in client side:
azure.servicebus.exceptions.ServiceBusAuthenticationError: CBS Token authentication failed.
Status code: 404
Description: The messaging entity 'sb://testforcommonexceptions.servicebus.windows.net/testfordeletedqueue' could not be found. To know more visit https://aka.ms/sbResourceMgrExceptions. TrackingId:624e8fb1-a308-48a7-949d-65fb399376c9_G9, SystemTracker:testforcommonexceptions.servicebus.windows.net:testfordeletedqueue, Timestamp:xxxx
RCA & Suggestions:
Entity associated with the operation doesn't exist or it has been deleted. Please make sure the entity exists.
MessagingEntityDisabledError
Definition:
The queue of service bus is in disabled status, so it does not allow to send message to it.
Scenario:
For some reason, I set the queue send disabled temporarily for test receiving process but have not set it active back. When I try to send a message to this queue, I receive an exception.
Error in client side:
RCA & Suggestions:
Please Activate the entity.
ServiceBusQuotaExceededError:
Definition:
Service bus quota is exceeded when sending messages to service bus entity.
Scenario:
There are messages with 1GB size to max queue quota for basic service bus. And I have not consumed the message to make room and continue send message to this queue.
Error in client side:
azure.servicebus.exceptions.ServiceBusQuotaExceededError: The maximum entity size has been reached or exceeded for Queue: 'TESTFORCOMMONEXCEPTIONS:QUEUE:TESTFORMAXQUEUEQUATOIZE'. Size of entity in bytes:1073801667, Max entity size in bytes: 1073741824. For more information please see https://aka.ms/ServiceBusExceptions . QuotaType: EntitySize Reference:d2b3bc9b-af61-4c0a-bab2-3c90771f9eba, TrackingId:b7c7650000002e8b001263e563c426ff_G13_B28, SystemTracker:testforcommonexceptions:Queue:testformaxqueuequatoize, Timestamp:xxxx Error condition: ErrorCodes.ResourceLimitExceeded.
RCA & Suggestions:
The messaging entity has reached its maximum allowable size, or the maximum number of connections to a namespace has been exceeded.
Create space in the entity by receiving messages from the entity or its subqueues.
Summary
Here we list some common exceptions’ root cause, scenarios and troubleshot suggestions. And there are other kinds of exceptions when using this python library, we just raise a mind to look into problems and hope it could help analyze and resolve the issues efficiently when facing the issue at your side.
Referring to link for get awareness about the other rest common exceptions:
azure-sdk-for-python/README.md at main · Azure/azure-sdk-for-python (github.com)
Thanks for reading. Please leave your comments if you have any questions, we will treat it seriously and return you an answer. Hope everything goes well during your usage and debugging.