Using the Developer Dashboard in SharePoint 2010

The developer dashboard is a new feature in SharePoint 2010 that is design to provide additional performance and tracing information that can be used to debug and troubleshoot issues with page rendering time. The dashboard is turned off by default, but can be enabled via the object model or stsadm (and PowerShell too, I just haven’t put together the script for it yet). When the dashboard is turned on you will find information about the controls, queries and execution time that occur as part of the page rendering process; this information appears at the bottom of the page. Here’s an example of what the “short” version of the output looks like (NOTE: this screen shot is from a build prior to the public beta so your bits will look a little different):

As you can see, it provides information from the perspective of the event pipeline, the web server and database. On the left side you can see the different events that fired in the page processing pipeline and within that, you can see how long individual web parts took to within those events. On the top right hand side you see information about the page processing as whole, including the overall execution time, the amount of memory used in the processing of the page request and the correlation ID, which can be of great value when trying to link the page render to entries in the ULS log. Underneath the server information you will find a list of the different database calls that were made through the object model by various components in the page itself as well as the controls it hosts – all useful information.

You may also notice the database calls are actually a hyperlink. This is another pretty cool feature in that when you click on it, it shows the call stack from what triggered that particular database call, the SQL that was execute and the IO stats:

Enabling the developer dashboard is fairly easy. If you’re doing it via the object model, the code looks something like this; to turn it on:

SPWebService cs = SPWebService.ContentService;

cs.DeveloperDashboardSettings.DisplayLevel = SPDeveloperDashboardLevel.On;

cs.DeveloperDashboardSettings.Update();

NOTE: This code will not work in a web part if the web part is hosted in any site except the central admin site. We specifically check for and block that scenario because the developer dashboard is a farm-wide setting. If you code it up in a web part and try to execute it in a non-central admin site, it will throw a security exception.

To turn it off you set the DisplayLevel to SPDeveloperDashboard.Off; for on demand use of the dashboard you can set the value to SPDeveloperDashboard.OnDemand. When you set it to OnDemand, it adds a small icon to the upper right hand corner of the page; you click the icon to toggle the dashboard on and off. The icon looks like this:

You can also turn it off and on with stsadm; you just need to make sure you are running the command as a farm administrator:

Stsadm –o setproperty –pn developer-dashboard –pv ondemand (or “on” or “off”)

The on demand setting is really the optimal setting in my opinion. Here’s what it gives you: once it is set to on demand, site collection admins can turn it on or off. When they do, it only turns it on or off for that particular site collection. Equally as good, only the person that turned it on sees the output – your everyday users will not see the output from developer dashboard so this becomes a really valuable troubleshooting tool. Even more interesting is that if you have multiple site collection admins and one of them toggles it on, the output is displayed only for that person, not for every site collection admin. Want more flexibility? Well you can even change the permissions that are required to see the dashboard output. The DeveloperDashboardSettings has a property called RequiredPermissions. You can assign a collection of base permissions (like EditLists, CreateGroups, ManageAlerts, or whatever you want) to it; only those people that have those permissions will be able to see the output. So you have a great deal of flexibility and granularity in deciding when to use it the dashboard output and who will see it.

Okay, so this all seems good – all my web parts and code I run within the page will just show up and we’ll have this great troubleshooting info, right? Well, not exactly unfortunately. Take a look at the output from the dashboard again – you’ll notice a finite set of events that are reported. Those are tied to events in the base web part class so they cannot be expanded for any random click event for example. Any code you have in your override for OnInit or Render will automatically be captured in this pipeline, but code in other places will not. All is not lost however! We’ve also introduced a new class to the object model called the SPMonitoredScope. Among other things, it helps to keep track of useful usage and tracing information just like the developer dashboard uses.

In order to get the rest of your code included in the developer dashboard output, you need to wrap it up in a new monitored scope, with something like this:

using (SPMonitoredScope GetListsBtnScope = new

     SPMonitoredScope("GetListsBtn_Click"))

{

//your code goes here

}

The name I used here – “GetListsBtn_Click” – is what will appear in the developer dashboard output. Here’s an example:

This should be one of your first best practices for developing code for SharePoint 2010 – use SPMonitoredScope! This can only help you understand and manage the performance of your components as you deploy from development to production.

There’s a ton of great out of the box value here, but there is also one piece missing that is worth mentioning. Even if you use SPMonitoredScope, if your code is a sandbox component (i.e. a User Solution), the output from it will not be captured in Developer Dashboard. The reason it doesn’t get captured is that sandbox components execute in a completely different process from the page request – that’s why it’s sandboxed. As a result though, we can’t pipe the tracing information back into the page processing event pipeline. Sorry about that one folks, but we still have a lot of capabilities here that we should be taking advantage of.

I hope after reading this you will see the value in the developer dashboard, understand how to turn it on and off, and know what you have to do to get all of your code to be managed through this pipeline.