Configure Profiling Session

To configure a profiling session, you should:

Specify how dotTrace should run the application you wish to profile. You can do this with the help of run configurations. If you want to profile an already running application, this step is not required.
Specify how dotTrace should profile the application: select a profiling type and (optionally) configure other profiling options, like time measurement type, process filters, and others.

1. Create a run configuration

A run configuration is the way to tell dotTrace how it should run the profiled application. For example, a run configuration of a standalone .NET application will include a path to the application executable, command-line arguments, and a path to the application working directory.

If you already have a run configuration for the profiled application, select this run configuration from the New Process Run under Choose what you want to profile. Otherwise, create the run configuration by following the instruction below.

To create a run configuration

Under Choose what you want to profile, New Process Run, click Add run configuration.
In the New Run Configuration wizard, choose the application type and provide application options:
* Windows only
Click Save. This will create and save the run configuration. Next time when you need to profile this application, select the created configuration from the New Process Run list.

2. Choose profiling type

Choose a profiling type in Profiling Type under Choose how you want to profile it.

The profiling type defines the way of how dotTrace collects profiling data and as a result – the amount and the type of the collected data. The following table will help you choose the best suitable profiling type. For more information, refer to Basics. Profiling Types.

	Description	Use Case
Timeline	Collects temporal data about thread states, application events, and other multi-threading data. On Windows, Timeline profiling is based on Event Tracing for Windows (ETW) and requires running JetBrains ETW Host Service with administrative privileges. On macOS and Linux, external service is not required. Supports native profiling.	Recommended for most cases. Especially for analyzing multithreaded apps. Use it, for example, to determine the cause of UI freezes, excessive garbage collections, uneven workload distribution, insufficient I/O, and so on.
Sampling	Accurate time measurement, number of calls is not measured.	Recommended for most cases. Ideal when you look for performance issues in your app for the first time.
Tracing	Accurate calls count measurement, time measurement may be inaccurate due to profiling overhead.	When sampling data is not enough. For example, for analyzing algorithm complexity (when info about number of calls is more valuable than call time values).
Line-by-line	Windows only. Each line of code is measured, call time values are inaccurate due to huge profiler overhead. To lower the overhead, you can profile only particular methods using filters.	For advanced use cases only. For example, when you already know what function causes issues and want to analyze each line of it.

3. Configure other profiling options

Sampling rate

(Timeline on Windows)

dotTrace takes stack trace data from Windows kernel. By default, the kernel provides 1000 sample events per second. You can increase the sampling rate up to 8000 samples/sec. This makes sense, for example, in game development, when you want to profile fast-executing native code. The higher the sampling rate, the more accurate the results are, but the larger the snapshot is.

Control profiling


Manually (default)	Control the profiling session using the buttons in the profiling controller window. For example, to take a snapshot, you click Get Snapshot and Wait.
Using API	Control profiling directly from the code of the profiled application. For example, to take a snapshot in the exact point of your code, you call the `MeasureProfiler.SaveData()` function. Learn more about using the API in Controlling Profiling Process Through API. Not available for the Timeline profiling type for standalone applications on Linux and macOS.

Manually (default)

Control the profiling session using the buttons in the profiling controller window. For example, to take a snapshot, you click Get Snapshot and Wait.

Using API

Control profiling directly from the code of the profiled application. For example, to take a snapshot in the exact point of your code, you call the MeasureProfiler.SaveData() function. Learn more about using the API in Controlling Profiling Process Through API.

Not available for the Timeline profiling type for standalone applications on Linux and macOS.

Time measurement

(Sampling, Tracing on Windows, Line-by-line)

This option defines how dotTrace must calculate call time. Typically, this is a choice between whether dotTrace should calculate the time when a thread is not working or shouldn't. For more information, refer to Basics. Time Measurement.


Real time (performance counter)	Recommended. dotTrace calculates the overall real time passed between method entry and exit. This time doesn't depend on app threads states. Time is calculated using system performance counter.
Real time (CPU instruction)	dotTrace calculates the overall real time passed between method entry and exit. This time doesn't depend on app threads states. Time is calculated using the CPU register.
Thread time	dotTrace calculates only the time when a certain thread is running. The time when the thread is waiting or sleeping is not included in the calculation.
Thread cycle time	dotTrace calculates only the time when a certain thread is running. The time when the thread is waiting or sleeping is not included in the calculation. Time is calculated using the CPU register.

Enable inlining

(Tracing, Line-by-line)

Clear this option if you want dotTrace to turn off JIT-inlining and get call stacks that closely resemble the structure of the application's source code.

High accuracy

(Tracing, Line-by-line)

If selected, dotTrace will take into account time spent in the profiler itself by taking more time samples.

Enable native profiling

(Timeline, Unity/Mono on Windows)

If selected, dotTrace will collect native call stack data. The resulting snapshot will contain both managed and native call stacks. This profiling option may be helpful for finding performance issues in Unity games.

Collect native allocations

(Timeline on Windows)

If selected, dotTrace will collect information about all memory allocations the profiled application does in the native (unmanaged) heap.

Sample allocations every ... KB defines the size of the allocated memory that will trigger a memory allocation sample. The default value is 100 KB. This means that a sample is triggered once the size of allocated memory exceeds 100 KB in total. For example, a native thread allocates five 50 KB memory blocks during profiling. In such a case, dotTrace will detect only two allocations of 100 KB.
The smaller the size, the more accurate the results are and the larger the snapshot is. Use this option to find the optimal balance between the data accuracy and snapshot size.
If Collect only unreleased allocations is selected, dotTrace will save into the snapshot only data about those allocations that were still in the unmanaged heap at the moment of taking the snapshot.

