dotTrace SDK: An API for Your Performance Needs!

Hadi Hariri

UPDATE: This blog post is dedicated to dotTrace  version 5 which is now outdated. For the information about the latest dotTrace profiling API refer to the documentation.

As of version 5 of dotTrace Performance we started shipping as part of the package, an SDK which allowed us to programmatically make use of dotTrace Performance engine. We are excited to announce that we are now offering this as its own standalone product, with its own installer, and available for free. Download it here.

Making performance snapshots child’s play

Performance issues generally are a pain. They usually only appear in production and are hard to pinpoint and even worse to reproduce. When performance issues arise, the first step is to run analysis on the application to try and find the bottlenecks, and this isn’t always easy in production. To begin with, we need to interact with the machine where the application is running. With dotTrace Performance we’ve made this somewhat easier by allowing remote profiling. Secondly however, we need to have some knowledge to collect this information, in other words, know how to work with dotTrace Performance. This usually means a member of the support team or developer. Not the customer.

Wouldn’t it be great however if this weren’t necessary? Imagine if we could just instruct the program to profile itself. Well that is what the SDK is bringing to the table, and more!

Scenarios

Let’s take a look at some of the scenarios that the SDK enables.

Self-Profiling

As mentioned previously, one of the great advantages of the SDK is to allow an application to profile itself and gather performance metrics. In ReSharper 7 we are already making use of this functionality. When you install ReSharper, you will notice a new menu entry under Help menu:

When we execute this option, the dotTrace performance engine kicks in and attaches itself to the running process. It then starts to gather information about everything that is going on in the application. Once enough information has been gathered, it creates a snapshot file that can be analyzed by dotTrace Performance and more importantly, it can be detached from the process. As we know, running an application under a profiler has a performance penalty so it is fundamental to only do it for the minimum time required.

By default, when invoking this functionality, the dotTrace Controller pops up:

However, this functionality can be customized to one’s own needs, so we can in fact have something that blends in more with our application and we also have access to events that allow us to intercept the snapshot and do what we want with it.

Application-Centric Profiling: Profiler API

When analyzing performance snapshots, we usually focus on our own application code and ignore system code such as the BCL calls or libraries and frameworks that we cannot necessarily do anything about. With some applications this is easy to accomplish as dotTrace Performance grays out irrelevant code and allows us to focus on our own. However with certain types of applications, it’s not always straightforward as it’s hard to often distinguish entry points from the users perspective.

The SDK now allows us to indicate where we want to focus our performance analysis by allowing us to define entry points. For instance, in an ASP.NET WebForm application, we can add the following code to the Application_Start event:

This means that if we’re running under dotTrace Performance (in other words profiling the application), to start monitoring our code. We can then indicate where we want to stop monitoring also:

and thus allowing the focus to stay within the bounds of the code we are interested in. Notice how we do not have to make explicit calls to the profiler. We just indicate when we want to start and when we want to finish.

By doing this, we can now activate the Use Profiler API checkbox in dotTrace Performance

and thus removing all irrelevant infrastructure code that we are not interested in from the analysis.

On-Demand Profiling

Although not a scenario as such, the ability to pause and resume performance, gives us the ability to provide on-demand profiling in our applications. We can have SDK calls in the code and activate them on demand.

Getting Started: Show me the code

Once we download and install the SDK, the application folder where it is installed contains 4 folders:

The Doc contains the documentation for the API classes which we’ll examine briefly in a moment. The Lib folder is the two assemblies that are referenced in applications that use the SDK. An important folder is the Redist. This contains a redistributable copy of the dotTrace Performance engine which should be shipped with your application if you’re using the Self-Attach functionality. Finally Samples provides two documented samples of how to work with the SDK in the scenarios depicted previously. One of them is the VSTool Visual Studio self-profiling add-in and the other is an ASP.NET WebForms application.

The SDK itself has a small surface area, with only a few classes. Namely the important ones include:

• ProfilingControl: Class to control the starting, stopping, pausing, attaching and detaching of the profiler to the application. We need this class in order to use the Use Profiler API option in dotTrace. An example usage of this is the ASP.NET WebForms sample that ships with the SDK.
• SelfAttach: Class to allow self-profiling. Covered in the VS add-on sample that ships with the SDK.

When using the SelfAttach class, we can indicate how we want the behavior to be once a snapshot has been taken. We can opt on opening the snapshot file, saving it or have it processed by a third party assembly. Each of these options have their own settings and are defined by different classes:

• OpenProfilingConfig: Open the snapshot once completed
• SaveProfilingConfig: Save the snapshot once completed
• ProcessSnapshotProfilingConfig: Process the snapshot once completed

We pass as constructor to argument to SelfAttach an instance of one of these classes. The VSTool demo shows example usages of all three.

An important option among the configuration classes is the ProfilerControlKind property which indicates how the profiling process is controller. The default option (as described above in the Self-Profiling) is to use the dotTrace Controller window. Alternatives are None or using the API.

Summary

This is the first big release of the SDK and based on the feedback we receive we want to improve it and make it more versatile, so we appreciate any and all comments. As mentioned the SDK is freely available. You do not need to own a license of dotTrace Performance to distribute it. You do however of course need dotTrace to analyze the results. The point is though to make it simple and cheap for you to include this functionality inside your applications

You can download the SDK from here.

Enjoy and please give us any feedback.

Subscribe to a monthly digest curated from the .NET Tools blog:

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!