• 2019 Update 3
  • 03/07/2019
  • Public Content
  • Download as PDF
Contents

ticks

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.
    Note
    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.
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

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804