hpcproftt:
Correlation of Flat Profile Metrics for Teletype Output

The HPCToolkit Performance Tools

2012/04/19

Version 5.4.2

hpcproftt correlates `flat' profile metrics with either source code structure or object code and generates textual output suitable for a terminal. Alternatively, it also generates textual dumps of profile files.

Table of Contents

Synopsis

hpcproftt [--source] [options] profile-file...

hpcproftt --object [options] profile-file...

hpcproftt --dump profile-file...

Description

hpcproftt correlates `flat' profile metrics with either source code structure (the first and default mode) or object code (second mode) and generates textual output suitable for a terminal (hence the tt, for teletype, in its name). In both of these modes, hpcproftt expects a list of flat profile files. hpcproftt also supports a third mode in which it generates textual dumps of profile files. In this mode, the profile list may contain either flat or call path profile files.

hpcproftt defaults to source code correlation mode. Without any mode switch, it behaves as if passed --source=pgm,lm.

Source Source Structure Correlation. First, hpcproftt creates raw metrics for every native event with in each profile file. Derived summary metrics can be optionally created with the --metric option. All metrics are normalized to use the unit 'events' rather than 'samples' since this enables meaningful comparisons and derived metrics. Since percents facilitate rapid comprehension (compared to values), all raw metrics display as percents; derived metrics likewise default to percent, if sensible.

Then, hpcproftt correlates metrics to program structure. If hpcstruct(1) structure information is available, this is used for correlation; if not, a simple 'File | Procedure | Statement' structure is computed using the load module's line map.

Finally, hpcproftt generates metric summaries and annotated source files to standard out. Each metric summary compares a certain source structure element (such as a procedure) with all other elements of that type across the whole program. Structure elements include: Program, Load Module, File, Procedure, Loop (requires hpcstruct(1) ), and Statement. For example, the procedure summary shows (exclusive) metric values for each procedure in the program. (Structure elements are pruned if all corresponding metrics are 0.) Summaries are rank ordered by the first metric. hpcproftt optionally annotates source files with Statement (line) level metrics. Note that it can only annotate files found by combining debug information with --include search paths.

Object Correlation.

hpcproftt's object correlation mode is intended for inspection of fine-grained correlation. In contrast to the source structure correlation mode, true summaries are not computed; rather (like an annotated source file) hpcproftt generates annotated object code, i.e., procedures and instructions. Moreover, only raw metrics corresponding to the native events in one profile file may be correlated to the object code touched by those metrics. Accordingly, hpcproftt creates raw metrics for every native event in one profile file. Metrics use the unit 'samples' rather than 'events' and default to percents, though absolute values may optionally be displayed. Procedures are pruned from the output if no associated metric totals to the provided threshold.

Warnings:

Arguments

profile-file...
A list of flat profile files.

Default values for an option's optional arguments are shown in {}.

Options: General

-v [n], --verbose [n]
Verbose: generate progress messages to stderr at verbosity level n. {1}
-V, --version
Print version information.
-h, --help
Print help.
--debug [n]
Debug: use debug level n. {1}

Options: Source Structure Correlation

--source [=all,sum,pgm,lm,f,p,l,s,src]
--src [=all,sum,pgm,lm,f,p,l,s,src]
Correlate metrics to source code structure. Use the following flags to control which source code structures appear in the output: Without --source, the default set of flags is {pgm,lm}; with --source, the default set is {sum}.

--srcannot glob
Annotate source files with path names that match file glob glob. (Protect glob characters from shell with single quotes or backslash.) May pass multiple times to logically OR additional globs.

-M metric, --metric metric
Specify the set of metrics to compute, where metric is one of the following: Default is 'thread'.

-I dir, --include dir
Use dir as a search directory to find source files. For a recursive search, append a '*' after the last slash, e.g., '/mypath/*' (quote or escape to protect from the shell). May pass multiple times.

Note: With multiple search-directory arguments, it may be the case that file f exists within more than one search directory. In this case, the ambiguity is resolved in favor of the search directory that appears first on the command line.

-S file, --structure file
Use hpcstruct(1) structure file file for correlation. May pass multiple times (e.g., for shared libraries).

-R 'old-path=new-path', --replace-path 'old-path=new-path'
Substitute instances of old-path with new-path; apply to all paths (e.g., a profile's load map and source code) for which old-path is a prefix. Use '\' to escape instances of '=' within a path. May pass multiple times.

Use this option when a profile or binary contains references to files that have been relocated, such as might occur with a file system change.

Options: Object Correlation

--object [=s]
--obj [=s]
Correlate metrics with object code by annotating object code procedures and instructions. {}

--objannot glob
Annotate object procedures with (unmangled) names that match glob glob. (Protect glob characters from shell with single quotes or backslash.) May pass multiple times to logically OR additional globs.

--obj-threshold n
Prune procedures with an event count < n {1}

--obj-values
Show raw metrics as values instead of percents

Options: Dump Raw Profile Data

--dump
Generate textual representation of raw profile data.

Examples

See Also

hpctoolkit(1) .

Version

Version: 5.4.2 of 2012/04/19.

License and Copyright

Copyright
© 2002-2016, Rice University.
License
See README.License.

Authors

Nathan Tallent
Rice HPCToolkit Research Group
Email: hpctoolkit-forum =at= rice.edu
WWW: http://hpctoolkit.org.