Request Throttling
Applies to: SharePoint Foundation 2010
This topic describes the Microsoft SharePoint Foundation system for throttling HTTP requests when front-end web servers become too busy to handle all the incoming requests.
Overview of Request Throttling
SharePoint Foundation includes a system for monitoring various Windows Server 2008 performance counters and for throttling (that is, blocking) HTTP requests, if any of those counters indicates that a server is too busy to handle all the requests that it is receiving. The monitoring and throttling system can be turned on or off, for a specific SharePoint Foundation web application, in the Central Administration application or by using a PowerShell command in SharePoint Management Shell. The system can be modified through the SharePoint Foundation object model or through cmdlets in SharePoint Management Shell.
Tip
Before you attempt to program against the monitoring and throttling object model of SharePoint Foundation, you should be familiar the Windows Server 2008 system of performance counters and the concepts of category (also known as performance object), counter, and instance. For more information about these things and about creating your own performance counters, see the following topics:
-
Windows Performance Counters and the topics under this node.
-
Introduction to Monitoring Performance Thresholds and the topics under this node.
-
PerformanceCounter
Initialization of the Throttle Control System
The throttle control system is initialized during the BeginRequest event of the first HTTP request to a specific worker process on a specific front-end web server. Subsequent requests to the same process reuse the entities and threads that are initialized in that first request. If the web application is reset, the system is reinitialized with the first request following the reset. The two major steps to the initialization are described in the following subsections.
Creating a Performance Inspector
Each worker process of each web application on each front-end web server has its own performance inspector that is initialized with information from the web application’s HttpThrottleSettings property. The inspector has the following major parts:
A set of health scores, one for each performance counter that is being monitored. The scores are Int32 values from 0 to 10, with 0 being the healthiest possible score and 10 being the least healthy.
An overall health score for the process, which is also an Int32 from 0 to 10.
For each counter that is being monitored, a set of raw performance values that have been read (sampled) from the counter. They are in order from the oldest sample to the most recent.
A server status inspection thread that is used to sample the counter values periodically.
A refresh interval setting that determines how frequently the counters are resampled. The default is 5 seconds.
Launching the Server Status Inspection Thread
The server status inspection thread is created when the inspector is created. It loops through the following steps at an interval specified by the inspector’s refresh interval.
Gets the SPHttpThrottleSettings object in the web application’s HttpThrottleSettings property. (This object may have changed since the last loop; for example, the refresh interval may have been changed or an additional performance counter may have been added to the list of those being monitored.)
Verifies that request throttling has not been turned off since the last loop.
Sets the refresh interval of the inspector with the value from SPHttpThrottleSettings.RefreshInterval.
Calls the GenerateMonitors() method. This method creates an SPSystemPerformanceCounterMonitor object for each performance counter that has to be monitored. Information about which of the server’s counters have to be monitored is provided by a persisted set of SPPerformanceMonitorCreationData objects. There is one of these for every counter that has to be monitored. Each of these creation data objects has a critical child SPHealthScoreCalculator object. This object can translate a performance counter value into a health score from 0 to 10. (It can also take the result of a mathematical function of multiple performance values and translate it into a health score.)
Each monitor samples the latest value from the counter that it monitors and stores that value in the inspector’s set of raw performance values for the corresponding counter.
Each monitor updates the health score for the counter that it monitors. This step has the following substeps:
Sample values that are too old to be relevant are removed from the set of raw performance values. Only the most recent n values are preserved, where n is the value of the HttpThrottleSettings.NumberOfSamples property.
A mathematical function is applied to the remaining values to produce a weighted average of the values. The more recent the value, the higher it is weighted.
The monitor uses its health score calculator to calculate a health score from 0 to 10 for the weighted average.
The overall health score for the worker process is set to the highest (least healthy) score from among the scores of the individual monitors.
The throttle level is set in keeping with the following rules:
If the overall health score for the process is less than 10, there is no need to throttle requests, so the throttle level is set to Normal.
If the overall health score is 10 (the highest possible and the least healthy score), but it has been at 10 for less than 60 seconds, the throttle level is set to FirstStage. This means that certain categories of HTTP requests are blocked and the client is sent an HTTP 503 error ("Service unavailable"). This throttle affects only requests assigned to the same worker process. For information about how the system determines which categories of requests are blocked and how it decides which category a given request belongs to, see Determining Whether to Block a Request later in this topic.
If the overall health score is 10 and has been 10 for at least 60 seconds, the throttle level is set to SecondStage. This means that additional categories of requests are blocked.
The inspection thread waits for the duration of the refresh interval and then repeats.
Note
If the throttling level is at FirstStage or SecondStage, throttling continues for the worker process until its overall health score is reset to a value below 10 on some cycle of the inspection thread.
Determining Whether to Block a Request
If the monitoring and throttling system is turned on for a specified web application, the determination of whether a given HTTP request is blocked occurs during the PostResolveRequestCache event of the request. Specifically, the following steps are executed:
The HTTP response object is initialized and a header that contains the overall health score of the worker process is added to it.
The throttle level for the process is checked to determine whether it is either FirstStage or SecondStage. If it is not either, the process is not in throttle mode, and the remaining steps are skipped.
If the process is in throttle mode, the request is tested by each of the throttle classifiers of the web application. Throttle classifiers are persisted objects that are stored in the HttpThrottleSettings.ThrottleClassifiers property. In effect, each throttle classifier is a definition of a category of HTTP request. You can use any combination of characteristics of HTTP requests to define a category, including the file name extension of the requested resource, the values of certain headers, the user agent, and the HTTP method (for example, "GET" or "POST"). The classifier has a ThrottleLevel property that specifies whether requests that belong to the category are throttled in FirstStage, SecondStage, or not at all. The request is blocked, or not, according to the following rules:
If the worker process has throttle level FirstStage, all requests in categories with throttle level FirstStage, and requests that do not belong to any of the defined categories, are blocked.
If the worker process has throttle level SecondStage, requests in categories with throttle level SecondStage are also blocked, in addition to those that are blocked when the worker process has a throttle level of FirstStage.
Note
Because requests that do not match any classifier are blocked in FirstStage throttling mode, you must programmatically create a classifier object for any kind of request that you do not want to be blocked until the second stage and construct the object with a ThrottleLevel of SecondStage. Similarly, if a kind of request should never be blocked, you must construct a classifier object with ThrottleLevel of Never. For more information about classifier objects, see Request Classifiers later in this topic.
An HTTP 503 error is sent to the client of any blocked request.
Note
If a request belongs to more than one category, and the categories do not all have the same throttle level, it is throttled in accordance with the most stringently throttled category. For example, if a request belongs to a category that is throttled at the FirstStage level but also to a category that is throttled only if the SecondStage is reached, it will be throttled at the first stage.
Registered Performance Counters
When SharePoint Foundation is first installed, some performance counters may be automatically registered with the initial "SharePoint – 80" web application for tracking by the monitor and throttling system. You can add or remove counters from the system either programmatically or by using a cmdlet in SharePoint Management Shell. To get a list of the registered counters for any given web application, use the following cmdlet in SharePoint Management Shell.
Get-SPWebApplicationHttpThrottlingMonitor –identity http://<Web application URL>
The following table is a typical list of counters that a SharePoint Foundation administrator might want to monitor for a web application.
Performance Category |
Counter |
Instance Name, If More Than One |
|---|---|---|
Memory |
Available Mbytes |
This counter has only one instance. |
ASP.NET |
Requests Queued |
This counter has only one instance. |
ASP.NET |
Request Wait Time |
This counter has only one instance. |
Processor |
Interrupts/sec |
_Total |
For information about how to register or deregister a performance counter for a web application programmatically, see How to: Register or Deregister a Performance Counter.
Request Classifiers
An HTTP request classifier is an object of a class that is derived from SPRequestThrottleClassifier. These objects persist in the configuration database as the value of the HttpThrottleSettings.ThrottleClassifiers property. There are some SPRequestThrottleClassifier-derived classes in the object model. The properties of these classes are read-only, so you cannot change an existing request classifier object, but you can add new classifier objects with different property values to the store and then remove old classifier objects. The classes are sealed; but you can create new objects of each of the classes, and you can derive your own classifier classes from SPRequestThrottleClassifier. The following table shows the classes and the kind of request category each of them can be used to define. Also shown is the default throttle level at which matching requests are throttled unless a different level is specified when the classifier object is created.
Type |
Category |
Default Throttle Level |
|---|---|---|
Requests for resources with a specified file name extension |
||
Requests that contain a specified header |
||
Requests that have a specified user agent or that use a specified HTTP method |
||
Requests that come from search crawlers |
Note
The system default for requests that do not match any classifier is to block them in first stage, so you must specifically create a classifier object that has a throttle level of Never for any requests that should be exempted from throttling.
For more information about programmatically registering and deregistering request classifier objects, see How to: Create and Register or Deregister a Request Classifier. For information about creating a new category of classifier, see How to: Create a New Request Classifier.
Health Score Calculators
A health score calculator turns a raw value from a performance counter (or the result of some function applied to multiple raw values) into a health score from 0 to 10, with 0 representing the healthiest possible state of the counter and 10 representing the least healthy. A calculator is an object of a class derived from SPHealthScoreCalculator. There is one such class already in the object model: SPBucketHealthScoreCalculator. An object of this class divides the range of possible values of a counter into subranges, called "buckets." The object has a CalculateScore(Double) method that assigns a health score to a value based on the bucket into which the value falls. Only values in the least healthy bucket are given the least healthy score of 10.
The buckets—that is, the subrange boundaries—are defined when the SPBucketHealthScoreCalculator object is constructed and can be changed by using the SetScoreBuckets([]) method.
Important
When you are defining the buckets to be passed to a SPBucketHealthScoreCalculator object, consider the following:
-
It is hard-coded into SharePoint Foundation to throttle requests only when the weighted average of at least one of the counters that is being monitored gets the worst possible score, 10.
-
The SPBucketHealthScoreCalculator is sealed, and its CalculateScore(Double) assigns a 10 only to scores in the least healthy bucket.
Therefore, if it is essential that throttling be turned on when the weighted average of a given counter reaches a certain value, be sure that you define the buckets so that that value falls into the least healthy bucket.
If you want a bucket-style calculator whose CalculateScore(Double) method behaves differently, or if you need a health score calculator that does not use a bucket system at all, derive a new class from SPHealthScoreCalculator, and implement the CalculateScore(Double) method as needed.
A health score calculator object is persisted in the configuration database as a property of a SPPerformanceMonitorCreationData object.
For more information about creating health score calculators and assigning them to monitor creation data objects, see How to: Create, Modify, and Change a Bucket-Style Health-Score Calculator.
See Also
Tasks
How to: Change the Settings for the Request Throttling System
How to: Register or Deregister a Performance Counter
How to: Create and Register or Deregister a Request Classifier
How to: Create, Modify, and Change a Bucket-Style Health-Score Calculator