Intel® Trace Analyzer and Collector User and Reference Guide

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

stftool Utility Options


Syntax:--convert [<filename>]


Description: Converts the entire file into the file format specified with --logfile-format or the filename suffix. Options that normally select a subset of the trace data are ignored when this low-level conversion is done. Without this flag writing is restricted to ASCII format, while this flag can also be used to copy any kind of STF trace.




Description: Sub-option to --merge. Deletes or removes the given raw trace after merging.




Description: A shortcut for --logfile-name - and --logfile-format ASCII, that is, it prints the trace data to stdout.



Default:off in Intel Trace Collector, on in stftool

Description: Several events can only be stored in STF, but not in VTF. Intel® Trace Collector libraries default to writing valid VTF trace files and thus skip these events. This option enables writing of non-standard VTF records in ASCII mode that Intel® Trace Analyzer would complain about. In the stftool the default is to write these extended records, because the output is more likely to be parsed by scripts rather than by the Intel Trace Analyzer.


Syntax:--logfile-format [ASCII|STF|STFSINGLE|SINGLESTF]


Description: Specifies the format of the tracefile. ASCII is the traditional Vampir* file format where all trace data is written into one file. It is human-readable.

The Structured Trace File (STF) is a binary format which supports storage of trace data in several files and allows Intel® Trace Analyzer to analyze the data without loading all of it, so it is more scalable. Writing it is only supported by Intel® Trace Collector.

One trace in STF format consists of several different files which are referenced by one index file (.stf). The advantage is that different processes can write their data in parallel (see STF-PROCS-PER-FILE, STF-USE-HW-STRUCTURE). SINGLESTF rolls all of these files into one (.single.stf), which can be read without unpacking them again. However, this format does not support distributed writing, so for large program runs with many processes the generic STF format is better.


Syntax:--logfile-name <file name> 

Description: Specifies the name for the tracefile containing all the trace data. Can be an absolute or relative pathname; in the latter case, it is interpreted relative to the log prefix (if set) or the current working directory of the process writing it.

If unspecified, then the name is the name of the program plus .avt for ASCII, .stf for STF and .single.stf for single STF tracefiles. If one of these suffices is used, then they also determine the logfile format, unless the format is specified explicitly.

In the stftool the name has to be specified explicitly, either by using this option or as argument of the --convert or --move switch.




Description: When converting from STF to ASCII-VTF communication records are usually split up into conventional VTF records. If this option is enabled, an extended format is written, which puts all information about the communication into a single line.


Syntax:--merge [<merged trace name>]


Description: Merges the given raw trace. When you use the --merge option with the --delete-raw-data option, such configuration deletes the given raw trace after merging. When you use --merge option with the --sumdata option, such configuration creates additional Summary Data files for the given unmerged trace.


Syntax:--move [<file/dirname>]


Description: Moves the given file without otherwise changing it. The target can be a directory.




Description: Prints the errors that were found in the application.




Description: Lists all components that are part of the given STF file, including their size. This is similar to ls -l, but also works with single-file STF.




Description: Prints the Message Checker reports of the input file to stdout.




Description: Prints the precomputed statistics of the input file to stdout.




Description: Prints information about each native thread that was encountered by the Intel® Trace Collector when generating the trace.




Description: Removes the given file and all of its components.


Syntax:--request <type>, <thread triplets>, <categories>, <window>

Description: Restricts the data written into the new trace to the one that matches the arguments. If a window is given (in the form <timespec>:<timespec> with at least one unit descriptor), data is restricted to this time interval. It has the usual format of a time value, with one exception: the unit for seconds s is required to distinguish it from a thread triplet; in other words, use 10s instead of just 10. The <type> can be any kind of string in single or double quotation marks, but it has to identify uniquely the kind of data. Valid <categories> are FUNCTIONS, SCOPES, FILEIO, COUNTERS, MESSAGES, COLLOPS, ERRORS and REQUESTS.

All of the arguments are optional and default to all threads, all categories and the whole time interval. They can be separated by commas or spaces and it is possible to mix them as desired. This option can be used more than once and then data matching any request is written.


Syntax:--sumdata <output trace name>


Description: Forces creation of additional Summary Data files for the given trace.

You can use the --sumdat option with or without --merge option. Thus, there can be the following three scenarios:

  1. --merge<output trace> Merges the given unmerged trace and creates output merged trace.

  2. --sumdata<output trace> Creates Summary Data files for the given merged trace.

    In this scenario, only Summary Data files is created. No output trace is generated.
  3. --merge --sumdata<output trace> Merges the given unmerged trace; creates output merged trace and the Summary Data files for this output trace.




Description: Setting this option to on lets stftool interpret all timestamps as ticks (rather than seconds, milliseconds and so on). Given time values are converted into seconds and then truncated (floor). The clock ticks are based on the nominal clock period specified by the CLKPERIOD header, just as the time stamps printed by the stftool for events.


Syntax:--verbose [on|off|<level>]


Description: Enables or disables additional output on stderr. <level> is a positive number, with larger numbers enabling more output:

  1. 0 (= off) disables all output

  2. 1 (= on) enables only one final message about generating the result

  3. 2 enables general progress reports by the main process

  4. 3 enables detailed progress reports by the main process

  5. 4 the same, but for all processes (if multiple processes are used at all)

Levels higher than 2 may contain output that only makes sense to the developers of Intel® Trace Collector.