Control Profiling Session with API

Last modified: 10 November 2021

Profiling a specific part of the code

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

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. *
note
* 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.

Self-profiled applications

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

Control Profiling Session with API﻿

Profiling a specific part of the code﻿

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

note

Self-profiled applications﻿

To add self-profiling to an application﻿

See also

Reference

Control Profiling Session with API

Profiling a specific part of the code

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

Self-profiled applications

To add self-profiling to an application