In Part 1 of this series on HTTP Request Throttling, we discussed how to retrieve and modify existing monitors. It's now time to see how you can add your own monitors to the Request Throttling and Monitoring system. As an example, we'll assume that you'd like to add a monitor for CPU percentage to the list of out-of-the-box monitors.
You may be accustomed to the typical way of adding a new instance to a collection of similar instances in the .NET Framework. In PowerShell, this would manifest as calling New-Object to create and then set properties on the new instance, then calling .Add(…) on the collection object and passing the new instance as a parameter. If you are accustomed to this paradigm, you'll be a bit disappointed to know that adding a performance monitor to the Request Throttling system works differently.
Add a new performance monitor to be monitored
In the Request Throttling system, you call .AddPerformanceMonitor on the SPHttpThrottleSettings object to specify details of a new counter to be monitored, specifying the Category (i.e. Object), Counter, and Instance for the Performance Monitor along with the ranges of values for health score calculation (i.e. the buckets). For example, assuming you had captured a reference to a SPHttpThrottleSettings object in $throttleSettings (as we did in Part 1), you'd use the following line to add a new monitor for CPU percentage:
$throttleSettings.AddPerformanceMonitor( "Processor", "% Processor Time", "_Total", @( 20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0, 90.0, 95.0, 98.0 ), $true )
With that one simple line, we've added a new monitor. The first string represents the category (or object) for the counter, the second represents the specific counter to monitor, and the third string is the instance of that counter to consider. (N.B. There is a second overload for this method which allows you to specify the "current process" as the instance, which will cause the exact identity of the current running process to be determined at runtime.) The array of numbers are the delimiters for the 11 buckets into which the current value will fall and based on which the health score will be calculated. The final Boolean parameter ($true) tells the system that the numbers go up in value, and thus values below the first number belong in bucket 0 (for example). If the numbers went down in value (as in, say, the Available MBs counter, where higher values are more healthy), this final paramater would be $false.
To verify that our new monitor has been added, call Get-SPWebApplicationHttpThrottlingMonitor "http://domain:port" (sorry for leaving the cmdlet off in my previous post). You will see your new counter listed along with the other ones.
Now you may recall me mentioning in part 1 that it's possible to use custom Health Score Calculators other than the default buckets-based one. To do so, you'd need to temporarily create a buckets-based monitor, then modify the AssociatedHealthScoreCalculator property on the newly added PerformanceMonitor to point to your own implementation of SPHealthScoreCalculator (see the SDK or contact me for further help with this).
You have several options if you'd like to remove this or other performance monitors. You can call .RemovePerformanceMonitor, specifying the Category, Counter, and Instance for the monitor you'd like to remove:
$throttleSettings.RemovePerformanceMonitor( "Processor", "% Processor Time", "_Total" )
You could call .Clear and remove all performance monitors, which you might do in situations where you want to start from scratch and don't want to use the OOTB monitors:
And finally, you can call the static .ResetToDefaultSettings method, which resets all settings (including the refresh interval, throttling enablement, et al), to their defaults:
[Microsoft.SharePoint.Utilities.SPHttpThrottleSettings]::ResetToDefaultSettings( $(Get-SPWebApplication http://server:port) )
You can verify settings by calling Get-SPWebApplicationHttpThrottlingMonitor "http://domain:port" and (Get-SPWebApplication "http://domain:port").HttpThrottleSettings.
In the final post in this series we'll talk about Throttling stages, Throttle Classifiers, and how you can add your own.