dotTrace 2019.3 Help

Controlling Profiling Session Through 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

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 the details on 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 Use profiler API option. It is located in the advanced 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 profiling disabled, the calls to the API methods will be simply 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.

  • 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.

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

  1. Reference the JetBrains.Profiler.API NuGet package in your project.

  2. 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(); }

  3. Start profiling the application from within dotTrace, JetBrains Rider, or Visual Studio, and select the Use profiler API checkbox in the profiler options. *

Self-profiled applications

As the name suggests, in this scenario, an application profiles itself. The main difference comparing 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 dotMemory UI). In case of a self-profiled application, the session is initiated right from the application code.

For example, ReSharper uses this API to collect statistics about how it behaves on end-user desktops. When a user faces a performance or memory issue, the support team asks the user to run ReSharper with a special option (it enables the self-profiling feature) and reproduce the issue. The collected snapshot is then sent to the development team.

Main concepts:

  • The self-profiling API is distributed as a zip archive available for download at JetBrains website.

  • The self-profiling API does not support .NET Core applications.

  • End-users do not have dotTrace installed; therefore, you must include dotTrace redistributables into the installation package of your application.

  • As end-users are not supposed to initiate profiling, a self-profiling session is initiated by the API. For this purpose, the API uses the static SelfAttach class located in the JetBrains.Profiler.Windows.SelfApi.dll library.

  • The Attach() method prepares profiling configuration and executes the profiler from the 'redistributables' folder.

  • The profiling configuration is defined by one of two classes (instantiated from the BaseSnapshotProfilingConfig BaseProfilingConfig classes) passed to the Attach method:

    • SaveSnapshotProfilingConfig – the resulting snapshot is saved to the designated folder.

    • ExecutableSnapshotProfilingConfig – the resulting snapshot is saved to the designated or default folder, the path to the snapshot is passed to an external application as a command line parameter.

  • The self-profiling API does not support Tracing and Line by Line profiling types.

To use the API in self-profiled applications

  1. Download and unpack the profiling SDK. If your domain policy is to treat the files downloaded from the Internet as unsafe, unblock the zip archive using the Unblock button in file properties.

  2. Reference the JetBrains.Profiler.Windows.SelfApi assembly from the JetBrains.Profiler.Windows.SelfApi.dll file located in the main directory of the SDK.

  3. Supply your app with the SDK redistributables.

  4. Initiate self-profiling somewhere in your app using the SelfAttach class. For example:

    SelfAttach.Attach(new SaveSnapshotProfilingConfig() { ProfilingControlKind = ProfilingControlKind.Api, SaveDir = "C:\\Temp", RedistDir = "C:\\ProfilerSDK", ProfilingType = ProfilingType.Performance, ListFile = "C:\\snapshot_list.xml" // the file is created automatically during profiling });

  5. Insert calls to the profiling API into your code as required by your use case. If you start profiling right after the self-profiling initialization, add a short wait (the SelfAttach API requires some time to start):

    // wait until API starts while (SelfAttach.State != SelfApiState.Active) Thread.Sleep(250); MeasureProfiler.StartCollectingData(); ... // Here goes some code that I want to profile MeasureProfiler.SaveData();

Last modified: 16 April 2020