This article is applicable to the IBM MQ Built-in (In-App) connector available in Logic Apps Standard. For more information about the connector, please refer to Connect to an IBM MQ server from a workflow in Azure Logic Apps.
In some scenarios, we found that it might be challenging to understand how IBM MQ server needs to be configured to be able to poll without experiencing the dreaded IBM MQ returned Reason Code: 2017 - MQRC_HANDLE_NOT_AVAILABLE.
To summarize, if you experience 2017 - MQRC_HANDLE_NOT_AVAILABLE, it is an indication that the handles that can be requested from the IBM MQ server, on all connections have been exceeded.
In this article, we're going to explain how this works and the math it takes to calculate the max Handles value you should set in your IBM MQ server.
Let's first explain the differences between connections and handles.
Connections and Handles
Generally, a new connection can always be created depending on the IBM MQ server memory limit.
A handle is created every time a queue or a topic is opened. When the queue or topic is closed, the handle will be released. If we're pulling a message from a Queue/Topic, the connector opens the queue, pulls the message and closes the queue. This means, that we will have a handle per message.
The amount of handles required depends on the number of messages in a batch, the scale-out limit, and the type of Receive operation used (Browse-lock or Auto-complete receive, trigger or action). For more information on how to set-up the Browse-Lock Trigger refer to Logic Apps Mission Critical Series: We Speak: IBM MQ (Part 1)
Note:
- Connections are per VM. Logic Apps VMs are per instance.
- Each Logic App instance will have a connection pool, with N connections set.
- Total connections in use = LA instances currently active * N max connections.
Hence, the maximum number of connections should be monitored and adjusted to keep this value in mind. To minimize the disruption during high load period, once the maximum connections in a pool has reached, the IBM MQ connector will begin to create one time use connection instead of throwing an exception that would stop the triggering process. Warning messages will not be shown in the UI, because the process is still running, but should be visible in AppInsights and Function logs.
How does this leave us, regarding the handles?
Handles are not related to the connections. You can still have 10 active connections but not reaching the Handles limit, or you can exhaust it with just one connection. You need to consider that the Handles are limited per Logic App. We suggest using the following formula:
Total possible handles = batch size * (LA instances Max scale out limit or Max Burst) * 2
The Max handles value should be adjusted to accommodate this. This is because the instances can scale out to either the Max burst defined in the App Service Plan, or to the Maximum Scale out limit, if you have it set.
Example values:
A Logic Apps Workflow has batches of 100 messages.
For a possible 5 VMs host with a workflow receive batch of 100 messages, you should set your queue manager Max handle to:
( 5 x 100 x 2) = 1000 handles.
By VM host we're referring to Logic App instances. If there are Always ready Instances, the minimum handles value should be:
Always Ready instances * batch size * 2
Max queue handles value should be calculated with the number of Max burst instances.
Real example:
Logic App standard has 3 always ready instances and App Service Max burst of 20, with no Scale out limit defined. The batch size to pull may be up to 200 messages.
The IBM MQ handles value should be configured to:
Minimum value:
3*200*2 = 1,200 handles
Max possible value:
20*200*2 = 8,000 handles
If increasing the max handles is not possible, then the Logic App instances must be adjusted to respect these limits. Also, consider that a Logic App instance is not the same as a Workflow instance. A Logic App instance is technically a service that has been provisioned to handle your workload. A workflow instance is a workflow Run.
Therefore, you may have one workflow run that takes 200 handles (to browse messages from the queue, for example) or you can have 10 workflow runs that only take one message from the queue, and that would be just 10 handles.
At the end of the day, while the math is simple, it may be confusing. I hope this article helps you understand it better.