Using SPMonitoredScope
Applies to: SharePoint Foundation 2010
In previous releases of Windows SharePoint Services, when an unexplained performance or reliability problem surfaced, it was sometimes difficult to isolate the problem and determine its cause. Often developers would spend a lot of time determining where their failure points and performance bottlenecks were.
Microsoft SharePoint Foundation 2010 introduces the SPMonitoredScope class, to allow developers to designate portions of their code so that they can monitor usage statistics in the Unified Logging Service (ULS) logs and the Developer Dashboard. See Using the Developer Dashboard for more information.
When to Use SPMonitoredScope
A developer can use SPMonitoredScope to:
Identify excessive resource usage.
Identify performance bottlenecks.
Determine how certain component interact with other components.
How to Use SPMonitoredScope
The SPMonitoredScope class resides in the Microsoft.SharePoint.Utilities namespace.
SPMonitoredScope is very easy to use. A developer simply "wraps" the section of code to be monitored. Then, as the code is executed, the measured statistics are written to the ULS logs as well as to the Developer Dashboard. This allows information about the component and the page where it resides to be immediately available to the developer and to the system administrator.
Here is an example of wrapped code.
using (new SPMonitoredScope("My Scope Name"))
{
doSomeWork();
}
Where Calculations are Displayed
When SPMonitoredScope is used in custom code, the statistics are written to the ULS logs and the Developer Dashboard.
Other Uses for SPMonitoredScope
Monitoring other resource usage
SPMonitoredScope can also measure resource usage of other types in a specified section of code.
For example, this code sample measures and logs execution time, number of requests, and the number of SharePoint SQL Server queries (including the query text) that are performed by the external callout.
using (new SPMonitoredScope("My Scope Name"))
new SPRequestUsageCounter(3),
new SPSqlQueryCounter()))
{
callExternalCode();
}
Using performance thresholds
SPMonitoredScope can also be used to dynamically trace only when excessive resource use is detected.
In the example above, the scope is being told that the callExternalCode() method should take no more than 1000ms, and that it should allocate no more than 3 SPRequests. If these limits are exceeded, the trace level for this scope will be increased to "high" for this one instance. The counter will also appear red in the dashboard.
Performance Considerations
Using SPMonitoredScope to wrap code has a very low performance hit. However, it should be noted that if a section of code wrapped by SPMonitoredScope were to contain a loop that performed a high number of iterations (for example, iterating through XML nodes that are returned by a SharePoint Foundation 2010 Web service), the call stack included on the Developer Dashboard could increase in size exponentially, making it difficult to decipher the information displayed.
Best Practices
A tip for the best and most effective use of SPMonitoredScope:
- All calls to external components, such as custom databases, external Web services, and so on, should be wrapped with SPMonitoredScope. This will make it easier for administrators to identify them as points of failure, and to isolate the problem quickly.
Limitations
It should be noted that there are a few limitations for using SPMonitoredScope.
Only calls to SharePoint databases are captured.
Only the code wrapped with SPMonitoredScope that resides on the front-end Web server appears on the Developer Dashboard. Code that executes on application servers only displays the SPMonitoredScope information in the ULS logs of the computer that the code is running on.
SPMonitoredScope cannot be used in sandboxed solutions.