Control Profiling Session with API

The profiling API provides a number of classes which allow you to control the profiling process. For example, right from the code of your application, you can:

start collecting profiling data: MeasureProfiler.StartCollectingData(),
stop collecting the data: MeasureProfiler.StopCollectingData(),
save the data to the disk: MeasureProfiler.SaveData(),
and more.

For the detailed information about the API classes, refer to API Reference.

There are two main scenarios that require using the profiling API:

Profiling a specific part of the code
Self-profiled applications.

Profile a specific part of the code

The API allows you to narrow the analysis scope and profile only the code you are interested in. For example, sometimes, it is not that easy to click the Get Snapshot button at the right moment. With the profiling API, you can do a "get a snapshot" call at an exact point of your code.

Note that dotTrace 2018.3 and earlier used another version of the profiling API (for more information about this API, refer to the dotTrace 2018.3 documentation). This API is still supported but we strongly recommend that you use the latest API version described in this section.

Main concepts:

The source code of the API is available on GitHub. The code is distributed under Apache license.
The profiling API is distributed as a JetBrains.Profiler.API NuGet package which you should reference in your project.
To enable the API, you must start a profiling session with the enabled How to control profiling | Using API parameter in the profiler options.
When using the API, the only difference comparing to a normal profiling session is in how you control the session: instead of clicking the buttons in the profiling controller, you call the corresponding API methods.
If you run your application with no profiling, the calls to the API methods will be ignored. The API will not throw any errors.
The main class you should use to control a profiling session is the MeasureProfiler static class.
To start collecting profiling data, call MeasureProfiler.StartCollectingData(). This is equivalent to pressing the Start button in the profiling controller.
To stop collecting the data and save them to the disk, call MeasureProfiler.SaveData() – an equivalent to pressing the Get Snapshot and Wait button.
To drop the data without saving, call MeasureProfiler.DropData() – an equivalent to pressing the Drop button.
To stop collecting profiling data without saving them to the disk, call MeasureProfiler.StopCollectingData(). Typically, you do not need to use this method. Note that this method is not applicable to the Timeline profiling type and will be ignored by the profiler.
On Windows, the Timeline profiling requires the ETW service to be run in the background. To start this service, administrator rights are required. For this reason, each time you start a profiling session, dotTrace prompts you for rights elevation. To avoid this, run the service manually using the <dotTrace_installation_directory>\x64\JetBrains.ETW.Collector.Host.exe file. Another option is to install the service using the <dotTrace_installation_directory>\Msi.x64\EtwService.msi installation file. In this case, the service will be run on Windows startup.
On macOS and Linux, the Timeline profiling doesn't require any external services.

To use the API for profiling a specific part of the code

Reference the JetBrains.Profiler.API NuGet package in your project.
Insert calls to methods of the MeasureProfiler class into your code as required by your use case. For example:
private void SomeMethod() { MeasureProfiler.StartCollectingData(); ... // Here goes some code that I want to profile MeasureProfiler.SaveData(); }
Start profiling the application from within dotTrace, JetBrains Rider, or Visual Studio, and select the How to control profiling | Using API parameter in the profiler options. *
* If you need to profile a unit test that contains API calls, you should only use standalone dotTrace for profiling. Profiling of such a test from Visual Studio or JetBrains Rider is not possible. See the detailed instructions.

Create self-profiled applications

As the name suggests, in this scenario, an application profiles itself. The main difference compared to the previous scenario is in how you initiate profiling. If you profile a specific part of the code using the profiling API, you initiate a session manually (for example, using the dotTrace UI). In the case of a self-profiled application, the session is initiated right from the application code.

Main concepts:

The self-profiling API is a separate JetBrains.Profiler.SelfApi NuGet package that you should reference in your project.
To control the profiling session, the API uses the dotTrace command-line tool.
The command-line tool is not a part of the package. When you initialize the API using the DotTrace.EnsurePrerequisite() method, the API downloads the latest version of the JetBrains.dotTrace.CommandLineTools NuGet package (Windows, Linux, macOS).
By default, the tool from the package is saved to the %LOCALAPPDATA%\JetBrains\Profiler folder. To specify another location, use the downloadTo argument of the DotTrace.EnsurePrerequisite() method.
If the package with the tool already exists, the new one is not downloaded.
To configure a profiling session, for example, specify the path for saved snapshots, you must use an instance of the DotTrace.Config class.
To start a profiling session, you should attach the profiler to the application process by calling the DotTrace.Attach() method. If you have a profiling configuration (an instance of DotTrace.Config), you should specify it as an argument: DotTrace.Attach(config)
DotTrace.Attach() does not start collecting profiling data. To do this, you should call the DotTrace.StartCollectingData() method.
As the self-profiling API attaches to the process, it has limitations on the available profiling types. By default, the API uses the Sampling profiling type. Alternatively, you can use the Timeline profiling type. To do this, you should use the UseTimelineProfilingType() method of the DotTrace.Config class.
To get a performance snapshot, call the DotTrace.SaveData() method. The snapshot will be saved to the directory specified in DotTrace.Config. If there is no profiling configuration, the snapshot will be saved to the application working directory.
Note that after you call DotTrace.SaveData(), the profiler stops collecting data. To start collecting data again, you should call DotTrace.StartCollectingData() one more time.
To finish the profiling session, call the DotTrace.Detach() method.
You can use the self-profiling API simultaneously with the profiling API.

To add self-profiling to an application

Reference the JetBrains.Profiler.SelfApi NuGet package in your project.
Initialize the self-profiling API by calling the DotTrace.EnsurePrerequisite() method. Note that the first initialization may take some time as the API needs to download the dotTrace command-line tool. If you want to track the downloading process and have the ability to cancel it, use the DotTrace.EnsurePrerequisitesAsync() method directly. It lets you use CancellationToken and track progress using a callback variable.
Add API calls as required by your use case:
- If you need only one snapshot:
  static void Main(string[] args) { ... // here goes some init code // initialize the API and download the tool (if needed) DotTrace.EnsurePrerequisite(); // config that sets the save directory var config = new DotTrace.Config(); config.SaveToDir("C:\\Temp\\Snapshot"); // start profiling session DotTrace.Attach(config); // start collecting data DotTrace.StartCollectingData(); SomeMethod(); // end session DotTrace.Detach(); } private void SomeMethod() { ... // here goes some code that I want to profile // get a snapshot and save it DotTrace.SaveData(); }
- If you need more than one snapshot:
  static void Main(string[] args) { ... // here goes some init code // initialize the API and download the tool (if needed) DotTrace.EnsurePrerequisite(); // config that sets the save directory var config = new DotTrace.Config(); config.SaveToDir("C:\\Temp\\Snapshot"); // start profiling session DotTrace.Attach(config); // start collecting data DotTrace.StartCollectingData(); SomeMethod(); // end session DotTrace.Detach(); } private void SomeMethod(IEnumerable<String> collection) { foreach (var item in collection) { ... // here goes some code that I want to profile // get a snapshot and save it DotTrace.SaveData(); // start collecting data again DotTrace.StartCollectingData(); } }

Last modified: 26 May 2024