Working with dotTrace Command-Line Profiler
Sometimes it is necessary to automate the process of gathering performance snapshots, for example, if you want to make profiling a part of your continuous integration builds (e.g., this can be a build step that performs profiling of your integration tests). For this purpose, dotTrace comes bundled with a couple of command-line tools (located in the dotTrace installation directory):
ConsoleProfiler.exe: profiles applications and takes performance snapshots.
Reporter.exe: analyzes a snapshot or compares a pair of snapshots and generates an XML report with performance data.
The tools are also distributed as a separate zip archive* and as a NuGet package. Note that the tools are free of charge and do not require any license keys.
Profiling applications using the ConsoleProfiler.exe tool
To profile an application using the command-line tool
-
Depending on your profiling scenario, run ConsoleProfiler.exe with the options you need. For example:
To run and profile a standalone application App.exe using the Timeline profiling type:
ConsoleProfiler.exe start --save-to=c:\Snapshots\snapshot.dtp --profiling-type=Timeline c:\MyApp\App.exe
To run and profile a standalone application App.exe (using the default Sampling profiling type) and control the session using the profiling API:
ConsoleProfiler.exe start --save-to=c:\Snapshots\snapshot.dtp c:\MyApp\App.exe --use-api
To attach to a running application with
PID=1234
and profile it using the sampling profiling type:ConsoleProfiler.exe attach --save-to=c:\Snapshots\snapshot.dtp
To see the full list of available options, run the tool without any arguments:
ConsoleProfiler.exe
After the profiled application finishes working, the ConsoleProfiler.exe tool will automatically save a performance snapshot.
ConsoleProfiler.exe exit code
By default, if the tool finishes its work successfully, its exit code is 0
. This may be inconvenient in some cases. For example, if you run the tool on a CI server, you may need to get the exit code of the profiled application (e.g., a unit test runner). To make ConsoleProfiler.exe return the exit code of the profiling target, use the --propagate-exit-code
argument.
For example:
ConsoleProfiler.exe start --save-to=c:\Snapshots\snapshot.dtp
--profiling-type=Sampling c:\MyApp\App.exe --propagate-exit-code
(Optional) Configuring profiling using an XML file
In the section above, we have provided the profiling configuration (profiling target, profiling method, and so on) as the ConsoleProfiler.exe arguments. If for some reason, you do not want to configure a session this way, you can provide the configuration in an XML file.
To simplify file creation, you can use the Configuration2Xml32.exe (and the 64-bit version Configuration2Xml64.exe) tool. This tool allows you to create the XML configuration file using the familiar user interface of the dotTrace Home window.
To create or modify a configuration file using Configuration2Xml
Run the Configuration2Xml32.exe or Configuration2Xml64.exe tool which is located in the dotTrace installation directory (by default, C:\Users\[username]\AppData\Local\JetBrains\Installations\dotTrace[N]).
To create a new profiling configuration, select the
menu.
To modify an existing profiling configuration, select .Specify profiling options as you normally do in the dotTrace Home window.
Click Save and specify the file name and path for the configuration file.
Click Save.
To run the profiling session configured via an XML file
-
Run the following command in the command line:
whereConsoleProfiler.exe xmlfile <path_to_config> --save-to=<path_to_snapshot>
<path_to_config>
- path to the XML configuration file.
<path_to_snapshot>
- path to the resulting snapshot file. Note that you can specify either the full path (including the snapshot file name) or only the path to the directory (without the file name). In the latter case, the snapshot file will get a random name.For example:
ConsoleProfiler.exe xmlfile config.xml --save-to=c:\Snapshots\snapshot.dtp
Generating performance reports using the Reporter.exe tool
The Reporter.exe tool can work in two modes:
Getting performance data for particular methods.
The resulting XML report gets data on execution time and number of calls for particular methods.Comparing snapshots.
The resulting XML report gets data on differences in execution time and number of calls for particular methods. This mode can be especially useful for comparing performance data you get in a latest build against some reference snapshot.
Regardless of the mode you choose, you should specify method names that should be added to the report.
1. Specifying methods for the report
The list of methods that must be added into a report is defined by an XML pattern file.
To create a pattern file
In an editor of your choice, create a blank XML file.
-
Write the list of methods that must be added to the report as shown in the example below.
where<Patterns> <Pattern PrintCallstacks = "MethodNameOnly">Method1</Pattern> <Pattern>Method2</Pattern> </Patterns>
Method1
andMethod2
- a regular expression that matches names (not substrings of names) of the methods you want to get the performance data for. Note that if a method name contains special characters, you should escape them with the backslash\
symbol. For example,MyMethod\+MySubMethod
.-
PrintCallstacks
- optional attribute that allows including call stack data in reports (an example of such a report is shown below). There are two available values forPrintCallstacks
:Full
- fully qualified method names will be shown in the call stack.MethodNameOnly
- only method names (without namespace and class names) will be shown in the call stack.
Save the file.
2a. Generating a performance report
To generate a performance report
In the command line, run the following command:
whereReporter.exe report <path_to_snapshot> --pattern=<path_to_pattern> --save-to=<path_to_report>
<path_to_snapshot>
- path to the source snapshot file.
<path_to_pattern>
- path to the XML pattern file which contains names of the methods added to the report.
<path_to_report>
- path to the resulting report file.
For example:
Reporter.exe report c:\Snapshots\snapshot.dtp --pattern=pattern.xml --save-to=c:\Reports\report.xml
Report Example
<Report>
<Info>
<Snapshot IndexFile="C:\snapshot1.dtp" Executable="C:\Temp\ConsoleAppTest.exe"
CommandLine="C:\Temp\ConsoleAppTest.exe" />
</Info>
<Function FQN="Tests.Method1" TotalTime="500" OwnTime="100" Calls="1" />
<Function FQN="Tests.Method2" TotalTime="400" OwnTime="200" Calls="10" />
</Report>
where
FQN
- full method name.
TotalTime
- execution time of the method's call subtree.
OwnTime
- method's own execution time.
Calls
- number of calls.
If a PrintCallstacks
attribute was specified for a particular Pattern
in an XML pattern file, the report will contain additional call stack data. For example, <Pattern PrintCallstacks = "MethodNameOnly">
was specified for some GetFileNames
function. In this case, the corresponding Function
node in the resulting report will contain an additional Instance
subnode with a call stack:
<Function Id="0x0020000C" FQN="MyApplication.MainWindow.GetFileNames" TotalTime="12520" OwnTime="0" Calls="1740" Instances="1">
<Instance CallStack="Main/Run/Run/RunInternal/RunDispatcher/PushFrame/PushFrameImpl/OnClick/RaiseEvent/RaiseEventImpl/InvokeHandlersImpl/InvokeHandler/btnSelectFiles_Click/GetFileNames" TotalTime="12520" OwnTime="0" Calls="1740" />
</Function>
2b. Generating a report on snapshots differences
To compare two snapshots and generate report on differences
In the command line, run the following command:
whereReporter.exe compare <path_to_snapshot1> <path_to_snapshot2> --pattern=<path_to_pattern> --save-to=<path_to_report>
<path_to_snapshot1>
- path to the reference snapshot file.
<path_to_snapshot2>
- path to the second snapshot file.
<path_to_pattern>
- path to the XML pattern file which contains names of the methods added to the report.
<path_to_report>
- path to the resulting report file.
For example:
Reporter.exe compare c:\Snapshots\base_snapshot.dtp c:\Snapshots\snapshot.dtp
--pattern=pattern.xml --save-to=c:\Reports\report.xml
The resulting report file is similar to the one you get in the "reporting" mode with the only difference: all fields will contain not the absolute time or number of calls values but their delta between the snapshots. Depending on the delta sign, the values will start with either +
or -
prefix.