Intel® Trace Analyzer and Collector User and Reference Guide

ID 767272
Date 3/31/2023
Document Table of Contents

Configuring the Collector

When using Intel® Trace Collector, you may want to customize various aspects of collector's operation and define filters for data tracing. It is achieved through setting up the appropriate configuration options.

You can set up these options in three ways:

  • In a configuration file.

  • In the corresponding environment variables.

  • In the command line when running your application.

For the list of options and their descriptions, see Configuration Options.

Using Configuration File

Intel Trace Collector configuration file is a plain ASCII file that contains a number of directives in each line and has the .conf extension.

For your convenience, Intel Trace Collector provides a utility called Configuration Assistant intended for creating and editing configuration files. However, you can create the configuration file manually using a text editor. For examples and details on syntax, see Configuration Reference.

To run the Configuration Assistant, enter the command:

$ itcconfig <trace_file> [<configuration_file>]
Configuration Assistant requires a trace file to be passed, therefore you should first trace your application without any settings to use the utility.

If you do not specify the configuration file, the default settings will be used. Edit the file and save it with the .conf extension.

To apply the settings, do the following:

  1. Set up the VT_CONFIG environment variable to point to the full path to your configuration file. For example:

    $ export VT_CONFIG=/<configuration_file_directory>/my_settings.conf
  2. Set up the VT_CONFIG_RANK environment variable to point to the process that reads and parses the configuration file (the default value is 0).

  3. Trace your application as described in Tracing MPI Applications.

Using Environment Variables

Each option has an equivalent environment variable. To set the variables, use the option names, but prefix them with VT_ and replace hyphens with underscores. For the SYMBOL, STATE and ACTIVITY options you can also list multiple values in one variable (see Filtering Trace Data for details). For example:

$ export VT_STATE=* OFF MPI:* ON
Environment variables are checked by the process that reads the configuration file after it has parsed the file, so the variables override the configuration file options.

Using Command-Line Options

To specify configuration options in the command line, at runtime use a string of the following syntax as an argument to your application:

--itc-args --<configuration_option> <value> --itc-args-end

For example, to generate a trace file of the SINGLESTF format:

$ mpirun -n 4 ./MyApp --itc-args --logfile-format SINGLESTF --itc-args-end
Fortran programs are an exception, because Intel Trace Collector has limited access to command line parameters of Fortran programs.

Protocol File

After tracing your application, a protocol file .prot is created. The file lists all configuration options with their values used when your application was traced, and other useful information. You can use the protocol file of a particular run as a configuration file to trace the application with the same settings again. See Protocol File for details.