At my current client we have implemented various operational tools to manage suspended queues, cleaning up dead messages, monitoring states and throttling. We had created a lot of these utilities to achieve functionality that could either not be produced easily through the standard BizTalk 2004 interface, the functionality provided was not enough to meet our requirements or there was some necessity to implement some automation.
A lot of these operational utilities were developed as either services or scheduled tasks using an appropriate scheduling mechanism such as SQL Jobs or Windows Scheduled Tasks. Some investigation had taken place into MOM, but at the time the 2000 version that was reviewed was not going to be deployed within the company.
During our current development using BizTalk 2006 we have had the opportunity to investigate the use of MOM 2005 as part of the overall solution. This has obviously lead to some initial review of whether it can be used to provide the operational utilities that were previously developed in a more accessible manner, along with any improvements in development time.
This leads me on to the purpose of this blog posting. One of the operational utilities that is offered as part of the service I am implementing on BizTalk 2006 is the ability to throttle Receive Locations. There is a requirement stating that if a publisher is submitting messages at such a rate whereby the BizTalk Group cannot handle the load, then an automated mechanism of disabling and enabling the Receive Location should exist.
For example, you have determined that the hardware and configuration of your BizTalk Group can handle scenarios where the host queue associated to that Receive Location is backing up to approximately 100 instances. You may want to throttle the Receive Location when the queue gets above this threshold so that the whole BizTalk Group does not sustain sufficient strain to cause itself problems.
At this point it may be worthwhile noting that you can actually throttle BizTalk at various levels from within the BizTalk Administration Console as shown in the figures below
Figure 1 - Host Throttling Properties
Figure 2 – Throttling Thresholds
The standard throttling may be more applicable to your own requirements - although it does not provide quite the flexibility of your own implementation - and in any event would also be the fall back mechanism for the solution discussed in this post. Also, please note that any figures discussed here are purely for demonstration purposes only, they are not realistic.
Anyway, with BizTalk 2006 you now have a number of extra performance counters that can be extremely useful. One of these is the Host Queue Length as shown below
Figure 3 – Host Queue Length Performance Counter
Before this was exposed in BizTalk 2006 you probably wrote stored procedures that returned you the queue lengths that you were interested and called these from your operational utilities. Fortunately you do not need to be concerned with this anymore and as they are exposed as performance counters we can employ them within a MOM 2005 utility.
As discussed above, we wish to throttle a specific Receive Location when it hits a certain threshold. What does this entail? Well, standard throttling means that when an observed figure goes above the threshold for a specific item then the item is disabled until a time at which the observed figure goes below another threshold. These are referred to as High and Low Watermarks.
So what we need to do is identify when the Host Queue counter shown above gets above the High Watermark and disabled a specified Receive Location. Then, once BizTalk has managed to process some of the backlog and the Host Queue counter resumes to a level below a Low Watermark then re-enable the Receive Location. This will be achieved using Performance Rules in MOM 2005 that fire Response scripts when the watermarks are met.
Firstly, we create a Rule Group in MOM 2005 that will group these rules (and any other you may deem appropriate) together. Within the MOM 2005 Administrator Console, we navigate to the Management Packs Rule Groups node, right-click and select Create Rule Group. You will then be presented with a screen similar to that shown below. Just enter some appropriate information.
Figure 4 – New Rule Group Properties
A generic Knowledge Base screen will appear that allows you to enter useful related information as part of your company’s Knowledge Base, just skip that screen for the moment by clicking Finish. You will then be prompted whether you wish to deploy to a group of computers.
Figure 5 – Rule Deployment Prompt
You then need to select the Computer Group that you wish to deploy to if you have one set-up or do this at a later date. For further information on Computer Groups, please refer to your MOM 2005 documentation. You should now have a newly created Rule Group as shown in the following figure
Figure 6 – MOM 2005 Administrator
We are creating Performance Rules, so navigate to the Performance Rules node within the newly created Rule Group, right-click and select Create Performance Rule. You will then be prompted to select a type of Performance Rule. As we wish to execute scripts based upon a threshold being met, select the Compare Performance Data (Threshold) option.
The next screen is trying to obtain what Provider to use. We need a new Windows NT Performance Counter Provider for the Host Queue counter we identified earlier. Click on the New button to create this provider and then use the dialog box that opens to choose this performance counter. At this point you need to browse to the Computer that contains the BizTalk 2006 installation and select the Host Queue performance counter much in the same manner as if you were using Performance Monitor, as shown in the figure below.
Figure 7 – Windows Performance Counter Provider Properties
Notice that we simply use the <All> hosts selection, which will return the queue depth for all the hosts in the BizTalk Group. We also use a sample rate of every 5 seconds and simply stick with the default naming. As mentioned previously, these figures and selections are simply used for demonstration purposes and can be altered to your requirements.
Now we have set-up this Windows Performance Counter Provider we want to set the threshold at which our script will execute. Back on the original dialog box we simply scroll through all the selections leaving them default until the Threshold Rule Properties – Threshold dialog. At this point we are defining the Performance Rule to use for disabling a Receive Location, so we will enter a High Watermark value in this dialog box. This is shown below:
Figure 8 – Threshold Rule Properties
Notice that we are using the “greater than the following value” option and specifying 100. This will mean that the script we wish to fire will do so once the Host Queue value exceeds 100.
The next screen in the wizard allows you to define an alert to raise when this criteria has been met. Once again, this all depends on your own particular requirements, but I would have this on at the very least during development and testing, as it assists in debugging any issues you may experience.
Figure 9 – Threshold Alert Properties
Scroll through the Alert Supression screen leaving the default alert suppression so that you do not receive unnecessary alerts and then you arrive at the Responses dialog box. This is where you define the response to this Performance Rule being met and where we wish to execute our script to disable the Receive Location.
Choose Add Launch a Script and you will be prompted with the Launch a Script dialog box. You may select an existing script you have created from here or define a new one. We will be entering a new one for this demonstration, so click the New button. You will be asked to enter a name and description for the script and then select the Language that the script is written in.
Figure 10 – General Script Properties
Enter some appropriate information, make sure the VBScript language is selected and click Next. You will then be shown an area where you may enter your script.
Now, I have been quite impressed with MOM 2005, but this is one of the areas that certainly need improvement. Not only does this dialog box not resize, but there are none of the User Interface improvements that you are used to in products such as Visual Studio. So you are left working with a bog standard text box. Not the most exhilarating experience that’s for sure. I tend to write the script elsewhere and debug as much as possible using cscript and then port it for MOM 2005 and paste into this teeny box.
The script you need to paste here is shown below. Note that this is still a Proof of Concept at this stage and I do need expect to be held liable if it affects your system in any way! By the time you have read this it may have changed already (a prime example is to add multiple Receive Locations), so simply use it as a basis for understanding the conceptual points I am trying to discuss.
'--------------------------------------------------------------------------
'
' WMI script to disable the specified Receive Location. The Receive Location
' to disable is specified by name as an argument passed to the script.
'
'--------------------------------------------------------------------------
' History:
'
' (03-Jan-2006 Matt Hall) - Created
'
'--------------------------------------------------------------------------
' Explicit declaration of variables
Option Explicit
' Event Constant definitions
Const EVENT_TYPE_SUCCESS = 0
Const EVENT_TYPE_ERROR = 1
Const EVENT_TYPE_WARNING = 2
Const EVENT_TYPE_INFORMATION = 4
Const EVENT_TYPE_AUDITSUCCESS = 8
Const EVENT_TYPE_AUDITFAILURE = 16
' VarSet Constants
Const RECEIVE_LOCATION_CHECKER_NAME = "Receive Loc Checker"
Const RECEIVE_LOCATION_CHECKER_STATE = "Receive Loc Checker State"
' Receive Location Checker States
Const RECEIVE_LOCATION_ENABLED = 1
Const RECEIVE_LOCATION_DISABLED = 0
' Retrieve the DebugMode parameter to determine whether we want to be in debug mode
Dim blnDebugMode : blnDebugMode = CBool(GetParam("DebugMode"))
' Start processing
If GetReceiveLocationState = RECEIVE_LOCATION_ENABLED Then
If blnDebugMode = true Then
CreateDebugEvent("GetReceiveLocationState returned true")
End If
Call DisableReceiveLocation()
SetReceiveLocationState(RECEIVE_LOCATION_DISABLED)
Else
If blnDebugMode = true Then
CreateDebugEvent("GetReceiveLocationState returned false")
End If
End If
'--------------------------------------------------------------------------
'
' Subroutine that disables the specified Receive Location
'
'--------------------------------------------------------------------------
Sub DisableReceiveLocation()
' If we are in debug mode then create an event to indicate we have entered the DisableReceiveLocation sub routine
If blnDebugMode = true Then
CreateDebugEvent("DisableReceiveLocation Start")
End If
' Get the Receive Location name that was passed
Dim strReceiveLocationName : strReceiveLocationName = GetParam("RecLoc")
' Build a query to retrieve the WMI object containing this Receive Location
Dim strQuery : strQuery = "SELECT * FROM MSBTS_ReceiveLocation WHERE Name =""" & strReceiveLocationName & """"
Dim objRecLocs : Set objRecLocs = GetObject("Winmgmts:!root\MicrosoftBizTalkServer").ExecQuery(strQuery)
' If we are in debug mode then create an event to display the receive location information
If blnDebugMode = true Then
CreateDebugEvent("strReceiveLocationName = " & strReceiveLocationName & ", strQuery = " & strQuery & ", objRecLocs.Count = " & cStr(objRecLocs.Count))
End If
' If a Receive Location was found matching the specified name then disable it
If objRecLocs.Count > 0 then
Dim objRecLoc
For Each objRecLoc in objRecLocs
objRecLoc.Disable
Next
' Otherwise a Receive Location was not found matching that name, so output this to the ScriptContext
Else
CreateEvent 100, EVENT_TYPE_INFORMATION, "DisableReceiveLocationScript", "A Receive Location was not found matching the name equal to " & strReceiveLocationName
End If
Set objRecLocs = Nothing
End Sub
'--------------------------------------------------------------------------
'
' Function that returns the specified parameter value from the ScriptContext
'
'--------------------------------------------------------------------------
Function GetParam(strParamName)
Dim objParameters : Set objParameters = ScriptContext.Parameters
Dim vntVariable : vntVariable = objParameters.get(strParamName)
Set objParameters = Nothing
GetParam = vntVariable
End Function
'--------------------------------------------------------------------------
'
' Subroutine that submits an event to the ScriptContext
'
'--------------------------------------------------------------------------
Sub CreateEvent(intEventNumber, intEventType, strEventSource, strEventMessage)
Dim objEvent : Set objEvent = ScriptContext.CreateEvent()
objEvent.EventSource = strEventSource
objEvent.EventNumber = intEventNumber
objEvent.EventType = intEventType
objEvent.Message = strEventMessage
ScriptContext.Submit objEvent
Set objEvent = Nothing
End Sub
'--------------------------------------------------------------------------
'
' Subroutine that takes a string and submits an appropriate event to the
' ScriptContext for debugging output
'
'--------------------------------------------------------------------------
Sub CreateDebugEvent(strDebugOutput)
' Note that we prefix the message even though this appears in the Source of the event as it makes it easier to
' read when viewing the log
CreateEvent 100, EVENT_TYPE_INFORMATION, "DisableReceiveLocationScript Debug", "DisableReceiveLocationScript: " & strDebugOutput
End Sub
'--------------------------------------------------------------------------
'
' Function that returns the state of the Receive Location we are checking
'
'--------------------------------------------------------------------------
Function GetReceiveLocationState()
' Debug output showing function has started
If blnDebugMode = true Then
CreateDebugEvent("GetReceiveLocationState Started")
End If
' Return the string to use for the name of the VarSet
Dim strReceiveLocCheckName : strReceiveLocCheckName = ReceiveLocationCheckerNameByMachine
' Debug output showing the VarSet name we will be using
If blnDebugMode = true Then
CreateDebugEvent("strReceiveLocCheckName = " & strReceiveLocCheckName)
End If
' Obtain the ScriptState
Dim objScriptState : Set objScriptState = ScriptContext.GetScriptState()
' Obtain the VarSet containing the state value we require
Dim objRecLocCheckerVarSet : Set objRecLocCheckerVarSet = objScriptState.GetSet(strReceiveLocCheckName)
' Obtain the state value
Dim vntRecLocCheckerState : vntRecLocCheckerState = objRecLocCheckerVarSet.get(RECEIVE_LOCATION_CHECKER_STATE)
' Debug output showing the state value
If blnDebugMode = true Then
CreateDebugEvent("vntRecLocCheckerState returned " & CStr(vntRecLocCheckerState))
End If
' Release resources
Set objScriptState = Nothing
Set objRecLocCheckerVarSet = Nothing
' Return state value
GetReceiveLocationState = vntRecLocCheckerState
End Function
'--------------------------------------------------------------------------
'
' Sub routine that sets the Receive Location state in the ScriptContext so
' we can query this value between both the disable and enable scripts. This
' allows us to determine the state of the Receive Location without having
' to undertake any unnecessary processing.
'
'--------------------------------------------------------------------------
Sub SetReceiveLocationState(intReceiveLocationState)
' Debug output showing sub procedure has started
If blnDebugMode = true Then
CreateDebugEvent("SetReceiveLocationState Started")
End If
' Return the string to use for the name of the VarSet
Dim strReceiveLocCheckName : strReceiveLocCheckName = ReceiveLocationCheckerNameByMachine
' Debug output showing the VarSet name we will be using
If blnDebugMode = true Then
CreateDebugEvent("strReceiveLocCheckName = " & strReceiveLocCheckName)
End If
' Obtain the ScriptState
Dim objScriptState : Set objScriptState = ScriptContext.GetScriptState()
' Obtain the Receive Location Checker VarSet
Dim objRecLocCheckerVarSet : Set objRecLocCheckerVarSet = objScriptState.GetSet(strReceiveLocCheckName)
' Save variable changes back to the VarSet
Call objRecLocCheckerVarSet.put(RECEIVE_LOCATION_CHECKER_STATE, intReceiveLocationState)
' Save the VarSet
Call objScriptState.SaveSet(strReceiveLocCheckName, objRecLocCheckerVarSet)
' Release resources
Set objScriptState = Nothing
Set objRecLocCheckerVarSet = Nothing
End Sub
'--------------------------------------------------------------------------
'
' Function that returns the Receive Location Checker Name value to use for
' storing the VarSet. We add the Target Computer so we know which BizTalk
' Server in the Group we are executing the script against. We also use the
' Receive Location name that was passed as a parameter to this script so the
' script can be executed against multiple Receive Locations if required.
'
'--------------------------------------------------------------------------
Function ReceiveLocationCheckerNameByMachine()
ReceiveLocationCheckerNameByMachine = RECEIVE_LOCATION_CHECKER_NAME + "#" + ScriptContext.TargetComputer + "#" + GetParam("RecLoc")
End Function
This script accepts a couple of parameters. The first of which is defining which Receive Location we are to be disabling, which is the unique name of the Receive Location. The second is simply a Debug parameter that I use in order to be able to output debug information to the MOM Alerts. If the debug parameter is set to true then the alerts are shown, otherwise they are not.
From the Script Properties – Parameters screen, click the Add button to add these two parameters to the script.
Figure 10 – Script Parameters to Add
Note that the names of these parameters must match those shown above, as they are referenced in the script. The value you enter is simply the default value to use and can be overridden by any Rule Responses that employ the script.
Click the Finish button and continue through the Rule definition dialog boxes using the default options until you reach the end where you must give it a name and save.
The above process has given you a quick walkthrough of how to set-up a Performance Rule that executes a script based upon a defined BizTalk 2006 Host Queue threshold. You must now add another rule that re-enables the Receive Location at a specified Low Watermark in the same manner as that which you have just created, using the script below.
Once you have added this rule you may deploy the rules to the BizTalk server you wish to test this on and then conduct some testing. For my test I simply flooded as many messages as I could into a File Receive Location that simply routed the messages to a folder on the same server. The results are shown in the following figure
Figure 11 – Performance Monitor Results
The white line shows the Host Queue length and you can observe the throttling in action by the peaks and troughs displayed. Obviously you can configure this to be more effective for your requirements and you can change the rate at which the Enable Receive Location checks so there is less time between the bursts of activity. But this post has simply been used as an introduction of what can be achieved with BizTalk 2006 and MOM 2005. I hope you have found it useful.
'--------------------------------------------------------------------------
'
' WMI script to enable the specified Receive Location. The Receive Location
' to enable is specified by name as an argument passed to the script.
'
'--------------------------------------------------------------------------
' History:
'
' (03-Jan-2006 Matt Hall) - Created
'
'--------------------------------------------------------------------------
' Explicit declaration of variables
Option Explicit
' Event Constant definitions
Const EVENT_TYPE_SUCCESS = 0
Const EVENT_TYPE_ERROR = 1
Const EVENT_TYPE_WARNING = 2
Const EVENT_TYPE_INFORMATION = 4
Const EVENT_TYPE_AUDITSUCCESS = 8
Const EVENT_TYPE_AUDITFAILURE = 16
' VarSet Constants
Const RECEIVE_LOCATION_CHECKER_NAME = "Receive Loc Checker"
Const RECEIVE_LOCATION_CHECKER_STATE = "Receive Loc Checker State"
' Receive Location Checker States
Const RECEIVE_LOCATION_ENABLED = 1
Const RECEIVE_LOCATION_DISABLED = 0
' Retrieve the DebugMode parameter to determine whether we want to be in debug mode
Dim blnDebugMode : blnDebugMode = CBool(GetParam("DebugMode"))
' Start processing
If GetReceiveLocationState = RECEIVE_LOCATION_DISABLED Then
If blnDebugMode = true Then
CreateDebugEvent("GetReceiveLocationState returned true")
End If
Call EnableReceiveLocation()
SetReceiveLocationState(RECEIVE_LOCATION_ENABLED)
Else
If blnDebugMode = true Then
CreateDebugEvent("GetReceiveLocationState returned false")
End If
End If
'--------------------------------------------------------------------------
'
' Subroutine that enables the specified Receive Location
'
'--------------------------------------------------------------------------
Sub EnableReceiveLocation()
' If we are in debug mode then create an event to indicate we have entered the EnableReceiveLocation sub routine
If blnDebugMode = true Then
CreateDebugEvent("EnableReceiveLocation Start")
End If
' Get the Receive Location name that was passed
Dim strReceiveLocationName : strReceiveLocationName = GetParam("RecLoc")
' Build a query to retrieve the WMI object containing this Receive Location
Dim strQuery : strQuery = "SELECT * FROM MSBTS_ReceiveLocation WHERE Name =""" & strReceiveLocationName & """"
Dim objRecLocs : Set objRecLocs = GetObject("Winmgmts:!root\MicrosoftBizTalkServer").ExecQuery(strQuery)
' If we are in debug mode then create an event to display the receive location information
If blnDebugMode = true Then
CreateDebugEvent("strReceiveLocationName = " & strReceiveLocationName & ", strQuery = " & strQuery & ", objRecLocs.Count = " & cStr(objRecLocs.Count))
End If
' If a Receive Location was found matching the specified name then enable it
If objRecLocs.Count > 0 then
Dim objRecLoc
For Each objRecLoc in objRecLocs
objRecLoc.Enable
Next
' Otherwise a Receive Location was not found matching that name, so output this to the ScriptContext
Else
CreateEvent 100, EVENT_TYPE_INFORMATION, "EnableReceiveLocationScript", "A Receive Location was not found matching the name equal to " & strReceiveLocationName
End If
Set objRecLocs = Nothing
End Sub
'--------------------------------------------------------------------------
'
' Function that returns the specified parameter value from the ScriptContext
'
'--------------------------------------------------------------------------
Function GetParam(strParamName)
Dim objParameters : Set objParameters = ScriptContext.Parameters
Dim vntVariable : vntVariable = objParameters.get(strParamName)
Set objParameters = Nothing
GetParam = vntVariable
End Function
'--------------------------------------------------------------------------
'
' Subroutine that submits an event to the ScriptContext
'
'--------------------------------------------------------------------------
Sub CreateEvent(intEventNumber, intEventType, strEventSource, strEventMessage)
Dim objEvent : Set objEvent = ScriptContext.CreateEvent()
objEvent.EventSource = strEventSource
objEvent.EventNumber = intEventNumber
objEvent.EventType = intEventType
objEvent.Message = strEventMessage
ScriptContext.Submit objEvent
Set objEvent = Nothing
End Sub
'--------------------------------------------------------------------------
'
' Subroutine that takes a string and submits an appropriate event to the
' ScriptContext for debugging output
'
'--------------------------------------------------------------------------
Sub CreateDebugEvent(strDebugOutput)
' Note that we prefix the message even though this appears in the Source of the event as it makes it easier to
' read when viewing the log
CreateEvent 100, EVENT_TYPE_INFORMATION, "EnableReceiveLocationScript Debug", "EnableReceiveLocationScript: " & strDebugOutput
End Sub
'--------------------------------------------------------------------------
'
' Function that returns the state of the Receive Location we are checking
'
'--------------------------------------------------------------------------
Function GetReceiveLocationState()
' Debug output showing function has started
If blnDebugMode = true Then
CreateDebugEvent("GetReceiveLocationState Started")
End If
' Return the string to use for the name of the VarSet
Dim strReceiveLocCheckName : strReceiveLocCheckName = ReceiveLocationCheckerNameByMachine
' Debug output showing the VarSet name we will be using
If blnDebugMode = true Then
CreateDebugEvent("strReceiveLocCheckName = " & strReceiveLocCheckName)
End If
' Obtain the ScriptState
Dim objScriptState : Set objScriptState = ScriptContext.GetScriptState()
' Obtain the VarSet containing the state value we require
Dim objRecLocCheckerVarSet : Set objRecLocCheckerVarSet = objScriptState.GetSet(strReceiveLocCheckName)
' Obtain the state value
Dim vntRecLocCheckerState : vntRecLocCheckerState = objRecLocCheckerVarSet.get(RECEIVE_LOCATION_CHECKER_STATE)
' Debug output showing the state value
If blnDebugMode = true Then
CreateDebugEvent("vntRecLocCheckerState returned " & CStr(vntRecLocCheckerState))
End If
' Release resources
Set objScriptState = Nothing
Set objRecLocCheckerVarSet = Nothing
' Return state value
GetReceiveLocationState = vntRecLocCheckerState
End Function
'--------------------------------------------------------------------------
'
' Sub routine that sets the Receive Location state in the ScriptContext so
' we can query this value between both the disable and enable scripts. This
' allows us to determine the state of the Receive Location without having
' to undertake any unnecessary processing.
'
'--------------------------------------------------------------------------
Sub SetReceiveLocationState(intReceiveLocationState)
' Debug output showing sub procedure has started
If blnDebugMode = true Then
CreateDebugEvent("SetReceiveLocationState Started")
End If
' Return the string to use for the name of the VarSet
Dim strReceiveLocCheckName : strReceiveLocCheckName = ReceiveLocationCheckerNameByMachine
' Debug output showing the VarSet name we will be using
If blnDebugMode = true Then
CreateDebugEvent("strReceiveLocCheckName = " & strReceiveLocCheckName)
End If
' Obtain the ScriptState
Dim objScriptState : Set objScriptState = ScriptContext.GetScriptState()
' Obtain the Receive Location Checker VarSet
Dim objRecLocCheckerVarSet : Set objRecLocCheckerVarSet = objScriptState.GetSet(strReceiveLocCheckName)
' Save variable changes back to the VarSet
Call objRecLocCheckerVarSet.put(RECEIVE_LOCATION_CHECKER_STATE, intReceiveLocationState)
' Save the VarSet
Call objScriptState.SaveSet(strReceiveLocCheckName, objRecLocCheckerVarSet)
' Release resources
Set objScriptState = Nothing
Set objRecLocCheckerVarSet = Nothing
End Sub
'--------------------------------------------------------------------------
'
' Function that returns the Receive Location Checker Name value to use for
' storing the VarSet. We add the Target Computer so we know which BizTalk
' Server in the Group we are executing the script against. We also use the
' Receive Location name that was passed as a parameter to this script so the
' script can be executed against multiple Receive Locations if required.
'
'--------------------------------------------------------------------------
Function ReceiveLocationCheckerNameByMachine()
ReceiveLocationCheckerNameByMachine = RECEIVE_LOCATION_CHECKER_NAME + "#" + ScriptContext.TargetComputer + "#" + GetParam("RecLoc")
End Function
