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:
get a memory snapshot:
MemoryProfiler.GetSnapshot(),enable or disable collecting memory allocation data:
MemoryProfiler.CollectAllocations(bool enable),and even force garbage collection:
MemoryProfiler.ForceGc(),
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 dotMemory 2018.3 and earlier used another version of the profiling API (for the details on this API, refer to the dotMemory 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 Control profiling via 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
MemoryProfilerstatic class.To get a memory snapshot and save it to the disk, call
MemoryProfiler.GetSnapshot()– an equivalent to pressing the Get Snapshot button in the profiling controller.To enable/disable collecting memory allocation data, call
CollectAllocations(bool enable)– an equivalent to pressing the Collect Allocations button.To check whether a
CollectAllocations(bool enable)call will have effect, useMemoryProfiler.GetFeatures(). Note that this check is not obligatory.
To use the API for profiling a specific part of the code
Reference the
JetBrains.Profiler.APINuGet package in your project.Insert calls to methods of the
MemoryProfilerclass into your code as required by your use case. For example:private void SomeMethod() { // Enable collecting memory allocation data MemoryProfiler.CollectAllocations(true); ...// Here goes some code that I want to profile // Get a snapshot MemoryProfiler.GetSnapshot(); }Start profiling the application from dotMemory, and select the Control profiling via API option in the profiler options.
Self-profiled applications
As the name suggests, in this scenario, an application profiles itself. 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 dotMemory 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
SelfAttachclass 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
BaseSnapshotProfilingConfigBaseProfilingConfigclasses) passed to theAttachmethod:SaveSnapshotProfilingConfig– the resulting snapshot is saved in the designated folder.ExecutableSnapshotProfilingConfig– the resulting snapshot is saved in the designated or default folder, the path to the snapshot is passed to an external application as a command line parameter.
The resulting self-profiling snapshot has the
.dmwfile extension.
To use the API in self-profiled applications
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.
Reference the
JetBrains.Profiler.Windows.SelfApiassembly from the JetBrains.Profiler.Windows.SelfApi.dll file located in the main directory of the SDK.Supply your app with the SDK redistributables.
Initiate self-profiling somewhere in your app using the
SelfAttachclass. For example:SelfAttach.Attach(new SaveSnapshotProfilingConfig() { ProfilingControlKind = ProfilingControlKind.Api, SaveDir = "C:\\Temp", RedistDir = "C:\\ProfilerSDK", ProfilingType = ProfilingType.Memory, ListFile = "C:\\snapshot_list.xml" // the file is created automatically during profiling });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
SelfAttachAPI requires some time to start):// wait until API starts while (SelfAttach.State != SelfApiState.Active) Thread.Sleep(250); MemoryProfiler.CollectAllocations(true); ... // Here goes some code that I want to profile MemoryProfiler.GetSnapshot();