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 according to the settings specified in a configuration file.
- Reporter.exe - analyzes a snapshot or compares a pair of snapshots and generates an XML report with performance data.
The tools are also distributed in a separate zip archive* (available for download on the dotTrace page). Note that the tools do not require the dotTrace license key.
In this section:
Profiling Application Using the ConsoleProfiler.exe Tool
1. (Optional) Creating profiling configuration file
Profiling configuration (profiling target, profiling method, and so on) for the ConsoleProfiler.exe tool can be provided in two ways:
If you choose to provide the configuration via the XML file, you can use the Configuration2Xml32.exe (and the 64-bit version Configuration2Xml64.exe) tool to simplify file creation. This tool allows you to create the XML configuration file using the familiar UI 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.
-
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.
2. Running profiling session
After the configuration file is created, you can start profiling.
To profile an application using the command-line tool:
-
Do one of the following:
-
If you provide profiling configuration in an XML file, run the following command
in the command line:
where
ConsoleProfiler.exe <path_to_config> <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 config.xml c:\Snapshots\snapshot.dtp
-
If you choose to provide profiling configuration using the command-line options, run
ConsoleProfiler.exe with the options you need.
For example, to profile some standalone application
App.exe using the sampling profiling type:
To see the full list of available options, run the following command:
ConsoleProfiler.exe /app=c:\MyApp\App.exe /profiling_type=sampling c:\Snapshots\snapshot.dtp
ConsoleProfiler.exe /h
-
If you provide profiling configuration in an XML file, run the following command
in the command line:
After the profiled application finishes working, the ConsoleProfiler.exe tool will automatically save a performance snapshot.
ConsoleProfiler.exe Exit Code
By default, if tool finishes its work successfully, its exit code is 0. This may be not very convenient in some
cases. For example, when you run the tool on the 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 /transparent_exit_code
argument.
ConsoleProfiler.exe config.xml snapshot.dtp /transparent_exit_code
Generating Performance Report 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.
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>Method1</Pattern> <Pattern>Method2</Pattern> </Patterns>
Method1
andMethod2
- names of the methods you want to get the performance data for. - Save the file.
2. Generating a report
To generate a performance report:
-
In the command line, run the following command:
where
Reporter.exe /reporting <path_to_snapshot> <path_to_pattern> <path_to_report> /add_process_info
<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.
</add_process_info>
- (optional) Adds info on the profiled process (path to the executable and command line arguments) to the report. This option is useful when profiling applications with multiple child processes (some unit test runners run tests in a separate child process).
For example:
Reporter.exe /reporting c:\Snapshots\snapshot.dtp pattern.xml c:\Reports\report.xml /add_process_info
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.
To compare two snapshots and generate report on differences:
-
In the command line, run the following command:
where
Reporter.exe /compare <path_to_snapshot1> <path_to_snapshot2> <path_to_pattern> <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.xml 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.