Intel® Trace Analyzer and Collector User and Reference Guide

User Guide

  • 2022.2
  • 08/08/2022
  • Public Content
Contents

stftool Utility Options

convert

Syntax:
--convert [
<filename>
]
Default:
off
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.

delete-raw-data

Syntax:
--delete-raw-data
Default:
off
Description:
 Sub-option to
--merge
. Deletes or removes the given raw trace after merging.

dump

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

extended-vtf

Syntax:
--extended-vtf
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.

logfile-format

Syntax:
--logfile-format [ASCII|STF|STFSINGLE|SINGLESTF]
Default:
STF
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.

logfile-name

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.

matched-vtf

Syntax:
--matched-vtf
Default:
off
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.

merge

Syntax:
--merge [
<merged trace name>
]
Default:
off
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.

move

Syntax:
--move [
<file/dirname>
]
Default:
off
Description:
 Moves the given file without otherwise changing it. The target can be a directory.

print-errors

Syntax:
--print-errors
Default:
off
Description:
 Prints the errors that were found in the application.

print-files

Syntax:
--print-files
Default:
off
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.

print-reports

Syntax:
--print-reports
Default:
off
Description:
 Prints the Message Checker reports of the input file to
stdout
.

print-statistics

Syntax:
--print-statistics
Default:
off
Description:
 Prints the precomputed statistics of the input file to
stdout
.

print-threads

Syntax:
--print-threads
Default:
off
Description:
 Prints information about each native thread that was encountered by the Intel® Trace Collector when generating the trace.

remove

Syntax:
--remove
Default:
off
Description:
 Removes the given file and all of its components.

request

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.

sumdata

Syntax:
--sumdata
<output trace name>
Default:
off
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.

ticks

Syntax:
--ticks
Default:
off
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.

verbose

Syntax:
--verbose [on|off|
<level>
]
Default:
on
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.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.