Intel® Trace Collector 8.1 Reference Guide
itcpin [<ITC options>] -- <application command line>
<ITC options> - see itcpin Utility Options
<command line> - command and (when running it) its options
The itcpin utility program manipulates a binary executable file while it runs. It can:
insert an Intel® Trace Collector library into the binary as if the executable had been linked against it
automatically initialize the Intel® Trace Collector library, if necessary
record function entry and exit events, thus allowing more detailed analysis of the user code in an application
Without further options itcpin will just analyze the executable given in the command line to ensure that it can be instrumented and how. With the --list option it will print a list of all functions found inside the executable to stdout. The format of this list is the same as the one used for the STATE configuration option and its ON/OFF flag indicates whether tracing of a function is enabled or not. --list can be combined with options that specify a configuration to test their effect without actually running the executable. One relevant options is --debug, which groups functions by the source file that contains them. The top-level group is always the binary file containing the function, leading to function names of the format: <basename binary file>:<basename source file>:<function name>
C++ names are demangled automatically if --demangle is specified. In this case their methods are grouped according to the class hierarchy by default instead of using the normal file oriented grouping. When --filter is used, then the filter script is passed all available information and can decide itself which grouping it wants to use.
The function list generated that way is limited to the main executable and those dynamic libraries which are already loaded during startup. Functions in libraries which are opened dynamically during the normal execution of the application will not be found this way.
The executable is run only if the --run option is given. Unless instructed otherwise, itcpin will insert libVT if it finds that the main executable references MPI calls. In all other cases it is necessary to choose which library to insert with the --insert option.
The installation path of Intel® Trace Collector must be the same on all nodes (see section Installation) to ensure that it can find the necessary binaries at run-time.
Invoking itcpin on the executable as described in the previous section will print a list of all available libraries with a short description of each one. The Intel® Trace Collector documentation also has a full list of all available libraries in the System Requirements and Supported Features section. libVTcs is the one used for ordinary function tracing.
If you want to do MPI tracing and MPI was linked statically into the binary, then it is necessary to point itcpin towards a shared version of a matching MPI library with --mpi.
Choosing which tracing library to insert and the right MPI library is useful, but not required when just using --list: if given, then itcpin will hide functions that are internal to those libraries and thus cannot be traced.
The optional function profiling is enabled with the --profile flag. This records the entry and exit for functions in the trace file. Limiting the number of recorded functions is recommended to avoid excessive runtime overhead and reduce the amount of trace data. This can be done with one or more of the following options: --state, --activity, --symbol, --config. Alternatively, you can use folding to prune the amount of recorded trace data dynamically at runtime; see the section Tracing Library Calls in the Intel® Trace Collector documentation for details.
You must initialize Intel® Trace Collector libraries before you can use them. In MPI tracing libraries this is done implicitly when MPI_Init() is called, so inserting the library is enough. For the other libraries there are two possibilities:
The application may contain calls to VT_initialize() and (for libVTcs) VT_clientinit()/VT_serverinit(). To get the application linked libVTnull can be used. During binary instrumentation all API calls will be redirected into the actual Intel® Trace Collector library. This is also useful when tracing MPI applications, for example to store additional data in the trace file.
If the application contains no call to VT_initialize(), then itcpin will call VT_initialize() as soon as the Intel® Trace Collector library gets inserted.
It is quite common that MPI applications are started by scripts. It is possible to invoke itcpin on the startup script or program loader. itcpin will then monitor this initial loader and all commands started by it until it finds the main executable.
When inserting an MPI tracing library (regardless whether it was selected explicitly through --insert or not) then the first executable which contains MPI calls is treated as the main executable. If the main executable contains no MPI calls because all of them were moved to a shared library which is only going to be loaded later, then this heuristic fails.
In that case and when inserting other Intel® Trace Collector libraries, the --executable command line option can be used to specify which executable is to be instrumented.
The Microsoft* Windows* version of itcpin has some limitations against Linux* one. Unless the binary to be instrumented comes with a .pdb symbol file (that is, has been built with debug information), itcpin does not see the symbols inside the main binary and thus cannot detect whether it is an MPI application. In this situation the user has to specify explicitly which Intel® Trace Collector library should be inserted (through --insert). There is another difference to Linux: the name of the MPI dll the application is linked to has to be specified, either through --mpi or through the environment variable VT_MPI_DLL. The latter is already done in the itacvars script, therefore no special action is needed if the application is linked to the standard MPI dll and itacvars has been executed. When running under itcpin, it is important that the environment variables VT_DLL_DIR and VT_MPI_DLL are set on all MPI processes. Depending on your MPI, this might require special flags for mpiexec (for example, mpiexec -env). For Intel® MPI Library, as an example, after executing the mpivars and itacvars scripts, the startup command might look like
mpiexec -hosts ... -wdir ... -genv VT_DLL_DIR "%VT_DLL_DIR%"
-genv VT_MPI_DLL "%VT_MPI_DLL%" itcpin --run -- my_app.exe
To use itcpin on Microsoft Windows OS, you have to disable the McAfee Host Intrusion Prevention* antivirus software.