Collect TPL events

(Timeline)

If selected, profiling performance may be affected, but dotTrace will collect Task Parallel Library (TPL) data. If cleared, there will be no Task nodes in Call Tree and async call nodes will be shown without their await and continuations parts.

Clear this option in case your application does not use multitasking or you do not need this info.

Collect debug output

(Timeline on Windows)

If selected, dotTrace will collect information about all messages the profiled application sends to the debug output.

Download symbol files

(Timeline on Windows)

PDB files (or symbol files) let you see native functions in the call tree. This is relevant for native applications and managed applications that call native code. If you select Download symbol files, dotTrace will try downloading PDB files from remote servers right after you get a snapshot. Note that this may take a significant amount of time depending on file size.

By default, dotTrace looks for PDB files in the locations specified in the _NT_SYMBOL_PATH environment variable. Alternatively, you can specify custom local or remote locations using Edit Symbol File Locations.

If Download in background is enabled, dotTrace starts downloading symbol files while the profiling session is running. This may help to reduce the time of taking a snapshot.

Collect profiling data from start

If selected, dotTrace will start recording profiling data right after the launch. Otherwise, dotTrace will start collecting these data only after you click Start in the profiling controller window.

4. (Optional) Configure process filters

If the profiled application creates a number of processes, use the Process filters setting to specify what processes you want to profile. You can either select a predefined filter or create a new one.

Note that process filters work differently depending on the application type specified in the selected run configuration.

App type	Description
Standalone .NET and .NET Core Mono Unity Unreal Engine	dotTrace will profile only processes that match the specified filter. The filter is applied to the entire process tree of the profiled process (including child processes). For example, you have a managed process that creates a number of child processes. You want to profile not only the main process but also child processes with `service` in their name. To do this, add the `service` include filter.
External .NET Process	In this mode, starting the profiling session doesn't start the profiled process. Instead, dotTrace waits for and attaches to the first managed process started in the operating system. When certain Process filters are selected, dotTrace will attach to the first process that matches the filter. For example, you created the include filter: `service`. dotTrace will attach to the first process in the system with `service` in its name.
IIS IIS Express Windows Service WCF Service WinRT MAUI	Process filters aren't applied.

App type

Description

dotTrace will profile only processes that match the specified filter. The filter is applied to the entire process tree of the profiled process (including child processes).

For example, you have a managed process that creates a number of child processes. You want to profile not only the main process but also child processes with service in their name. To do this, add the *service* include filter.

External .NET Process

In this mode, starting the profiling session doesn't start the profiled process. Instead, dotTrace waits for and attaches to the first managed process started in the operating system. When certain Process filters are selected, dotTrace will attach to the first process that matches the filter.

For example, you created the include filter: *service*. dotTrace will attach to the first process in the system with service in its name.

Process filters aren't applied.

To select a process filter

Under Choose how you want to profile it, Advanced Options, open the Process filters list.
Select the required filter.
dotTrace provides two predefined filters:
- Default: process filter is not applied.
- Entire process tree: dotTrace will profile the entire process tree including child processes. In case a .NET Process run configuration is selected, dotTrace will attach to and profile the first managed process started in the system, including all its child processes.

To create a process filter

Under Choose how you want to profile it, Advanced Options, open the Process filters list.
Choose Add Filter.
Specify filter settings:
- Name: filter name.
- Profile entire process tree: if selected, dotTrace will profile the entire process tree including child processes. Disabling this option makes sense only if you create a filter for the .NET Process run configuration. In this case, dotTrace will wait for and attach to the first process in the system that matches the filter, but it will not profile child processes of this process.
  What does entire process tree mean? Typically, an application has one 'main' process that can create a number of 'child' processes. Nevertheless, in some cases there can be more than one 'main' process. For example, unmanaged processes can create a number of managed 'main' processes which, in turn, can create a number of 'child' processes. dotTrace is able to profile every managed process in such a tree.
- Include filter masks, Exclude filter masks: include and exclude filter masks correspondingly. The masks are applied according to the following rules:
  - The default policy is 'profile all'.
  - Include masks are applied first. Exclude masks are applied to the processes filtered by the include masks.
  - You can use asterisk * wildcards.
  For example, to profile all child processes with Service in their name excluding MyService, add the *Service* include mask and the MyService exclude mask.
Click Save.

5. (Optional) Configure filters for the line-by-line profiling

Line-by-line profiling may be effective in particular cases, but it is always time-consuming. To somehow minimize the profiling overhead, you can define some rules. According to them, not all functions are profiled line by line but only those that are interesting for further investigation.

So you can create and set a filter or filters that match only the functions/classes/assemblies you need.

To create a filter for the line-by-line profiling

Under Choose how you want to profile it, select the Line-by-Line profiling type.
Click Edit Filters.
Click Add filter in the Edit Filter dialog.
Choose a filter type:
- Profile code in: include the specified code item into profiling and exclude all other code items.
- Do not profile code in: exclude the specified code item from profiling.
- Do not profile code marked with attribute: exclude code items with the specified attribute from profiling.
If you've chosen one of the first two options, specify an assembly, a class, and/or a method to be included or excluded from profiling. Code items are filtered independently on one another. For example, if you specify a method and leave asterisks * for assembly and class to exclude methods with the specified name from all assemblies and all classes.
If you've chosen the last option, specify the name of the attribute that will be used to exclude symbols from profiling. Optionally, specify the assembly name where this attribute is declared.
You can use asterisk wildcards when specifying code item names in a filter: * (asterisk) represents zero or more characters. For example, the *.Tests wildcard will exclude all test projects from code analysis.
Click OK.

Last modified: 02 October 2024